Introduce 'useNativeNumbers' config option

This boolean option allows users to make driver accept and represent
integer values as native JavaScript `Number`s instead of driver's
special `Integer`s. When this option is set to `true` driver will
fail to encode `Integer` values passed as query parameters. All
returned `Record`, `Node`, `Relationship`, etc. will have their
integer fields as native `Number`s. Object returned by `Record#toObject()`
will also contain native numbers.

**Warning:** enabling this setting can potentially make driver return
lossy integer values. This would be the case when database contain
integer values which do not fit in
`[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]` range. Such
integers will then be represented as `Number.NEGATIVE_INFINITY` or
`Number.POSITIVE_INFINITY`, which is lossy and different from what is
actually stored in the database. That is why this option is set to
`false` by default. Driver's `Integer` class is able to represent
integer values beyond `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`
and thus is a much safer option in the general case.

Author: lutovich

package-lock.json

@@ -157,6 +157,17 @@ const USER_AGENT = "neo4j-javascript/" + VERSION;
  *       // result in no timeout being applied. Connection establishment will be then bound by the timeout configured
  *       // on the operating system level. Default value is 5000, which is 5 seconds.
  *       connectionTimeout: 5000, // 5 seconds
+ *
+ *       // Make this driver always return and accept native JavaScript number for integer values, instead of the
+ *       // dedicated {@link Integer} class. Values that do not fit in native number bit range will be represented as
+ *       // <code>Number.NEGATIVE_INFINITY</code> or <code>Number.POSITIVE_INFINITY</code>. Driver will fail to encode
+ *       // {@link Integer} values passed as query parameters when this setting is set to <code>true</code>.
+ *       // <b>Warning:</b> It is not safe to enable this setting when JavaScript applications are not the only ones
+ *       // interacting with the database. Stored numbers might in such case be not representable by native
+ *       // {@link Number} type and thus driver will return lossy values. For example, this might happen when data was
+ *       // initially imported using neo4j import tool and contained numbers larger than
+ *       // <code>Number.MAX_SAFE_INTEGER</code>. Driver will then return positive infinity, which is lossy.
+ *       useNativeNumbers: false,
  *     }
  *
  * @param {string} url The URL for the Neo4j database, for instance "bolt://localhost"

src/v1/index.js

