feat: introduce EntityFilter class with support for and/or filters

src/entity.ts

@@ -21,6 +21,7 @@ import {PathType} from '.';
 import {protobuf as Protobuf} from 'google-gax';
 import * as path from 'path';
 import {google} from '../protos/protos';
+import {Filter, isFilter, PropertyFilter} from './filter';
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace entity {
@@ -1186,18 +1187,6 @@ export namespace entity {
    * ```
    */
   export function queryToQueryProto(query: Query): QueryProto {
-    const OP_TO_OPERATOR = {
-      '=': 'EQUAL',
-      '>': 'GREATER_THAN',
-      '>=': 'GREATER_THAN_OR_EQUAL',
-      '<': 'LESS_THAN',
-      '<=': 'LESS_THAN_OR_EQUAL',
-      HAS_ANCESTOR: 'HAS_ANCESTOR',
-      '!=': 'NOT_EQUAL',
-      IN: 'IN',
-      NOT_IN: 'NOT_IN',
-    };
-
     const SIGN_TO_ORDER = {
       '-': 'DESCENDING',
       '+': 'ASCENDING',
@@ -1254,32 +1243,11 @@ export namespace entity {
 
     if (query.filters.length > 0) {
       const filters = query.filters.map(filter => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        let value: any = {};
-
-        if (filter.name === '__key__') {
-          value.keyValue = entity.keyToKeyProto(filter.val);
-        } else {
-          value = entity.encodeValue(filter.val, filter.name);
-        }
-
-        return {
-          propertyFilter: {
-            property: {
-              name: filter.name,
-            },
-            op: OP_TO_OPERATOR[filter.op],
-            value,
-          },
-        };
+        return isFilter(filter)
+          ? filter
+          : new PropertyFilter(filter.name, filter.op, filter.val);
       });
-
-      queryProto.filter = {
-        compositeFilter: {
-          filters,
-          op: 'AND',
-        },
-      };
+      queryProto.filter = Filter.AND(filters).toProto();
     }
 
     return queryProto;

src/filter.ts

@@ -0,0 +1,158 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {Operator, Filter as IFilter} from './query';
+import {entity} from './entity';
+
+enum CompositeOperator {
+  AND = 'AND',
+  OR = 'OR',
+}
+
+/**
+ * A Filter is a class that contains data for a filter that can be translated
+ * into a proto when needed.
+ *
+ * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#filters| Filters Reference}
+ *
+ */
+export abstract class Filter {
+  static AND(filters: Filter[]): CompositeFilter {
+    return new CompositeFilter(filters, CompositeOperator.AND);
+  }
+
+  static OR(filters: Filter[]): CompositeFilter {
+    return new CompositeFilter(filters, CompositeOperator.OR);
+  }
+  /**
+   * Gets the proto for the filter.
+   *
+   */
+  // eslint-disable-next-line
+  abstract toProto(): any;
+}
+
+/**
+ * A PropertyFilter is a filter that gets applied to a query directly.
+ *
+ * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#property_filters| Property filters Reference}
+ *
+ * @class
+ */
+export class PropertyFilter extends Filter implements IFilter {
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  val: any;
+  op: Operator;
+
+  /**
+   * Build a Property Filter object.
+   *
+   * @param {string} Property
+   * @param {Operator} operator
+   * @param {any} val
+   */
+  constructor(property: string, operator: Operator, val: any) {
+    super();
+    this.name = property;
+    this.op = operator;
+    this.val = val;
+  }
+
+  private encodedValue(): any {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let value: any = {};
+    if (this.name === '__key__') {
+      value.keyValue = entity.keyToKeyProto(this.val);
+    } else {
+      value = entity.encodeValue(this.val, this.name);
+    }
+    return value;
+  }
+
+  /**
+   * Gets the proto for the filter.
+   *
+   */
+  // eslint-disable-next-line
+  toProto(): any {
+    const OP_TO_OPERATOR = new Map([
+      ['=', 'EQUAL'],
+      ['>', 'GREATER_THAN'],
+      ['>=', 'GREATER_THAN_OR_EQUAL'],
+      ['<', 'LESS_THAN'],
+      ['<=', 'LESS_THAN_OR_EQUAL'],
+      ['HAS_ANCESTOR', 'HAS_ANCESTOR'],
+      ['!=', 'NOT_EQUAL'],
+      ['IN', 'IN'],
+      ['NOT_IN', 'NOT_IN'],
+    ]);
+    const value = new PropertyFilter(
+      this.name,
+      this.op,
+      this.val
+    ).encodedValue();
+    return {
+      propertyFilter: {
+        property: {
+          name: this.name,
+        },
+        op: OP_TO_OPERATOR.get(this.op),
+        value,
+      },
+    };
+  }
+}
+
+/**
+ * A CompositeFilter is a filter that combines other filters and applies that
+ * combination to a query.
+ *
+ * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#composite_filters| Composite filters Reference}
+ *
+ * @class
+ */
+class CompositeFilter extends Filter {
+  filters: Filter[];
+  op: string;
+
+  /**
+   * Build a Composite Filter object.
+   *
+   * @param {Filter[]} filters
+   */
+  constructor(filters: Filter[], op: CompositeOperator) {
+    super();
+    this.filters = filters;
+    this.op = op;
+  }
+
+  /**
+   * Gets the proto for the filter.
+   *
+   */
+  // eslint-disable-next-line
+  toProto(): any {
+    return {
+      compositeFilter: {
+        filters: this.filters.map(filter => filter.toProto()),
+        op: this.op,
+      },
+    };
+  }
+}
+
+export function isFilter(filter: any): filter is Filter {
+  return (filter as Filter).toProto !== undefined;
+}

src/query.ts

@@ -18,10 +18,11 @@ import arrify = require('arrify');
 import {Key} from 'readline';
 import {Datastore} from '.';
 import {Entity} from './entity';
+import {Filter as NewFilter, isFilter} from './filter';
 import {Transaction} from './transaction';
 import {CallOptions} from 'google-gax';
 import {RunQueryStreamOptions} from '../src/request';
-import {AggregateField, AggregateQuery} from './aggregate';
+import {string} from 'is';
 
 export type Operator =
   | '='
@@ -75,7 +76,7 @@ class Query {
   scope?: Datastore | Transaction;
   namespace?: string | null;
   kinds: string[];
-  filters: Filter[];
+  filters: (Filter | NewFilter)[];
   orders: Order[];
   groupByVal: Array<{}>;
   selectVal: Array<{}>;
@@ -170,7 +171,7 @@ class Query {
    *
    * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-property-filter-nodejs| Datastore Filters}
    *
-   * @param {string} property The field name.
+   * @param {string | NewFilter} propertyOrFilter The field name.
    * @param {string} [operator="="] Operator (=, <, >, <=, >=).
    * @param {*} value Value to compare property to.
    * @returns {Query}
@@ -201,20 +202,29 @@ class Query {
    * const keyQuery = query.filter('__key__', key);
    * ```
    */
-  filter(property: string, value: {}): Query;
-  filter(property: string, operator: Operator, value: {}): Query;
-  filter(property: string, operatorOrValue: Operator, value?: {}): Query {
-    let operator = operatorOrValue as Operator;
-    if (arguments.length === 2) {
-      value = operatorOrValue as {};
-      operator = '=';
-    }
+  filter(propertyOrFilter: string | NewFilter, value?: {}): Query;
+  filter(propertyOrFilter: string, operator: Operator, value: {}): Query;
+  filter(
+    propertyOrFilter: string | NewFilter,
+    operatorOrValue?: Operator,
+    value?: {}
+  ): Query {
+    if (isFilter(propertyOrFilter)) {
+      this.filters.push(propertyOrFilter);
+      return this;
+    } else {
+      let operator = operatorOrValue as Operator;
+      if (arguments.length === 2) {
+        value = operatorOrValue as {};
+        operator = '=';
+      }
 
-    this.filters.push({
-      name: property.trim(),
-      op: operator.trim() as Operator,
-      val: value,
-    });
+      this.filters.push({
+        name: (propertyOrFilter as String).trim(),
+        op: operator.trim() as Operator,
+        val: value,
+      });
+    }
     return this;
   }
 

system-test/data/index.yaml

@@ -16,6 +16,12 @@ indexes:
   - name: family
   - name: appearances
 
+- kind: Character
+  ancestor: no
+  properties:
+  - name: family
+  - name: appearances
+
 - kind: Character
   ancestor: yes
   properties: