Merge pull request #1280 from stephenplusplus/spp--1266

callmehiphop · callmehiphop · commit f4e431f04934 · 2016-05-05T15:58:48.000-04:00
datastore: add query.run
diff --git a/lib/datastore/index.js b/lib/datastore/index.js
@@ -395,7 +395,7 @@ Datastore.prototype.createQuery = function(namespace, kind) {
     namespace = this.namespace;
   }
 
-  return new Query(namespace, arrify(kind));
+  return new Query(this, namespace, arrify(kind));
 };
 
 /**
diff --git a/lib/datastore/query.js b/lib/datastore/query.js
@@ -22,11 +22,16 @@
 
 var arrify = require('arrify');
 
+/*! Developer Documentation
+ *
+ * @param {module:datastore|module:transaction} scope - The parent scope the
+ *     query was created from.
+ */
 /**
  * Build a Query object.
  *
- * **Queries should be built with {module:datastore#createQuery} and run via
- * {module:datastore#runQuery}.**
+ * **Queries are built with {module:datastore#createQuery} and
+ * {module:transaction#createQuery}.**
  *
  * @resource [Datastore Queries]{@link http://goo.gl/Cag0r6}
  *
@@ -45,12 +50,14 @@ var arrify = require('arrify');
  * var datastore = gcloud.datastore();
  * var query = datastore.createQuery('AnimalNamespace', 'Lion');
  */
