Add arbitrary request options to single-feature helpers. (#2555)

Author: lukesneeringer

packages/google-cloud-vision/src/helpers.js

@@ -74,11 +74,22 @@ var coerceImage = (image, callback) => {
  *   asking for the single feature annotation.
  */
 var _createSingleFeatureMethod = featureValue => {
-  return function(image, options) {
-    return this.annotateImage({
-      image: image,
-      features: [{type: featureValue}],
-    }, options);
+  return function(annotateImageRequest, callOptions) {
+    annotateImageRequest.features = annotateImageRequest.features || [{
+      type: featureValue,
+    }];
+    // If the user submitted explicit features that do not line up with
+    // the precise method called, throw an exception.
+    for (let feature of annotateImageRequest.features) {
+      if (feature.type !== featureValue) {
+        throw new Error(
+          'Setting explicit features is not supported on this method. ' +
+          'Use the #annotateImage method instead.'
+        );
+      }
+    }
+    // Call the underlying #annotateImage method.
+    return this.annotateImage(annotateImageRequest, callOptions);
   };
 };
 
@@ -98,9 +109,10 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with the requested features.
    *
-   * @param {Object=} request
+   * @param {Object} request
    *   A representation of the request being sent to the Vision API.
-   * @param {Object=} request.image
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
@@ -110,7 +122,10 @@ module.exports = apiVersion => {
    *   If the key is `content`, the value should be a Buffer.
    * @param {Array} request.features
    *   An array of the specific annotation features being requested.
-   * @param {Object=} options
+   *   This should take a form such as:
+   *     [{type: vision.types.Feature.Type.FACE_DETECTION},
+   *      {type: vision.types.Feature.Type.WEB_DETECTION}]
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -137,12 +152,12 @@ module.exports = apiVersion => {
    *   console.error(err);
    * });
    */
-  methods.annotateImage = promisify(function(request, options, callback) {
+  methods.annotateImage = promisify(function(request, callOptions, callback) {
     // If a callback was provided and options were skipped, normalize
     // the argument names.
-    if (is.undefined(callback) && is.function(options)) {
-      callback = options;
-      options = undefined;
+    if (is.undefined(callback) && is.function(callOptions)) {
+      callback = callOptions;
+      callOptions = undefined;
     }
 
     // If there is no image, throw an exception.
@@ -159,7 +174,7 @@ module.exports = apiVersion => {
       request.image = image;
 
       // Call the GAPIC batch annotation function.
-      return this.batchAnnotateImages([request], options, (err, r) => {
+      return this.batchAnnotateImages([request], callOptions, (err, r) => {
         // If there is an error, handle it.
         if (err) {
           return callback(err);
@@ -187,15 +202,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with face detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -227,15 +245,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with landmark detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -267,15 +288,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with logo detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -307,15 +331,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with label detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -347,15 +374,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with text detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -387,15 +417,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with document text detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -427,15 +460,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with safe search detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -467,15 +503,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with image properties.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -507,15 +546,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with crop hints.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}
@@ -547,15 +589,18 @@ module.exports = apiVersion => {
   /**
    * Annotate a single image with web detection.
    *
-   * @param {Object=} image
+   * @param {Object} request
+   *   A representation of the request being sent to the Vision API.
+   *   This is an [AnnotateImageRequest]{@link AnnotateImageRequest}.
+   * @param {Object} request.image
    *   A dictionary-like object representing the image. This should have a
    *   single key (`source`, `content`).
    *
    *   If the key is `source`, the value should be another object containing
    *   `imageUri` or `filename` as a key and a string as a value.
    *
    *   If the key is `content`, the value should be a Buffer.
-   * @param {Object=} options
+   * @param {Object=} callOptions
    *   Optional parameters. You can override the default settings for this
    *   call, e.g, timeout, retries, paginations, etc. See
    *   [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions}

packages/google-cloud-vision/test/helpers.test.js

@@ -260,8 +260,8 @@ describe('Vision helper methods', () => {
 
       // Ensure that the annotateImage method does *not* pass the callback
       // on to batchAnnotateImages, but rather handles it itself.
-      var image = {content: new Buffer('bogus==')};
-      return vision.logoDetection(image).then(r => {
+      var imageRequest = {image: {content: new Buffer('bogus==')}};
+      return vision.logoDetection(Object.assign({}, imageRequest)).then(r => {
         var response = r[0];
 
         // Ensure that we got the slice of the response that we expected.
@@ -272,12 +272,26 @@ describe('Vision helper methods', () => {
         // Inspect the calls to annotateImage and batchAnnotateImages and
         // ensure they matched the expected signature.
         assert(annotate.callCount === 1);
-        assert(annotate.calledWith({image: image, features: [{type: 3}]}));
+        assert(annotate.calledWith({
+          features: [{type: 3}],
+          image: imageRequest.image,
+        }));
         assert(batchAnnotate.callCount === 1);
         assert(batchAnnotate.calledWith(
-          [{image: image, features: [{type: 3}]}]
+          [{image: imageRequest.image, features: [{type: 3}]}]
         ));
       });
     });
+
+    it('throws an exception if conflicting features are given', () => {
+      var vision = Vision.v1();
+      var imageRequest = {
+        image: {content: new Buffer('bogus==')},
+        features: [{type: 0}],
+      };
+      vision.logoDetection(imageRequest).then(assert.fail).catch(ex => {
+        assert(ex.message.indexOf('Setting explicit') > -1);
+      });
+    });
   });
 });