speech: add promise support (#1710)

package.json

@@ -20,6 +20,7 @@
     "mitm": "^1.1.0",
     "mkdirp": "^0.5.1",
     "mocha": "^2.5.3",
+    "multiline": "^1.0.2",
     "package-json": "^2.4.0",
     "propprop": "^0.3.1",
     "proxyquire": "^1.7.10",

packages/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/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/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/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;

test/docs.js

@@ -21,6 +21,7 @@ var format = require('string-format-obj');
 var fs = require('fs');
 var glob = require('glob');
 var mitm = require('mitm');
+var multiline = require('multiline');
 var overviews = require('../scripts/docs/config').OVERVIEW;
 var path = require('path');
 var prop = require('propprop');
@@ -175,7 +176,18 @@ function getDocs(mod) {
 function createInstantiationCode(mod) {
   var config = overviews[mod] || {};
 
-  return format('var {instanceName} = require(\'{path}\')({config});', {
+  return format(multiline.stripIndent(function() {/*
+    var {instanceName} = require('{path}')({config});
+
+    var api = {instanceName}.api;
+    if (api) {
+      Object.keys(api).forEach(function(apiName) {
+        Object.keys(api[apiName]).forEach(function(method) {
+          api[apiName][method] = function() {};
+        });
+      });
+    }
+  */}), {
     instanceName: config.instanceName || mod,
     path: '../packages/' + mod,
     config: JSON.stringify({