diff --git a/package.json b/package.json index 2263f44e9f0..56e432dd8ee 100644 --- a/package.json +++ b/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", diff --git a/packages/speech/README.md b/packages/speech/README.md index 01693602322..8f47b7efec7 100644 --- a/packages/speech/README.md +++ b/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') +}); ``` diff --git a/packages/speech/package.json b/packages/speech/package.json index 70c5427274f..6f5771f4309 100644 --- a/packages/speech/package.json +++ b/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", diff --git a/packages/speech/src/index.js b/packages/speech/src/index.js index a312aa9feb7..ec6f9c7a38e 100644 --- a/packages/speech/src/index.js +++ b/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; diff --git a/packages/speech/test/index.js b/packages/speech/test/index.js index 1ebc4d1e1df..e1b414f1a77 100644 --- a/packages/speech/test/index.js +++ b/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; diff --git a/packages/translate/README.md b/packages/translate/README.md index 759c8c55f58..1dd0bd1f568 100644 --- a/packages/translate/README.md +++ b/packages/translate/README.md @@ -46,6 +46,16 @@ translate.getLanguages(function(err, languages) { // ] } }); + +// Promises are also supported by omitting callbacks. +translate.getLanguages().then(function(data) { + var languages = data[0]; +}); + +// It's also possible to integrate with third-party Promise libraries. +var translate = require('@google-cloud/translate')({ + promise: require('bluebird') +}); ``` diff --git a/packages/translate/package.json b/packages/translate/package.json index 88b48402079..86bdb73e7e1 100644 --- a/packages/translate/package.json +++ b/packages/translate/package.json @@ -1,6 +1,6 @@ { "name": "@google-cloud/translate", - "version": "0.3.0", + "version": "0.4.0", "author": "Google Inc.", "description": "Google Translate API Client Library for Node.js", "contributors": [ @@ -50,7 +50,7 @@ "translate" ], "dependencies": { - "@google-cloud/common": "^0.6.0", + "@google-cloud/common": "^0.7.0", "arrify": "^1.0.0", "extend": "^3.0.0", "is": "^3.0.1", diff --git a/packages/translate/src/index.js b/packages/translate/src/index.js index 03259af202b..457a18540fb 100644 --- a/packages/translate/src/index.js +++ b/packages/translate/src/index.js @@ -101,8 +101,6 @@ function Translate(options) { * @param {number=} callback.results[].confidence - A float 0 - 1. The higher * the number, the higher the confidence in language detection. Note, this * is not always returned from the API. - * @param {string} callback.input - The original input that this was result was - * based on. * @param {object} callback.apiResponse - Raw API response. * * @example @@ -142,6 +140,14 @@ function Translate(options) { * // ] * } * }); + * + * //- + * // If the callback is omitted, we'll return a Promise. + * //- + * translate.detect('Hello').then(function(data) { + * var results = data[0]; + * var apiResponse = data[2]; + * }); */ Translate.prototype.detect = function(input, callback) { input = arrify(input); @@ -237,6 +243,14 @@ Translate.prototype.detect = function(input, callback) { * // ] * } * }); + * + * //- + * // If the callback is omitted, we'll return a Promise. + * //- + * translate.getLanguages().then(function(data) { + * var languages = data[0]; + * var apiResponse = data[1]; + * }); */ Translate.prototype.getLanguages = function(target, callback) { if (is.fn(target)) { @@ -340,6 +354,14 @@ Translate.prototype.getLanguages = function(target, callback) { * // ] * } * }); + * + * //- + * // If the callback is omitted, we'll return a Promise. + * //- + * translate.translate('Hello', 'es').then(function(data) { + * var translation = data[0]; + * var apiResponse = data[1]; + * }); */ Translate.prototype.translate = function(input, options, callback) { input = arrify(input); @@ -411,4 +433,11 @@ Translate.prototype.request = function(reqOpts, callback) { common.util.makeRequest(reqOpts, this.options, callback); }; +/*! Developer Documentation + * + * All async methods (except for streams) will return a Promise in the event + * that a callback is omitted. + */ +common.util.promisifyAll(Translate); + module.exports = Translate; diff --git a/packages/translate/test/index.js b/packages/translate/test/index.js index b0a3470211e..76223bdf6cb 100644 --- a/packages/translate/test/index.js +++ b/packages/translate/test/index.js @@ -22,6 +22,7 @@ var proxyquire = require('proxyquire'); var util = require('@google-cloud/common').util; var makeRequestOverride; +var promisified = false; var fakeUtil = extend({}, util, { makeRequest: function() { if (makeRequestOverride) { @@ -29,6 +30,11 @@ var fakeUtil = extend({}, util, { } return util.makeRequest.apply(null, arguments); + }, + promisifyAll: function(Class) { + if (Class.name === 'Translate') { + promisified = true; + } } }); @@ -55,6 +61,10 @@ describe('Translate', 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; diff --git a/test/docs.js b/test/docs.js index 262b51d08a2..db0949f06c2 100644 --- a/test/docs.js +++ b/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({