language: add promise support (#1706)

packages/google-cloud-language/README.md

@@ -18,11 +18,6 @@ var language = require('@google-cloud/language')({
   keyFilename: '/path/to/keyfile.json'
 });
 
-var language = language({
-  projectId: 'grape-spaceship-123',
-  keyFilename: '/path/to/keyfile.json'
-});
-
 // Get the entities from a sentence.
 language.detectEntities('Stephen of Michigan!', function(err, entities) {
   // entities = {
@@ -65,6 +60,16 @@ document.annotate(function(err, annotations) {
   //   ]
   // }
 });
+
+// Promises are also supported by omitting callbacks.
+document.annotate().then(function(data) {
+  var annotations = data[0];
+});
+
+// It's also possible to integrate with third-party Promise libraries.
+var language = require('@google-cloud/language')({
+  promise: require('bluebird')
+});
 ```
 
 

packages/google-cloud-language/package.json

@@ -52,10 +52,11 @@
     "language"
   ],
   "dependencies": {
-    "@google-cloud/common": "^0.6.0",
+    "@google-cloud/common": "^0.7.0",
     "arrify": "^1.0.1",
     "extend": "^3.0.0",
     "google-gax": "^0.7.0",
+    "google-proto-files": "^0.8.3",
     "is": "^3.0.1",
     "propprop": "^0.3.1"
   },

packages/google-cloud-language/src/document.js

@@ -354,6 +354,14 @@ Document.PART_OF_SPEECH = {
  *   //   ]
  *   // }
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * document.annotate().then(function(data) {
+ *   var annotation = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Document.prototype.annotate = function(options, callback) {
   if (is.fn(options)) {
@@ -522,6 +530,14 @@ Document.prototype.annotate = function(options, callback) {
  *   //   ]
  *   // }
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * document.detectEntities().then(function(data) {
+ *   var entities = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Document.prototype.detectEntities = function(options, callback) {
   if (is.fn(options)) {
@@ -588,6 +604,14 @@ Document.prototype.detectEntities = function(options, callback) {
  *   //   magnitude: 40
  *   // }
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * document.detectSentiment().then(function(data) {
+ *   var sentiment = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Document.prototype.detectSentiment = function(options, callback) {
   if (is.fn(options)) {
@@ -754,5 +778,12 @@ Document.sortByProperty_ = function(propertyName) {
   };
 };
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(Document);
+
 module.exports = Document;
 

packages/google-cloud-language/src/index.js

@@ -137,6 +137,14 @@ function Language(options) {
  * };
  *
  * language.annotate('Hello!', options, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * language.annotate('Hello!').then(function(data) {
+ *   var entities = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Language.prototype.annotate = function(content, options, callback) {
   if (is.fn(options)) {
@@ -220,6 +228,14 @@ Language.prototype.annotate = function(content, options, callback) {
  * };
  *
  * language.detectEntities('Axel Foley is from Detroit', options, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * language.detectEntities('Axel Foley is from Detroit').then(function(data) {
+ *   var entities = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Language.prototype.detectEntities = function(content, options, callback) {
   if (is.fn(options)) {
@@ -294,6 +310,14 @@ Language.prototype.detectEntities = function(content, options, callback) {
  * };
  *
  * language.detectSentiment('Hello!', options, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * language.detectSentiment('Hello!').then(function(data) {
+ *   var sentiment = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Language.prototype.detectSentiment = function(content, options, callback) {
   if (is.fn(options)) {
@@ -460,5 +484,14 @@ Language.prototype.text = function(content, options) {
   return this.document(options);
 };
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(Language, {
+  exclude: ['document', 'html', 'text']
+});
+
 module.exports = Language;
 module.exports.v1beta1 = v1beta1;

packages/google-cloud-language/system-test/language.js

@@ -56,7 +56,7 @@ describe('Language', function() {
   });
 
   after(function(done) {
-    GCS.getBuckets({ prefix: TESTS_PREFIX })
+    GCS.getBucketsStream({ prefix: TESTS_PREFIX })
       .on('error', done)
       .pipe(through.obj(function(bucket, _, next) {
         bucket.deleteFiles({ force: true }, function(err) {

packages/google-cloud-language/test/document.js

@@ -23,13 +23,19 @@ var proxyquire = require('proxyquire');
 var util = require('@google-cloud/common').util;
 
 var isCustomTypeOverride;
+var promisified = false;
 var fakeUtil = extend(true, {}, util, {
   isCustomType: function() {
     if (isCustomTypeOverride) {
       return isCustomTypeOverride.apply(null, arguments);
     }
 
     return false;
+  },
+  promisifyAll: function(Class) {
+    if (Class.name === 'Document') {
+      promisified = true;
+    }
   }
 });
 
@@ -70,6 +76,10 @@ describe('Document', function() {
       assert.strictEqual(document.api, LANGUAGE.api);
     });
 
+    it('should promisify all the things', function() {
+      assert(promisified);
+    });
+
     it('should set the correct document for inline content', function() {
       assert.deepEqual(document.document, {
         content: CONFIG,

packages/google-cloud-language/test/index.js

@@ -21,7 +21,17 @@ var extend = require('extend');
 var proxyquire = require('proxyquire');
 var util = require('@google-cloud/common').util;
 
-var fakeUtil = extend(true, {}, util);
+var promisified = false;
+var fakeUtil = extend({}, util, {
+  promisifyAll: function(Class, options) {
+    if (Class.name !== 'Language') {
+      return;
+    }
+
+    promisified = true;
+    assert.deepEqual(options.exclude, ['document', 'html', 'text']);
+  }
+});
 
 function FakeDocument() {
   this.calledWith_ = arguments;
@@ -60,6 +70,10 @@ describe('Language', function() {
   });
 
   describe('instantiation', function() {
+    it('should promisify all the things', function() {
+      assert(promisified);
+    });
+
     it('should normalize the arguments', function() {
       var options = {
         projectId: 'project-id',