translate: add promise support (#1711)

packages/google-cloud-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')
+});
 ```
 
 

packages/google-cloud-translate/package.json

@@ -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",

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

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

@@ -22,13 +22,19 @@ var proxyquire = require('proxyquire');
 var util = require('@google-cloud/common').util;
 
 var makeRequestOverride;
+var promisified = false;
 var fakeUtil = extend({}, util, {
  makeRequest: function() {
  if (makeRequestOverride) {
  return makeRequestOverride.apply(null, arguments);
  }
 
  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;