Merge pull request #153 from pontusmelke/1.1-integer-cleanup

Expose new integer methods

Author: pontusmelke

README.md

@@ -138,8 +138,8 @@ While there is no need to grab admin right if you are running tests against an e
 ## A note on numbers and the Integer type
 The Neo4j type system includes 64-bit integer values.
 However, Javascript can only safely represent integers between `-(2`<sup>`53`</sup>` - 1)` and `(2`<sup>`53`</sup>` - 1)`.
-In order to support the full Neo4j type system, the driver includes an explicit Integer types.
-Any time the driver recieves an Integer value from Neo4j, it will be represented with the Integer type by the driver.
+In order to support the full Neo4j type system, the driver will not automatically convert to javascript integers.
+Any time the driver receives an integer value from Neo4j, it will be represented with an internal integer type by the driver.
 
 ### Write integers
 Number written directly e.g. `session.run("CREATE (n:Node {age: {age}})", {age: 22})` will be of type `Float` in Neo4j.
@@ -158,19 +158,22 @@ session.run("CREATE (n {age: {myIntParam}})", {myIntParam: neo4j.int("9223372036
 ```
 
 ### Read integers
-Since Integers can be larger than can be represented as JavaScript numbers, it is only safe to convert Integer instances to JavaScript numbers if you know that they will not exceed `(2`<sup>`53`</sup>` - 1)` in size:
+Since Integers can be larger than can be represented as JavaScript numbers, it is only safe to convert to JavaScript numbers if you know that they will not exceed `(2`<sup>`53`</sup>` - 1)` in size.
+In order to facilitate working with integers the driver include `neo4j.isInt`, `neo4j.integer.inSafeRange`, `neo4j.integer.toNumber`, and `neo4j.integer.toString`.
 
 ```javascript
 var aSmallInteger = neo4j.int(123);
-var aNumber = aSmallInteger.toNumber();
+if (neo4j.integer.inSafeRange(aSmallInteger)) {
+    var aNumber = aSmallInteger.toNumber();
+}
 ```
 
-If you will be handling integers larger than that, you can use the Integer instances directly, or convert them to strings:
+If you will be handling integers larger than that, you can should convert them to strings:
 
 ```javascript
 var aLargerInteger = neo4j.int("9223372036854775807");
-var integerAsString = aLargerInteger.toString();
+if (!neo4j.integer.inSafeRange(aSmallInteger)) {
+    var integerAsString = aLargerInteger.toString();
+}
 ```
 
-To help you work with Integers, the Integer class exposes a large set of arithmetic methods.
-Refer to the [Integer API docs](http://neo4j.com/docs/api/javascript-driver/current/class/src/v1/integer.js~Integer.html) for details.

src/v1/index.js

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 
-import {int, isInt} from './integer';
+import {int, isInt, inSafeRange, toNumber, toString} from './integer';
 import {Node, Relationship, UnboundRelationship, PathSegment, Path} from './graph-types'
 import {Neo4jError, SERVICE_UNAVAILABLE, SESSION_EXPIRED} from './error';
 import Result from './result';
@@ -138,11 +138,17 @@ const error = {
   SERVICE_UNAVAILABLE,
   SESSION_EXPIRED
 };
+const integer = {
+  toNumber,
+  toString,
+  inSafeRange
+};
 
 const forExport = {
   driver,
   int,
   isInt,
+  integer,
   Neo4jError,
   auth,
   types,
@@ -154,6 +160,7 @@ export {
   driver,
   int,
   isInt,
+  integer,
   Neo4jError,
   auth,
   types,

src/v1/integer.js

@@ -32,6 +32,8 @@ import {newError} from "./error";
  * @param {number} low The low (signed) 32 bits of the long
  * @param {number} high The high (signed) 32 bits of the long
  * @constructor
+ *
+ * @deprecated This class will be removed or made internal in a future version of the driver.
  */
 class Integer {
   constructor(low, high) {
@@ -67,6 +69,8 @@ class Integer {
   // Common constant values ZERO, ONE, NEG_ONE, etc. are defined below the from*
   // methods on which they depend.
 
+
+  inSafeRange() {return this.greaterThanOrEqual(Integer.MIN_SAFE_VALUE) && this.lessThanOrEqual(Integer.MAX_SAFE_VALUE)}
   /**
    * Converts the Integer to an exact javascript Number, assuming it is a 32 bit integer.
    * @returns {number}
@@ -718,6 +722,41 @@ Integer.fromValue = function(val) {
     return new Integer(val.low, val.high);
 };
 
+/**
+ * Converts the specified value to a number.
+ * @access private
+ * @param {!Integer|number|string|!{low: number, high: number}} val Value
+ * @returns {number}
+ * @expose
+ */
+Integer.toNumber = function(val) {
+ return Integer.fromValue(val).toNumber();
+};
+
+/**
+* Converts the specified value to a string.
+* @access private
+* @param {!Integer|number|string|!{low: number, high: number}} val Value
+* @param {number} radix optional radix for string conversion, defaults to 10
+* @returns {String}
+* @expose
+*/
+Integer.toString = function(val, radix) {
+  return Integer.fromValue(val).toString(radix)
+};
+
+/**
+ * Checks if the given value is in the safe range in order to be converted to a native number
+ * @access private
+ * @param {!Integer|number|string|!{low: number, high: number}} val Value
+ * @param {number} radix optional radix for string conversion, defaults to 10
+ * @returns {boolean}
+ * @expose
+ */
+Integer.inSafeRange = function(val) {
+  return Integer.fromValue(val).inSafeRange();
+};
+
 /**
  * @type {number}
  * @const
@@ -801,6 +840,20 @@ Integer.MAX_VALUE = Integer.fromBits(0xFFFFFFFF|0, 0x7FFFFFFF|0, false);
  */
 Integer.MIN_VALUE = Integer.fromBits(0, 0x80000000|0, false);
 
+/**
+ * Minimum safe value.
+ * @type {!Integer}
+ * @expose
+ */
+Integer.MIN_SAFE_VALUE = Integer.fromBits(0x1|0, 0xFFFFFFFFFFE00000|0);
+
+/**
+* Maximum safe value.
+* @type {!Integer}
+* @expose
+*/
+Integer.MAX_SAFE_VALUE = Integer.fromBits(0xFFFFFFFF|0,0x1FFFFF|0);
+
 /**
  * Cast value to Integer type.
  * @access public
@@ -812,14 +865,42 @@ let int = Integer.fromValue;
 /**
  * Check if a variable is of Integer type.
  * @access public
- * @param {Mixed} value - The varaible to check.
+ * @param {Mixed} value - The variable to check.
  * @return {Boolean} - Is it of the Integer type?
  */
 let isInt = Integer.isInteger;
 
+/**
+ * Check if a variable can be safely converted to a number
+ * @access public
+ * @param {Mixed} value - The variable to check
+ * @return {Boolean} - true if it is safe to call toNumber on variable otherwise false
+ */
+let inSafeRange = Integer.inSafeRange;
+
+/**
+ * Converts a variable to a number
+ * @access public
+ * @param {Mixed} value - The variable to convert
+ * @return {number} - the variable as a number
+ */
+let toNumber = Integer.toNumber;
+
+/**
+ * Converts the integer to a string representation
+ * @access public
+ * @param {Mixed} value - The variable to convert
+ * @param {number} radix - radix to use in string conversion, defaults to 10
+ * @return {String} - returns a string representation of the integer
+ */
+let toString = Integer.toString;
+
 export {
     int,
     isInt,
+    inSafeRange,
+    toNumber,
+    toString
 }
 
 export default Integer

test/v1/integer.test.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2002-2016 "Neo Technology,"
+ * Network Engine for Objects in Lund AB [http://neotechnology.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * 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();
+  });
+
+  it('exposes toNumber function', function () {
+    expect(integer.toNumber(int("9007199254740991"))).toEqual(9007199254740991);
+    expect(integer.toNumber(int("-9007199254740991"))).toEqual(-9007199254740991);
+  });
+
+  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");
+  });
+});