speech: add promise support (#1710)

Author: callmehiphop

packages/google-cloud-speech/README.md

@@ -58,6 +58,19 @@ fs.createReadStream('./audio.raw')
     //     ...
     //   }
   });
+
+// Promises are also supported by omitting callbacks.
+speech.recognize('./audio.raw', {
+  encoding: 'LINEAR16',
+  sampleRate: 16000
+}).then(function(data) {
+  var transcript = data[0];
+});
+
+// It's also possible to integrate with third-party Promise libraries.
+var speech = require('@google-cloud/speech')({
+  promise: require('bluebird')
+});
 ```
 
 

packages/google-cloud-speech/package.json

@@ -54,7 +54,7 @@
     "speech"
   ],
   "dependencies": {
-    "@google-cloud/common": "^0.6.0",
+    "@google-cloud/common": "^0.7.0",
     "events-intercept": "^2.0.0",
     "extend": "^3.0.0",
     "google-gax": "^0.7.0",

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

@@ -632,6 +632,14 @@ Speech.prototype.operation = function(name) {
  *   //   }
  *   // ]
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * speech.recognize('./bridge.raw', config).then(function(data) {
+ *   var results = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Speech.prototype.recognize = function(file, config, callback) {
   var self = this;
@@ -764,6 +772,14 @@ Speech.prototype.recognize = function(file, config, callback) {
  *       // ]
  *     });
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * speech.startRecognition('./bridge.raw', config).then(function(data) {
+ *   var operation = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Speech.prototype.startRecognition = function(file, config, callback) {
   var self = this;
@@ -811,5 +827,14 @@ Speech.prototype.startRecognition = function(file, config, callback) {
   });
 };
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(Speech, {
+  exclude: ['operation']
+});
+
 module.exports = Speech;
 module.exports.v1beta1 = v1beta1;

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

@@ -27,7 +27,17 @@ var tmp = require('tmp');
 
 var util = require('@google-cloud/common').util;
 
-var fakeUtil = extend({}, util);
+var promisified = false;
+var fakeUtil = extend({}, util, {
+  promisifyAll: function(Class, options) {
+    if (Class.name !== 'Speech') {
+      return;
+    }
+
+    promisified = true;
+    assert.deepEqual(options.exclude, ['operation']);
+  }
+});
 
 function FakeGrpcOperation() {
   this.calledWith_ = arguments;
@@ -90,6 +100,10 @@ describe('Speech', function() {
   });
 
   describe('instantiation', function() {
+    it('should promisify all the things', function() {
+      assert(promisified);
+    });
+
     it('should normalize the arguments', function() {
       var normalizeArguments = fakeUtil.normalizeArguments;
       var normalizeArgumentsCalled = false;