fix!: don't unwrap int, double by default, add a warning when a number is autoconverted to double or int

src/entity.ts

@@ -52,27 +52,44 @@ export namespace entity {
    * provided.
    *
    * @class
-   * @param {number} value The double value.
+   * @param {number|string} value The double value.
    *
    * @example
    * const {Datastore} = require('@google-cloud/datastore');
    * const datastore = new Datastore();
    * const aDouble = datastore.double(7.3);
    */
-  export class Double {
+  export class Double extends Number {
+    private _entityPropertyName: string | undefined;
     type: string;
     value: number;
-    constructor(value: number) {
+    constructor(value: number | string | ValueProto) {
+      super(typeof value === 'object' ? value.doubleValue : value);
+
       /**
        * @name Double#type
        * @type {string}
        */
       this.type = 'DatastoreDouble';
+
+      this._entityPropertyName =
+        typeof value === 'object' ? value.propertyName : undefined;
+
       /**
        * @name Double#value
        * @type {number}
        */
-      this.value = value;
+      this.value =
+        typeof value === 'object' ? Number(value.doubleValue) : Number(value);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    valueOf(): any {
+      return Number(this.value);
+    }
+
+    toJSON(): any {
+      return {type: this.type, value: this.value};
     }
   }
 
@@ -475,7 +492,7 @@ export namespace entity {
    *
    * @private
    * @param {object} valueProto The protobuf Value message to convert.
-   * @param {boolean | IntegerTypeCastOptions} [wrapNumbers=false] Wrap values of integerValue type in
+   * @param {boolean | IntegerTypeCastOptions} [wrapNumbers=true] Wrap values of integerValue type in
    *     {@link Datastore#Int} objects.
    *     If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
    *     If an `object`, this will return a value returned by
@@ -523,10 +540,21 @@ export namespace entity {
       }
 
       case 'doubleValue': {
+        if (wrapNumbers === undefined) {
+          wrapNumbers = true;
+        }
+
+        if (wrapNumbers) {
+          return new entity.Double(valueProto);
+        }
         return Number(value);
       }
 
       case 'integerValue': {
+        if (wrapNumbers === undefined) {
+          wrapNumbers = true;
+        }
+
         return wrapNumbers
           ? typeof wrapNumbers === 'object'
             ? new entity.Int(valueProto, wrapNumbers).valueOf()
@@ -580,23 +608,6 @@ export namespace entity {
       return valueProto;
     }
 
-    if (typeof value === 'number') {
-      if (Number.isInteger(value)) {
-        if (!Number.isSafeInteger(value)) {
-          process.emitWarning(
-            'IntegerOutOfBoundsWarning: ' +
-              "the value for '" +
-              property +
-              "' property is outside of bounds of a JavaScript Number.\n" +
-              "Use 'Datastore.int(<integer_value_as_string>)' to preserve accuracy during the upload."
-          );
-        }
-        value = new entity.Int(value);
-      } else {
-        value = new entity.Double(value);
-      }
-    }
-
     if (isDsInt(value)) {
       valueProto.integerValue = value.value;
       return valueProto;
@@ -607,6 +618,39 @@ export namespace entity {
       return valueProto;
     }
 
+    if (typeof value === 'number') {
+      const integerOutOfBoundsWarning =
+        "IntegerOutOfBoundsWarning: the value for '" +
+        property +
+        "' property is outside of bounds of a JavaScript Number.\n" +
+        "Use 'Datastore.int(<integer_value_as_string>)' to preserve accuracy " +
+        'in your database.';
+
+      const typeCastWarning =
+        "TypeCastWarning: the value for '" +
+        property +
+        "' property is a JavaScript Number.\n" +
+        "Use 'Datastore.int(<integer_value_as_string>)' or " +
+        "'Datastore.double(<double_value_as_string>)' to preserve consistent " +
+        'Datastore types in your database.';
+
+      if (Number.isInteger(value)) {
+        if (!Number.isSafeInteger(value)) {
+          process.emitWarning(integerOutOfBoundsWarning);
+        } else {
+          warn('TypeCastWarning', typeCastWarning);
+        }
+        value = new entity.Int(value);
+        valueProto.integerValue = value.value;
+        return valueProto;
+      } else {
+        warn('TypeCastWarning', typeCastWarning);
+        value = new entity.Double(value);
+        valueProto.doubleValue = value.value;
+        return valueProto;
+      }
+    }
+
     if (isDsGeoPoint(value)) {
       valueProto.geoPointValue = value.value;
       return valueProto;
@@ -667,6 +711,14 @@ export namespace entity {
     throw new Error('Unsupported field value, ' + value + ', was provided.');
   }
 
+  const warningTypesIssued = new Set<string>();
+  const warn = (warningName: string, warningMessage: string) => {
+    if (!warningTypesIssued.has(warningName)) {
+      warningTypesIssued.add(warningName);
+      process.emitWarning(warningMessage);
+    }
+  };
+
   /**
    * Convert any entity protocol to a plain object.
    *

src/query.ts

@@ -400,7 +400,7 @@ class Query {
    *     [here](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore).
    * @param {object} [options.gaxOptions] Request configuration options, outlined
    *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
-   * @param {boolean | IntegerTypeCastOptions} [options.wrapNumbers=false]
+   * @param {boolean | IntegerTypeCastOptions} [options.wrapNumbers=True]
    *     Wrap values of integerValue type in {@link Datastore#Int} objects.
    *     If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
    *     If an `object`, this will return a value returned by

src/request.ts

@@ -447,7 +447,7 @@ class DatastoreRequest {
    *     [here](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore).
    * @param {object} [options.gaxOptions] Request configuration options, outlined
    *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
-   * @param {boolean | IntegerTypeCastOptions} [options.wrapNumbers=false]
+   * @param {boolean | IntegerTypeCastOptions} [options.wrapNumbers=true]
    *     Wrap values of integerValue type in {@link Datastore#Int} objects.
    *     If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
    *     If an `object`, this will return a value returned by

system-test/datastore.ts

@@ -20,6 +20,7 @@ import * as yaml from 'js-yaml';
 import {Datastore, Index} from '../src';
 import {google} from '../protos/protos';
 import {Storage} from '@google-cloud/storage';
+import {entity} from '../src/entity';
 
 describe('Datastore', () => {
   const testKinds: string[] = [];
@@ -67,11 +68,11 @@ describe('Datastore', () => {
       publishedAt: new Date(),
       author: 'Silvano',
       isDraft: false,
-      wordCount: 400,
-      rating: 5.0,
+      wordCount: new entity.Int({propertyName: 'wordCount', integerValue: 400}),
+      rating: new entity.Double({propertyName: 'rating', doubleValue: 5.0}),
       likes: null,
       metadata: {
-        views: 100,
+        views: new entity.Int({propertyName: 'views', integerValue: 100}),
       },
     };
 
@@ -268,6 +269,40 @@ describe('Datastore', () => {
       await datastore.delete(postKey);
     });
 
+    it('should save/get an int-able double value via Datastore.', async () => {
+      const postKey = datastore.key('Team');
+      const points = Datastore.double(2);
+      await datastore.save({key: postKey, data: {points}});
+      let [entity] = await datastore.get(postKey, {wrapNumbers: true});
+      // Expect content is stored in datastore as a double with wrapping to
+      // return a wrapped double
+      assert.strictEqual(entity.points.type, 'DatastoreDouble');
+      assert.strictEqual(entity.points.value, 2);
+
+      [entity] = await datastore.get(postKey, {wrapNumbers: false});
+      // Verify that when requested with wrapNumbers false, we get a plain
+      // javascript Number 2.
+      assert.strictEqual(entity.points, 2);
+
+      [entity] = await datastore.get(postKey);
+      // Expect without any options, a wrapped double to be returned.
+      assert.strictEqual(entity.points.type, 'DatastoreDouble');
+      assert.strictEqual(entity.points.value, 2);
+
+      // Save the data again, reget, ensuring that along the way it isn't
+      // somehow changed to another numeric type.
+      await datastore.save(entity);
+      [entity] = await datastore.get(postKey);
+      // expect as we saved, that this property is still a DatastoreDouble.
+      assert.strictEqual(entity.points.type, 'DatastoreDouble');
+      assert.strictEqual(entity.points.value, 2);
+
+      // Verify that DatastoreDouble implement Number behavior
+      assert.strictEqual(entity.points + 1, 3);
+
+      await datastore.delete(postKey);
+    });
+
     it('should wrap specified properties via IntegerTypeCastOptions.properties', async () => {
       const postKey = datastore.key('Scores');
       const largeIntValueAsString = '9223372036854775807';
@@ -513,7 +548,7 @@ describe('Datastore', () => {
           },
         });
         const [entity] = await datastore.get(key);
-        assert.strictEqual(entity.year, integerValue);
+        assert.strictEqual(entity.year.valueOf(), integerValue);
       });
 
       it('should save and decode a double', async () => {
@@ -527,7 +562,7 @@ describe('Datastore', () => {
           },
         });
         const [entity] = await datastore.get(key);
-        assert.strictEqual(entity.nines, doubleValue);
+        assert.strictEqual(entity.nines.valueOf(), doubleValue);
       });
 
       it('should save and decode a geo point', async () => {
@@ -885,7 +920,7 @@ describe('Datastore', () => {
         datastore.get(key),
       ]);
       assert.strictEqual(typeof deletedEntity, 'undefined');
-      assert.strictEqual(fetchedEntity.rating, 10);
+      assert.strictEqual(fetchedEntity.rating.valueOf(), 10);
     });
 
     it('should use the last modification to a key', async () => {