-function Query(namespace, kinds) {
+function Query(scope, namespace, kinds) {
   if (!kinds) {
     kinds = namespace;
     namespace = null;
   }
 
+  this.scope = scope;
+
   this.namespace = namespace || null;
   this.kinds = kinds;
 
@@ -73,15 +80,17 @@ function Query(namespace, kinds) {
  * @return {module:datastore/query}
  *
  * @example
- * // Retrieve a list of people related to person "1234",
- * // disabling auto pagination
+ * //-
+ * // Retrieve a list of people related to "Dave", with auto-pagination
+ * // disabled.
+ * //-
  * var query = datastore.createQuery('Person')
- *   .hasAncestor(datastore.key(['Person', 1234]))
+ *   .hasAncestor(datastore.key(['Person', 'Dave']))
  *   .autoPaginate(false);
  *
  * function callback(err, entities, nextQuery, apiResponse) {
  *   if (nextQuery) {
- *     // More results might exist, so we'll manually fetch them
+ *     // More results might exist, so we'll manually fetch them.
  *     datastore.runQuery(nextQuery, callback);
  *   }
  * }
@@ -103,7 +112,7 @@ Query.prototype.autoPaginate = function(autoPaginateVal) {
  * @resource [Datastore Filters]{@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Filters}
  *
  * @param {string} property - The field name.
- * @param {string=} operator - Operator (=, <, >, <=, >=). Default: `=`.
+ * @param {string=} operator - Operator (=, <, >, <=, >=). Default: `=`
  * @param {*} value - Value to compare property to.
  * @return {module:datastore/query}
  *
@@ -295,4 +304,76 @@ Query.prototype.offset = function(n) {
   return this;
 };
 
+/**
+ * Run the query.
+ *
+ * @param {object=} options - Optional configuration.
+ * @param {string} options.consistency - Specify either `strong` or `eventual`.
+ *     If not specified, default values are chosen by Datastore for the
+ *     operation. Learn more about strong and eventual consistency
+ *     [here](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore).
+ * @param {function=} callback - The callback function. If omitted, a readable
+ *     stream instance is returned.
+ * @param {?error} callback.err - An error returned while making this request
+ * @param {object[]} callback.entities - A list of entities.
+ * @param {?object} callback.nextQuery - If present, query with this object to
+ *     check for more results.
+ * @param {object} callback.apiResponse - The full API response.
+ *
+ * @example
+ * query.run(function(err, entities) {});
+ *
+ * //-
+ * // To control how many API requests are made and page through the results
+ * // manually, call `autoPaginate(false)` on your query.
+ * //-
+ * query.autoPaginate(false);
+ *
+ * function callback(err, entities, nextQuery, apiResponse) {
+ *   if (nextQuery) {
+ *     // More results might exist.
+ *     nextQuery.run(callback);
+ *   }
+ * }
+ *
+ * query.run(callback);
+ *
+ * //-
+ * // If you omit the callback, `run` will automatically call subsequent queries
+ * // until no results remain. Entity objects will be pushed as they are found.
+ * //-
+ * query.run()
+ *   .on('error', console.error)
+ *   .on('data', function (entity) {})
+ *   .on('end', function() {
+ *     // All entities retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * query.run()
+ *   .on('data', function (entity) {
+ *     this.end();
+ *   });
+ *
+ * //-
+ * // A keys-only query returns just the keys of the result entities instead of
+ * // the entities themselves, at lower latency and cost.
+ * //-
+ * query.select('__key__');
+ *
+ * query.run(function(err, entities) {
+ *   // entities[].key = Key object
+ *   // entities[].data = Empty object
+ * });
+ */
+Query.prototype.run = function() {
+  var query = this;
+  var args = [query].concat([].slice.call(arguments));
+
+  return this.scope.runQuery.apply(this.scope, args);
+};
+
 module.exports = Query;
diff --git a/lib/datastore/request.js b/lib/datastore/request.js
@@ -388,15 +388,7 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  * @param {function=} callback - The callback function. If omitted, a readable
  *     stream instance is returned.
  * @param {?error} callback.err - An error returned while making this request
- *     (may be null).
- * @param {array} callback.entities - The list of entities returned by this
- *     query. Note that this is a single page of entities, not necessarily
- *     all of the entities.
- * @param {?module:datastore/query} callback.nextQuery - If present, run another
- *     query with this object to check for more results.
- * @param {object} callback.apiResponse - The full API response.
- * @param {?error} callback.err - An error returned while making this request
- * @param {module:datastore/entity[]} callback.entities - A list of Entities
+ * @param {object[]} callback.entities - A list of entities.
  * @param {?object} callback.nextQuery - If present, query with this object to
  *     check for more results.
  * @param {object} callback.apiResponse - The full API response.
diff --git a/lib/datastore/transaction.js b/lib/datastore/transaction.js
@@ -71,6 +71,8 @@ var util = require('../common/util.js');
  * }, function(err) {});
  */
 function Transaction(datastore) {
+  this.datastore = datastore;
+
   this.projectId = datastore.projectId;
 
   this.request = datastore.request.bind(datastore);
@@ -96,6 +98,31 @@ nodeutil.inherits(Transaction, DatastoreRequest);
  *   B) we build up a "modifiedEntities_" array on this object, used to build
  *      the final commit request with.
  */
+
+/**
+ * Create a query for the specified kind. See {module:datastore/query} for all
+ * of the available methods.
+ *
+ * @resource [Datastore Queries]{@link https://cloud.google.com/datastore/docs/concepts/queries}
+ *
+ * @see {module:datastore/query}
+ *
+ * @param {string=} namespace - Namespace.
+ * @param {string} kind - The kind to query.
+ * @return {module:datastore/query}
+ *
+ * @example
+ * datastore.runInTransaction(function(transaction, done) {
+ *   var query = transaction.createQuery('Company');
+ *
+ *   // Run the query inside the transaction.
+ *   query.run(function(err, entities) {});
+ * });
+ */
+Transaction.prototype.createQuery = function() {
+  return this.datastore.createQuery.apply(this, arguments);
+};
+
 /**
  * Delete all entities identified with the specified key(s) in the current
  * transaction.
@@ -134,7 +161,7 @@ Transaction.prototype.delete = function(entities) {
  * Reverse a transaction remotely and finalize the current transaction instance.
  *
  * @param {function} callback - The callback function.
- * @param {?error} callback.err - An error returned while making this request
+ * @param {?error} callback.err - An error returned while making this request.
  * @param {object} callback.apiResponse - The full API response.
  *
  * @example
diff --git a/system-test/datastore.js b/system-test/datastore.js
@@ -641,6 +641,12 @@ describe('Datastore', function() {
         done();
       });
     });
+
+    it('should query from the Query object', function(done) {
+      var q = datastore.createQuery('Character');
+
+      q.run(done);
+    });
   });
 
   describe('transactions', function() {
@@ -758,5 +764,21 @@ describe('Datastore', function() {
         });
       });
     });
+
+    it('should query within a transaction', function(done) {
+      datastore.runInTransaction(function(t, tDone) {
+        var query = t.createQuery('Company');
+
+        query.run(function(err, entities) {
+          if (err) {
+            tDone(err);
+            return;
+          }
+
+          assert(entities.length > 0);
+          tDone();
+        });
+      }, done);
+    });
   });
 });
diff --git a/test/datastore/index.js b/test/datastore/index.js
@@ -191,32 +191,25 @@ describe('Datastore', function() {
   });
 
   describe('createQuery', function() {
-    var dsWithoutNamespace;
-
-    beforeEach(function() {
-      dsWithoutNamespace = new Datastore({
-        projectId: 'test',
-        namespace: 'my-ns'
-      });
-    });
-
     it('should return a Query object', function() {
       var namespace = 'namespace';
       var kind = ['Kind'];
 
       var query = datastore.createQuery(namespace, kind);
       assert(query instanceof FakeQuery);
 
-      assert.strictEqual(query.calledWith_[0], namespace);
-      assert.deepEqual(query.calledWith_[1], kind);
+      assert.strictEqual(query.calledWith_[0], datastore);
+      assert.strictEqual(query.calledWith_[1], namespace);
+      assert.deepEqual(query.calledWith_[2], kind);
     });
 
     it('should include the default namespace', function() {
       var kind = ['Kind'];
       var query = datastore.createQuery(kind);
 
-      assert.strictEqual(query.calledWith_[0], datastore.namespace);
-      assert.deepEqual(query.calledWith_[1], kind);
+      assert.strictEqual(query.calledWith_[0], datastore);
+      assert.strictEqual(query.calledWith_[1], datastore.namespace);
+      assert.deepEqual(query.calledWith_[2], kind);
     });
   });
 
diff --git a/test/datastore/query.js b/test/datastore/query.js
@@ -17,30 +17,46 @@
 'use strict';
 
 var assert = require('assert');
+
 var Query = require('../../lib/datastore/query.js');
 
 describe('Query', function() {
+  var SCOPE = {};
+  var NAMESPACE = 'Namespace';
+  var KINDS = 'Kind';
+
+  var query;
+
+  beforeEach(function() {
+    query = new Query(SCOPE, NAMESPACE, KINDS);
+  });
+
   describe('instantiation', function() {
+    it('should localize the scope', function() {
+      assert.strictEqual(query.scope, SCOPE);
+    });
+
+    it('should localize the namespace', function() {
+      assert.strictEqual(query.namespace, NAMESPACE);
+    });
+
+    it('should localize the kind', function() {
+      assert.strictEqual(query.kinds, KINDS);
+    });
+
     it('should use null for all falsy namespace values', function() {
       [
-        new Query('', 'Kind'),
-        new Query(null, 'Kind'),
-        new Query(undefined, 'Kind'),
-        new Query(0, 'Kind'),
-        new Query('Kind')
+        new Query(SCOPE, '', KINDS),
+        new Query(SCOPE, null, KINDS),
+        new Query(SCOPE, undefined, KINDS),
+        new Query(SCOPE, 0, KINDS),
+        new Query(SCOPE, KINDS)
       ].forEach(function(query) {
         assert.strictEqual(query.namespace, null);
-        assert.equal(query.kinds, 'Kind');
       });
     });
 
-    it('should support custom namespaces', function() {
-      var query = new Query('ns', ['kind1']);
-      assert.equal(query.namespace, 'ns');
-    });
-
     it('should enable auto pagination by default', function() {
-      var query = new Query(['kind1']);
       assert.strictEqual(query.autoPaginateVal, true);
     });
   });
@@ -301,4 +317,23 @@ describe('Query', function() {
       assert.strictEqual(query, nextQuery);
     });
   });
+
+  describe('run', function() {
+    it('should call the parent instance runQuery correctly', function() {
+      var args = [0, 1, 2];
+      var runQueryReturnValue = {};
+
+      query.scope.runQuery = function() {
+        assert.strictEqual(this, query.scope);
+        assert.strictEqual(arguments[0], query);
+        assert.strictEqual(arguments[1], args[0]);
+        assert.strictEqual(arguments[2], args[1]);
+        assert.strictEqual(arguments[3], args[2]);
+        return runQueryReturnValue;
+      };
+
+      var results = query.run.apply(query, args);
+      assert.strictEqual(results, runQueryReturnValue);
+    });
+  });
 });
diff --git a/test/datastore/transaction.js b/test/datastore/transaction.js

Original file line number	Diff line number	Diff line change
`@@ -395,7 +395,7 @@ Datastore.prototype.createQuery = function(namespace, kind) {`
`395`	`395`	`namespace = this.namespace;`
`396`	`396`	`}`
`397`	`397`
`398`		`- return new Query(namespace, arrify(kind));`
	`398`	`+ return new Query(this, namespace, arrify(kind));`
`399`	`399`	`};`
`400`	`400`
`401`	`401`	`/**`