feat!: throw error with out of bounds integer values, optionally wrap into DsInt or provide a custom 'integerValue' type cast options

samples/concepts.js

@@ -731,8 +731,8 @@ class Query extends TestHelper {
       const percentCompletes = [];
       const [tasks] = await datastore.runQuery(query);
       tasks.forEach(task => {
-        priorities.push(task.priority);
-        percentCompletes.push(task.percent_complete);
+        priorities.push(task.priority.valueOf());
+        percentCompletes.push(task.percent_complete.valueOf());
       });
 
       return {
@@ -1017,14 +1017,22 @@ class Transaction extends TestHelper {
       const accounts = results.map(result => result[0]);
       // Restore `datastore` to the mock API.
       datastore = datastoreMock;
-      assert.strictEqual(
+      assert.equal(
         accounts[0].balance,
         originalBalance - amountToTransfer
       );
       assert.strictEqual(
+        accounts[0].balance.valueOf(),
+        originalBalance - amountToTransfer
+      );
+      assert.equal(
         accounts[1].balance,
         originalBalance + amountToTransfer
       );
+      assert.strictEqual(
+        accounts[1].balance.valueOf(),
+        originalBalance + amountToTransfer
+      );
     } catch (err) {
       datastore = datastoreMock;
       throw err;

src/entity.ts

@@ -17,7 +17,7 @@
 import arrify = require('arrify');
 import * as extend from 'extend';
 import * as is from 'is';
-import {Query, QueryProto} from './query';
+import {Query, QueryProto, IntegerTypeCastOptions} from './query';
 import {PathType} from '.';
 import {Entities} from './request';
 import * as Protobuf from 'protobufjs';
@@ -89,20 +89,73 @@ export namespace entity {
    *
    * @class
    * @param {number|string} value The integer value.
+   * @param {object} typeCastOptions Config for custom `integerValue` cast.
+   * @param {function} [typeCastOptions.integerTypeCastFunction] A custom user
+   *     provided function to convert `integerValue`.
+   * @param {sting|string[]} [typeCastOptions.properties] `Entity` property
+   *     names to be converted using `integerTypeCastFunction`.
    *
    * @example
    * const {Datastore} = require('@google-cloud/datastore');
    * const datastore = new Datastore();
    * const anInt = datastore.int(7);
    */
-  export class Int {
+  export class Int extends Number {
     value: string;
-    constructor(value: number | string) {
+    typeCastFunction?: Function;
+    typeCastProperties?: string[];
+    private _entityPropertyName: string | undefined;
+    constructor(
+      value: number | string | ValueProto,
+      typeCastOptions?: IntegerTypeCastOptions
+    ) {
+      super();
+      this._entityPropertyName =
+        typeof value === 'object' ? value.propertyName : undefined;
+      this.value =
+        typeof value === 'object'
+          ? value.integerValue.toString()
+          : value.toString();
       /**
        * @name Int#value
        * @type {string}
        */
-      this.value = value.toString();
+      if (typeCastOptions) {
+        if (typeof typeCastOptions.integerTypeCastFunction !== 'function') {
+          throw new Error(
+            `integerTypeCastFunction is not a function or was not provided.`
+          );
+        }
+        this.typeCastFunction = typeCastOptions.integerTypeCastFunction;
+        this.typeCastProperties = typeCastOptions.properties
+          ? arrify(typeCastOptions.properties)
+          : undefined;
+      }
+    }
+    // tslint:disable-next-line no-any
+    valueOf(): any {
+      let customCast = this.typeCastFunction ? true : false;
+      if (
+        this.typeCastProperties &&
+        !this.typeCastProperties.includes(this._entityPropertyName!)
+      ) {
+        customCast = false;
+      }
+
+      if (customCast) {
+        try {
+          return this.typeCastFunction!(this.value);
+        } catch (error) {
+          error.message = `integerTypeCastFunction threw an error - ${error.message}`;
+          throw error;
+        }
+      } else {
+        const num = Number(this.value);
+        if (!Number.isSafeInteger(num)) {
+          throw new Error(`Integer value ${this.value} is out of bounds.`);
+        }
+        return num;
+      }
     }
   }
 
@@ -332,6 +385,11 @@ export namespace entity {
    *
    * @private
    * @param {object} valueProto The protobuf Value message to convert.
+   * @param {object} typeCastOptions Config for custom `integerValue` cast.
+   * @param {function} [typeCastOptions.integerTypeCastFunction] A custom user
+   *     provided function to convert `integerValue`.
+   * @param {sting|string[]} [typeCastOptions.names] `Entity` property
+   *     names to be converted using `integerTypeCastFunction`.
    * @returns {*}
    *
    * @example
@@ -350,13 +408,19 @@ export namespace entity {
    * });
    * // <Buffer 68 65 6c 6c 6f>
    */
-  export function decodeValueProto(valueProto: ValueProto) {
+  export function decodeValueProto(
+    valueProto: ValueProto,
+    typeCastOptions?: IntegerTypeCastOptions
+  ) {
     const valueType = valueProto.valueType!;
     const value = valueProto[valueType];
 
     switch (valueType) {
       case 'arrayValue': {
-        return value.values.map(entity.decodeValueProto);
+        // tslint:disable-next-line no-any
+        return value.values.map((val: any) =>
+          entity.decodeValueProto(val, typeCastOptions)
+        );
       }
 
       case 'blobValue': {
@@ -372,7 +436,7 @@ export namespace entity {
       }
 
       case 'integerValue': {
-        return Number(value);
+        return new entity.Int(valueProto, typeCastOptions);
       }
 
       case 'entityValue': {
@@ -505,6 +569,11 @@ export namespace entity {
    *
    * @private
    * @param {object} entityProto The protocol entity object to convert.
+   * @param {object} typeCastOptions Config for custom `integerValue` cast.
+   * @param {function} [typeCastOptions.integerTypeCastFunction] A custom user
+   *     provided function to convert `integerValue`.
+   * @param {sting|string[]} [typeCastOptions.names] `Entity` property
+   *     names to be converted using `integerTypeCastFunction`.
    * @returns {object}
    *
    * @example
@@ -525,15 +594,18 @@ export namespace entity {
    * // }
    */
   // tslint:disable-next-line no-any
-  export function entityFromEntityProto(entityProto: EntityProto): any {
+  export function entityFromEntityProto(
+    entityProto: EntityProto,
+    typeCastOptions?: IntegerTypeCastOptions
+  ) {
     // tslint:disable-next-line no-any
     const entityObject: any = {};
     const properties = entityProto.properties || {};
 
     // tslint:disable-next-line forin
     for (const property in properties) {
       const value = properties[property];
-      entityObject[property] = entity.decodeValueProto(value);
+      entityObject[property] = entity.decodeValueProto(value, typeCastOptions);
     }
 
     return entityObject;
@@ -719,7 +791,11 @@ export namespace entity {
    * @param {object[]} results The response array.
    * @param {object} results.entity An entity object.
    * @param {object} results.entity.key The entity's key.
-   * @returns {object[]}
+   * @param {object} typeCastOptions Config for custom `integerValue` cast.
+   * @param {function} [typeCastOptions.integerTypeCastFunction] A custom user
+   *     provided function to convert `integerValue`.
+   * @param {sting|string[]} [typeCastOptions.names] `Entity` property
+   *     names to be converted using `integerTypeCastFunction`.* @returns {object[]}
    *
    * @example
    * request_('runQuery', {}, (err, response) => {
@@ -733,9 +809,12 @@ export namespace entity {
    *   //
    * });
    */
-  export function formatArray(results: ResponseResult[]) {
+  export function formatArray(
+    results: ResponseResult[],
+    typeCastOptions?: IntegerTypeCastOptions
+  ) {
     return results.map(result => {
-      const ent = entity.entityFromEntityProto(result.entity!);
+      const ent = entity.entityFromEntityProto(result.entity!, typeCastOptions);
       ent[entity.KEY_SYMBOL] = entity.keyFromKeyProto(result.entity!.key!);
       return ent;
     });
@@ -1225,6 +1304,7 @@ export interface ValueProto {
   values?: ValueProto[];
   // tslint:disable-next-line no-any
   value?: any;
+  propertyName?: string;
 }
 
 export interface EntityProto {

src/query.ts

@@ -517,9 +517,15 @@ export interface QueryProto {
  */
 export {Query};
 
+export interface IntegerTypeCastOptions {
+  integerTypeCastFunction: Function;
+  properties?: string | string[];
+}
+
 export interface RunQueryOptions {
   consistency?: 'strong' | 'eventual';
   gaxOptions?: CallOptions;
+  integerTypeCastOptions?: IntegerTypeCastOptions;
 }
 
 export interface RunQueryCallback {

system-test/datastore.ts

@@ -57,11 +57,11 @@ describe('Datastore', () => {
       publishedAt: new Date(),
       author: 'Silvano',
       isDraft: false,
-      wordCount: 400,
-      rating: 5.0,
+      wordCount: datastore.int(400),
+      rating: datastore.int(5.0),
       likes: null,
       metadata: {
-        views: 100,
+        views: datastore.int(100),
       },
     };
 
@@ -447,7 +447,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 () => {
@@ -794,7 +794,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 () => {