feat(NODE-4874): support EJSON parse for BigInt from $numberLong

src/extended_json.ts

@@ -22,6 +22,8 @@ export type EJSONOptions = {
   legacy?: boolean;
   /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
   relaxed?: boolean;
+  /** Enable native bigint support */
+  useBigInt64?: boolean;
 };
 
 /** @internal */
@@ -70,17 +72,23 @@ const keysToCodecs = {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function deserializeValue(value: any, options: EJSONOptions = {}) {
   if (typeof value === 'number') {
+    const in32BitRange = value <= BSON_INT32_MAX && value >= BSON_INT32_MIN;
+    const in64BitRange = value <= BSON_INT64_MAX && value >= BSON_INT64_MIN;
+
     if (options.relaxed || options.legacy) {
-      return value;
+      return Number.isInteger(value) && options.useBigInt64 ? BigInt(value) : value;
     }
 
     if (Number.isInteger(value) && !Object.is(value, -0)) {
       // interpret as being of the smallest BSON integer type that can represent the number exactly
-      if (value >= BSON_INT32_MIN && value <= BSON_INT32_MAX) {
+      if (in32BitRange) {
         return new Int32(value);
       }
-      if (value >= BSON_INT64_MIN && value <= BSON_INT64_MAX) {
+      if (in64BitRange) {
         // TODO(NODE-4377): EJSON js number handling diverges from BSON
+        if (options.useBigInt64) {
+          return BigInt(value);
+        }
         return Long.fromNumber(value);
       }
     }
@@ -362,13 +370,18 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parse(text: string, options?: EJSONOptions): any {
+  const ejsonOptions = {
+    useBigInt64: options?.useBigInt64 ?? false,
+    relaxed: options?.relaxed ?? true,
+    legacy: options?.legacy ?? false
+  };
   return JSON.parse(text, (key, value) => {
     if (key.indexOf('\x00') !== -1) {
       throw new BSONError(
         `BSON Document field names cannot contain null bytes, found: ${JSON.stringify(key)}`
       );
     }
-    return deserializeValue(value, { relaxed: true, legacy: false, ...options });
+    return deserializeValue(value, ejsonOptions);
   });
 }
 

src/long.ts

@@ -1021,9 +1021,20 @@ export class Long {
     if (options && options.relaxed) return this.toNumber();
     return { $numberLong: this.toString() };
   }
-  static fromExtendedJSON(doc: { $numberLong: string }, options?: EJSONOptions): number | Long {
-    const result = Long.fromString(doc.$numberLong);
-    return options && options.relaxed ? result.toNumber() : result;
+  static fromExtendedJSON(
+    doc: { $numberLong: string },
+    options?: EJSONOptions
+  ): number | Long | bigint {
+    const longResult = Long.fromString(doc.$numberLong);
+    const defaults = { useBigInt64: false, relaxed: true };
+    const ejsonOptions = { ...defaults, ...options };
+    if (ejsonOptions.useBigInt64) {
+      return BigInt(doc.$numberLong);
+    }
+    if (ejsonOptions.relaxed) {
+      return longResult.toNumber();
+    }
+    return longResult;
   }
 
   /** @internal */

test/node/bigint.test.ts

@@ -1,4 +1,4 @@
-import { BSON, BSONError } from '../register-bson';
+import { BSON, BSONError, EJSON } from '../register-bson';
 import { bufferFromHexArray } from './tools/utils';
 import { expect } from 'chai';
 import { BSON_DATA_LONG } from '../../src/constants';
@@ -263,4 +263,127 @@ describe('BSON BigInt support', function () {
       expect(serializedMap).to.deep.equal(expectedSerialization);
     });
   });
+
+  describe('EJSON.parse()', function () {
+    type ParseOptions = {
+      useBigInt64: boolean | undefined;
+      relaxed: boolean | undefined;
+    };
+    type TestTableEntry = {
+      options: ParseOptions;
+      expectedResult: BSON.Document;
+    };
+
+    // NOTE: legacy is not changed here as it does not affect the output of parsing a Long
+    const useBigInt64Values = [true, false, undefined];
+    const relaxedValues = [true, false, undefined];
+    const sampleCanonicalString = '{"a":{"$numberLong":"23"}}';
+    const sampleRelaxedIntegerString = '{"a":4294967296}';
+    const sampleRelaxedDoubleString = '{"a": 2147483647.9}';
+
+    function genTestTable(
+      useBigInt64: boolean | undefined,
+      relaxed: boolean | undefined,
+      getExpectedResult: (boolean, boolean) => BSON.Document
+    ): [TestTableEntry] {
+      const useBigInt64IsSet = useBigInt64 ?? false;
+      const relaxedIsSet = relaxed ?? true;
+
+      const expectedResult = getExpectedResult(useBigInt64IsSet, relaxedIsSet);
+
+      return [{ options: { useBigInt64, relaxed }, expectedResult }];
+    }
+
+    function generateTestDescription(entry: TestTableEntry, inputString: string): string {
+      // TODO(NODE-4874): When NODE-4873 is merged in, replace this with EJSON.stringify
+      const options = entry.options;
+      return `parses field 'a' of '${inputString}' to '${entry.expectedResult.a.constructor.name}' when useBigInt64 is ${options.useBigInt64} and relaxed is ${options.relaxed}`;
+    }
+
+    function generateTest(entry: TestTableEntry, sampleString: string): () => void {
+      const options = entry.options;
+
+      return () => {
+        const parsed = EJSON.parse(sampleString, {
+          useBigInt64: options.useBigInt64,
+          relaxed: options.relaxed
+        });
+        expect(parsed).to.deep.equal(entry.expectedResult);
+      };
+    }
+
+    describe('canonical input', function () {
+      const canonicalInputTestTable = useBigInt64Values.flatMap(useBigInt64 => {
+        return relaxedValues.flatMap(relaxed => {
+          return genTestTable(
+            useBigInt64,
+            relaxed,
+            (useBigInt64IsSet: boolean, relaxedIsSet: boolean) =>
+              useBigInt64IsSet
+                ? { a: 23n }
+                : relaxedIsSet
+                ? { a: 23 }
+                : { a: BSON.Long.fromNumber(23) }
+          );
+        });
+      });
+
+      it('meta test: generates 9 tests', () => {
+        expect(canonicalInputTestTable).to.have.lengthOf(9);
+      });
+
+      for (const entry of canonicalInputTestTable) {
+        const test = generateTest(entry, sampleCanonicalString);
+        const description = generateTestDescription(entry, sampleCanonicalString);
+
+        it(description, test);
+      }
+    });
+
+    describe('relaxed integer input', function () {
+      const relaxedIntegerInputTestTable = useBigInt64Values.flatMap(useBigInt64 => {
+        return relaxedValues.flatMap(relaxed => {
+          return genTestTable(
+            useBigInt64,
+            relaxed,
+            (useBigInt64IsSet: boolean, relaxedIsSet: boolean) =>
+              useBigInt64IsSet
+                ? { a: 4294967296n }
+                : relaxedIsSet
+                ? { a: 4294967296 }
+                : { a: BSON.Long.fromNumber(4294967296) }
+          );
+        });
+      });
+      it('meta test: generates 9 tests', () => {
+        expect(relaxedIntegerInputTestTable).to.have.lengthOf(9);
+      });
+
+      for (const entry of relaxedIntegerInputTestTable) {
+        const test = generateTest(entry, sampleRelaxedIntegerString);
+        const description = generateTestDescription(entry, sampleRelaxedIntegerString);
+
+        it(description, test);
+      }
+    });
+
+    describe('relaxed double input where double is outside of int32 range and useBigInt64 is true', function () {
+      const relaxedDoubleInputTestTable = relaxedValues.flatMap(relaxed => {
+        return genTestTable(true, relaxed, (_, relaxedIsSet: boolean) =>
+          relaxedIsSet ? { a: 2147483647.9 } : { a: new BSON.Double(2147483647.9) }
+        );
+      });
+
+      it('meta test: generates 3 tests', () => {
+        expect(relaxedDoubleInputTestTable).to.have.lengthOf(3);
+      });
+
+      for (const entry of relaxedDoubleInputTestTable) {
+        const test = generateTest(entry, sampleRelaxedDoubleString);
+        const description = generateTestDescription(entry, sampleRelaxedDoubleString);
+
+        it(description, test);
+      }
+    });
+  });
 });

test/node/long.test.ts

@@ -1,3 +1,4 @@
+import { expect } from 'chai';
 import { Long } from '../register-bson';
 
 describe('Long', function () {
@@ -21,4 +22,23 @@ describe('Long', function () {
     expect(new Long(13835058055282163712n).toString()).to.equal('-4611686018427387904');
     expect(new Long(13835058055282163712n, true).toString()).to.equal('13835058055282163712');
   });
+
+  describe('static fromExtendedJSON()', function () {
+    it('is not affected by the legacy flag', function () {
+      const ejsonDoc = { $numberLong: '123456789123456789' };
+      const longRelaxedLegacy = Long.fromExtendedJSON(ejsonDoc, { legacy: true, relaxed: true });
+      const longRelaxedNonLegacy = Long.fromExtendedJSON(ejsonDoc, {
+        legacy: false,
+        relaxed: true
+      });
+      const longCanonicalLegacy = Long.fromExtendedJSON(ejsonDoc, { legacy: true, relaxed: false });
+      const longCanonicalNonLegacy = Long.fromExtendedJSON(ejsonDoc, {
+        legacy: false,
+        relaxed: false
+      });
+
+      expect(longRelaxedLegacy).to.deep.equal(longRelaxedNonLegacy);
+      expect(longCanonicalLegacy).to.deep.equal(longCanonicalNonLegacy);
+    });
+  });
 });