@@ -88,6 +88,21 @@ class Integer {
    */
   toNumber(){ return this.high * TWO_PWR_32_DBL + (this.low >>> 0); }
 
+  /**
+   * Converts the Integer to native number or -Infinity/+Infinity when it does not fit.
+   * @return {number}
+   * @package
+   */
+  toNumberOrInfinity() {
+    if (this.lessThan(Integer.MIN_SAFE_VALUE)) {
+      return Number.NEGATIVE_INFINITY;
+    } else if (this.greaterThan(Integer.MAX_SAFE_VALUE)) {
+      return Number.POSITIVE_INFINITY;
+    } else {
+      return this.toNumber();
+    }
+  }
+
   /**
    * Converts the Integer to a string written in the specified radix.
    * @param {number=} radix Radix (2-36), defaults to 10

src/v1/integer.js

@@ -162,11 +162,12 @@ class Connection {
 
   /**
    * @constructor
-   * @param channel - channel with a 'write' function and a 'onmessage'
-   *                  callback property
-   * @param url - url to connect to
+   * @param {NodeChannel|WebSocketChannel} channel - channel with a 'write' function and a 'onmessage' callback property.
+   * @param {string} url - the hostname and port to connect to.
+   * @param {boolean} useNativeNumbers if this connection should treat/convert all received numbers
+   * (including native {@link Number} type or our own {@link Integer}) as native {@link Number}.
    */
-  constructor (channel, url) {
+  constructor(channel, url, useNativeNumbers = false) {
     /**
      * An ordered queue of observers, each exchange response (zero or more
      * RECORD messages followed by a SUCCESS message) we recieve will be routed
@@ -180,8 +181,8 @@ class Connection {
     this._ch = channel;
     this._dechunker = new Dechunker();
     this._chunker = new Chunker( channel );
-    this._packer = new Packer( this._chunker );
-    this._unpacker = new Unpacker();
+    this._packer = new Packer(this._chunker, useNativeNumbers);
+    this._unpacker = new Unpacker(useNativeNumbers);
 
     this._isHandlingFailure = false;
     this._currentFailure = null;
@@ -588,7 +589,7 @@ function connect(url, config = {}, connectionErrorCode = null) {
   const Ch = config.channel || Channel;
   const parsedUrl = urlUtil.parseBoltUrl(url);
   const channelConfig = new ChannelConfig(parsedUrl, config, connectionErrorCode);
-  return new Connection(new Ch(channelConfig), parsedUrl.hostAndPort);
+  return new Connection(new Ch(channelConfig), parsedUrl.hostAndPort, config.useNativeNumbers);
 }
 
 export {

src/v1/internal/connector.js

@@ -19,6 +19,7 @@
 import utf8 from './utf8';
 import Integer, {int, isInt} from '../integer';
 import {newError} from './../error';
+import {Chunker} from './chunking';
 
 const TINY_STRING = 0x80;
 const TINY_LIST = 0x90;
@@ -75,9 +76,17 @@ class Structure {
   * @access private
   */
 class Packer {
-  constructor (channel) {
+
+  /**
+   * @constructor
+   * @param {Chunker} channel the chunker backed by a network channel.
+   * @param {boolean} useNativeNumbers if this packer should treat/convert all received numbers
+   * (including native {@link Number} type or our own {@link Integer}) as native {@link Number}.
+   */
+  constructor(channel, useNativeNumbers = false) {
     this._ch = channel;
     this._byteArraysSupported = true;
+    this._useNativeNumbers = useNativeNumbers;
   }
 
   /**
@@ -98,7 +107,7 @@ class Packer {
     } else if (typeof(x) == "string") {
       return () => this.packString(x, onError);
     } else if (isInt(x)) {
-      return () => this.packInteger( x );
+      return this._packableInteger(x, onError);
     } else if (x instanceof Int8Array) {
       return () => this.packBytes(x, onError);
     } else if (x instanceof Array) {
@@ -141,6 +150,28 @@ class Packer {
     }
   }
 
+  /**
+   * Creates a packable function out of the provided {@link Integer} value.
+   * @param {Integer} x the value to pack.
+   * @param {function} onError the callback for the case when value cannot be packed.
+   * @return {function}
+   * @private
+   */
+  _packableInteger(x, onError) {
+    if (this._useNativeNumbers) {
+      // pack Integer objects only when native numbers are not used, fail otherwise
+      // Integer can't represent special values like Number.NEGATIVE_INFINITY
+      // and should not be used at all when native numbers are enabled
+      if (onError) {
+        onError(newError(`Cannot pack Integer value ${x} (${JSON.stringify(x)}) when native numbers are enabled. ` +
+          `Please use native Number instead or disable native number support on the driver level.`));
+      }
+      return () => undefined;
+    } else {
+      return () => this.packInteger(x);
+    }
+  }
+
   /**
    * Packs a struct
    * @param signature the signature of the struct
@@ -309,11 +340,18 @@ class Packer {
   * @access private
   */
 class Unpacker {
-  constructor () {
+
+  /**
+   * @constructor
+   * @param {boolean} useNativeNumbers if this unpacker should treat/convert all received numbers
+   * (including native {@link Number} type or our own {@link Integer}) as native {@link Number}.
+   */
+  constructor(useNativeNumbers = false) {
     // Higher level layers can specify how to map structs to higher-level objects.
-    // If we recieve a struct that has a signature that does not have a mapper,
+    // If we receive a struct that has a signature that does not have a mapper,
     // we simply return a Structure object.
     this.structMappers = {};
+    this._useNativeNumbers = useNativeNumbers;
   }
 
   unpack(buffer) {
@@ -388,9 +426,10 @@ class Unpacker {
       let b = buffer.readInt32();
       return int(b);
     } else if (marker == INT_64) {
-      let high = buffer.readInt32();
-      let low = buffer.readInt32();
-      return new Integer(low, high);
+      const high = buffer.readInt32();
+      const low = buffer.readInt32();
+      const integer = new Integer(low, high);
+      return this._useNativeNumbers ? integer.toNumberOrInfinity() : integer;
     } else {
       return null;
     }

src/v1/internal/packstream.js

@@ -59,6 +59,9 @@ const connectionPoolSize: undefined | number = config.connectionPoolSize;
 const maxTransactionRetryTime: undefined | number = config.maxTransactionRetryTime;
 const loadBalancingStrategy1: undefined | LoadBalancingStrategy = config.loadBalancingStrategy;
 const loadBalancingStrategy2: undefined | string = config.loadBalancingStrategy;
+const maxConnectionLifetime: undefined | number = config.maxConnectionLifetime;
+const connectionTimeout: undefined | number = config.connectionTimeout;
+const useNativeNumbers: undefined | boolean = config.useNativeNumbers;
 
 const sessionMode: SessionMode = dummy;
 const sessionModeStr: string = sessionMode;

test/types/v1/driver.test.ts

@@ -325,6 +325,43 @@ describe('driver', () => {
     testIPv6Connection('bolt://[::1]:7687', done);
   });
 
+  const nativeNumbers = [
+    Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY,
+    Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER,
+    -0, 0,
+    -42, 42,
+    -999, 999,
+    -1000, 1000,
+    -9000000, 9000000,
+    Number.MIN_SAFE_INTEGER + 1, Number.MAX_SAFE_INTEGER - 1
+  ];
+
+  nativeNumbers.forEach(number => {
+
+    it(`should return native number ${number} when useNativeNumbers=true`, done => {
+      testNativeNumberInReturnedRecord(number, done);
+    });
+
+  });
+
+  it('should fail to pack Integer when useNativeNumbers=true', done => {
+    driver = neo4j.driver('bolt://localhost', sharedNeo4j.authToken, {useNativeNumbers: true});
+    const session = driver.session();
+
+    session.run('RETURN $number', {number: neo4j.int(42)})
+      .then(result => {
+        done.fail(`Was somehow able to pack Integer and received result ${JSON.stringify(result)}`);
+      })
+      .catch(error => {
+        const message = error.message;
+        if (message.indexOf('Cannot pack Integer value') === -1) {
+          done.fail(`Unexpected error message: ${message}`);
+        } else {
+          done();
+        }
+      });
+  });
+
   function testIPv6Connection(url, done) {
     if (serverVersion.compareTo(VERSION_3_1_0) < 0) {
       // IPv6 listen address only supported starting from neo4j 3.1, so let's ignore the rest
@@ -341,6 +378,29 @@ describe('driver', () => {
     });
   }
 
+  function testNativeNumberInReturnedRecord(number, done) {
+    driver = neo4j.driver('bolt://localhost', sharedNeo4j.authToken, {useNativeNumbers: true});
+
+    const session = driver.session();
+    session.run('RETURN $number AS n0, $number AS n1', {number: number}).then(result => {
+      session.close();
+
+      const records = result.records;
+      expect(records.length).toEqual(1);
+      const record = records[0];
+
+      expect(record.get('n0')).toEqual(number);
+      expect(record.get('n1')).toEqual(number);
+
+      expect(record.get(0)).toEqual(number);
+      expect(record.get(1)).toEqual(number);
+
+      expect(record.toObject()).toEqual({n0: number, n1: number});
+
+      done();
+    });
+  }
+
   /**
    * Starts new transaction to force new network connection.
    * @param {Driver} driver - the driver to use.

test/v1/driver.test.js

@@ -17,27 +17,52 @@
  * limitations under the License.
  */
 
-var v1 = require('../../lib/v1');
-var int = v1.int;
-var integer = v1.integer;
-
-describe('Pool', function() {
-  it('exposes inSafeRange function', function () {
-    expect(integer.inSafeRange(int("9007199254740991"))).toBeTruthy();
-    expect(integer.inSafeRange(int("9007199254740992"))).toBeFalsy();
-    expect(integer.inSafeRange(int("-9007199254740991"))).toBeTruthy();
-    expect(integer.inSafeRange(int("-9007199254740992"))).toBeFalsy();
+import neo4j from '../../src/v1';
+import Integer from '../../src/v1/integer';
+
+const int = neo4j.int;
+const integer = neo4j.integer;
+
+describe('Integer', () => {
+
+  it('exposes inSafeRange function', () => {
+    expect(integer.inSafeRange(int('9007199254740991'))).toBeTruthy();
+    expect(integer.inSafeRange(int('9007199254740992'))).toBeFalsy();
+    expect(integer.inSafeRange(int('-9007199254740991'))).toBeTruthy();
+    expect(integer.inSafeRange(int('-9007199254740992'))).toBeFalsy();
+  });
+
+  it('exposes toNumber function', () => {
+    expect(integer.toNumber(int('9007199254740991'))).toEqual(9007199254740991);
+    expect(integer.toNumber(int('-9007199254740991'))).toEqual(-9007199254740991);
   });
 
-  it('exposes toNumber function', function () {
-    expect(integer.toNumber(int("9007199254740991"))).toEqual(9007199254740991);
-    expect(integer.toNumber(int("-9007199254740991"))).toEqual(-9007199254740991);
+  it('exposes toString function', () => {
+    expect(integer.toString(int('9007199254740991'))).toEqual('9007199254740991');
+    expect(integer.toString(int('9007199254740992'))).toEqual('9007199254740992');
+    expect(integer.toString(int('-9007199254740991'))).toEqual('-9007199254740991');
+    expect(integer.toString(int('-9007199254740992'))).toEqual('-9007199254740992');
   });
 
-  it('exposes toString function', function () {
-    expect(integer.toString(int("9007199254740991"))).toEqual("9007199254740991");
-    expect(integer.toString(int("9007199254740992"))).toEqual("9007199254740992");
-    expect(integer.toString(int("-9007199254740991"))).toEqual("-9007199254740991");
-    expect(integer.toString(int("-9007199254740992"))).toEqual("-9007199254740992");
+  it('converts to number when safe', () => {
+    expect(int('42').toNumberOrInfinity()).toEqual(42);
+    expect(int('4242').toNumberOrInfinity()).toEqual(4242);
+    expect(int('-999').toNumberOrInfinity()).toEqual(-999);
+    expect(int('1000000000').toNumberOrInfinity()).toEqual(1000000000);
+    expect(Integer.MIN_SAFE_VALUE.toNumberOrInfinity()).toEqual(Integer.MIN_SAFE_VALUE.toNumber());
+    expect(Integer.MAX_SAFE_VALUE.toNumberOrInfinity()).toEqual(Integer.MAX_SAFE_VALUE.toNumber());
   });
+
+  it('converts to negative infinity when too small', () => {
+    expect(Integer.MIN_SAFE_VALUE.subtract(1).toNumberOrInfinity()).toEqual(Number.NEGATIVE_INFINITY);
+    expect(Integer.MIN_SAFE_VALUE.subtract(42).toNumberOrInfinity()).toEqual(Number.NEGATIVE_INFINITY);
+    expect(Integer.MIN_SAFE_VALUE.subtract(100).toNumberOrInfinity()).toEqual(Number.NEGATIVE_INFINITY);
+  });
+
+  it('converts to positive infinity when too large', () => {
+    expect(Integer.MAX_SAFE_VALUE.add(1).toNumberOrInfinity()).toEqual(Number.POSITIVE_INFINITY);
+    expect(Integer.MAX_SAFE_VALUE.add(24).toNumberOrInfinity()).toEqual(Number.POSITIVE_INFINITY);
+    expect(Integer.MAX_SAFE_VALUE.add(999).toNumberOrInfinity()).toEqual(Number.POSITIVE_INFINITY);
+  });
+
 });

test/v1/integer.test.js

@@ -54,6 +54,7 @@ declare interface Config {
   loadBalancingStrategy?: LoadBalancingStrategy;
   maxConnectionLifetime?: number;
   connectionTimeout?: number;
+  useNativeNumbers?: boolean;
 }
 
 declare type SessionMode = "READ" | "WRITE";