language: add note about the version & code style

stephenplusplus · stephenplusplus · commit da82b12bdc16 · 2017-04-11T10:58:51.000-04:00
diff --git a/packages/language/src/index.js b/packages/language/src/index.js
@@ -26,7 +26,7 @@ var is = require('is');
 var v1 = require('./v1');
 var v1beta2 = require('./v1beta2');
 
-var _GAPICS = {
+var GAPIC_APIS = {
   v1: v1,
   v1beta2: v1beta2
 };
@@ -56,8 +56,10 @@ var Document = require('./document.js');
  * @resource [Cloud Natural Language API Documentation]{@link https://cloud.google.com/natural-language/docs}
  *
  * @param {object} options - [Configuration object](#/docs).
- * @param {string} options.apiVersion - API version. Defaults to "v1";
- *   the only other valid value is "v1beta2".
+ * @param {string} options.apiVersion - Either `v1` or `v1beta2`. `v1beta2` is a
+ *     *newer* release than `v1`, and still in beta. By choosing it, you are
+ *     opting into new, back-end behavior which is not officially supported by
+ *     the design of this API. (Default: `v1`)
  */
 function Language(options) {
   if (!(this instanceof Language)) {
@@ -70,14 +72,12 @@ function Language(options) {
     libVersion: require('../package.json').version
   });
 
-  // Determine the version to be used.
-  // We default to "v1", but use "v1beta2" if explicitly requested. Both
-  // GAPICs are packaged with the library.
-  var apiVersion = options.apiVersion || 'v1';
-  var gapic = _GAPICS[apiVersion];
-  if (is.undefined(gapic)) {
-    throw new Error('Invalid api_version: use "v1" or "v1beta2".');
+  var gapic = GAPIC_APIS[options.apiVersion || 'v1'];
+
+  if (!gapic) {
+    throw new Error('Invalid `apiVersion` specified. Use "v1" or "v1beta2".');
   }
+
   delete options.apiVersion;
 
   this.api = {
diff --git a/packages/language/test/index.js b/packages/language/test/index.js
@@ -48,6 +48,17 @@ function fakeV1() {
   };
 }
 
+var fakeV1Beta2Override;
+function fakeV1Beta2() {
+  if (fakeV1Beta2Override) {
+    return fakeV1Beta2Override.apply(null, arguments);
+  }
+
+  return {
+    languageServiceClient: util.noop
+  };
+}
+
 describe('Language', function() {
   var Language;
   var language;
@@ -60,12 +71,14 @@ describe('Language', function() {
         util: fakeUtil
       },
       './document.js': FakeDocument,
-      './v1': fakeV1
+      './v1': fakeV1,
+      './v1beta2': fakeV1Beta2
     });
   });
 
   beforeEach(function() {
     fakeV1Override = null;
+    fakeV1Beta2Override = null;
     language = new Language(OPTIONS);
   });
 
@@ -74,21 +87,6 @@ describe('Language', function() {
       assert(promisified);
     });
 
-    it('should accept an apiVersion "v1beta2"', function() {
-      var RealLanguage = require('../src/index.js');
-
-      // The v1beta2 GAPIC adds a new `analyzeEntitySentiment` function.
-      var langBeta = new RealLanguage({apiVersion: 'v1beta2'});
-      assert.strictEqual(typeof langBeta.api.Language.analyzeEntitySentiment,
-                         'function');
-    });
-
-    it('should not accept an unrecognized version', function() {
-      assert.throws(function() {
-        new Language({apiVersion: 'v1beta42'});
-      });
-    });
-
     it('should normalize the arguments', function() {
       var options = {
         projectId: 'project-id',
@@ -138,6 +136,45 @@ describe('Language', function() {
         Language: expectedLanguageService
       });
     });
+
+    it('should create a gax api client for v1beta2', function() {
+      var expectedLanguageService = {};
+
+      fakeV1Override = function() {
+        throw new Error('v1 should not be initialized.');
+      };
+
+      fakeV1Beta2Override = function(options) {
+        var expected = {
+          libName: 'gccl',
+          libVersion: require('../package.json').version
+        };
+        assert.deepStrictEqual(options, expected);
+
+        return {
+          languageServiceClient: function(options) {
+            assert.deepStrictEqual(options, expected);
+            return expectedLanguageService;
+          }
+        };
+      };
+
+      var language = new Language({
+        apiVersion: 'v1beta2'
+      });
+
+      assert.deepEqual(language.api, {
+        Language: expectedLanguageService
+      });
+    });
+
+    it('should not accept an unrecognized version', function() {
+      assert.throws(function() {
+        new Language({
+          apiVersion: 'v1beta42'
+        });
+      }, new RegExp('Invalid `apiVersion` specified. Use "v1" or "v1beta2".'));
+    });
   });
 
   describe('annotate', function() {
