Add setAncestor

Adds a new setAncestor method for ensuring only one ancestor is set for the query at a time. This will avoid errors that result because of setting multiple ancestors. Also deprecate hasAncestor because it will lead to warnings like this. Add parser logic to use the value provided in setAncestor for query sent to backend.

Author: danieljbruce

src/entity.ts

@@ -1247,6 +1247,11 @@ export namespace entity {
           ? filter
           : new PropertyFilter(filter.name, filter.op, filter.val);
       });
+      if (typeof query.ancestor !== 'undefined') {
+        filters.push(
+          new PropertyFilter('__key__', 'HAS_ANCESTOR', query.ancestor)
+        );
+      }
       queryProto.filter = Filter.AND(filters).toProto();
     }
 

src/query.ts

@@ -73,6 +73,7 @@ export interface Filter {
  * ```
  */
 class Query {
+  ancestor?: Key;
   scope?: Datastore | Transaction;
   namespace?: string | null;
   kinds: string[];
@@ -246,12 +247,36 @@ class Query {
    * const query = datastore.createQuery('MyKind');
    * const ancestoryQuery = query.hasAncestor(datastore.key(['Parent', 123]));
    * ```
+   *
+   * @deprecated Use setAncestor().
    */
   hasAncestor(key: Key) {
     this.filters.push({name: '__key__', op: 'HAS_ANCESTOR', val: key});
     return this;
   }
 
+  /**
+   * Filter a query by ancestors.
+   *
+   * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-ancestor-query-nodejs| Datastore Ancestor Filters}
+   *
+   * @param {Key} key Key object to filter by.
+   * @returns {Query}
+   *
+   * @example
+   * ```
+   * const {Datastore} = require('@google-cloud/datastore');
+   * const datastore = new Datastore();
+   * const query = datastore.createQuery('MyKind');
+   * const ancestorQuery = query.setAncestor(datastore.key(['Parent', 123]));
+   * ```
+   *
+   */
+  setAncestor(key: Key) {
+    this.ancestor = key;
+    return this;
+  }
+
   /**
    * Sort the results by a property name in ascending or descending order. By
    * default, an ascending sort order will be used.