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

src/extended_json.ts

@@ -28,6 +28,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 */
@@ -76,17 +78,23 @@ const keysToCodecs = {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function deserializeValue(value: any, options: EJSONOptions = {}) {
   if (typeof value === 'number') {
+    // TODO(NODE-4377): EJSON js number handling diverges from BSON
+    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;
     }
 
     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) {
-        // TODO(NODE-4377): EJSON js number handling diverges from BSON
+      if (in64BitRange) {
+        if (options.useBigInt64) {
+          return BigInt(value);
+        }
         return Long.fromNumber(value);
       }
     }
@@ -378,13 +386,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

@@ -76,6 +76,10 @@ const INT_CACHE: { [key: number]: Long } = {};
 /** A cache of the Long representations of small unsigned integer values. */
 const UINT_CACHE: { [key: number]: Long } = {};
 
+const MAX_INT64_STRING_LENGTH = 20;
+
+const DECIMAL_REG_EX = /^(\+?0|(\+|-)?[1-9][0-9]*)$/;
+
 /** @public */
 export interface LongExtended {
   $numberLong: string;
@@ -1023,9 +1027,35 @@ export class Long extends BSONValue {
     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 { useBigInt64 = false, relaxed = true } = { ...options };
+
+    if (doc.$numberLong.length > MAX_INT64_STRING_LENGTH) {
+      throw new BSONError('$numberLong string is too long');
+    }
+
+    if (!DECIMAL_REG_EX.test(doc.$numberLong)) {
+      throw new BSONError(`$numberLong string "${doc.$numberLong}" is in an invalid format`);
+    }
+
+    if (useBigInt64) {
+      const INT64_MAX = BigInt('0x7fffffffffffffff');
+      const INT64_MIN = -BigInt('0x8000000000000000');
+      const bigIntResult = BigInt(doc.$numberLong);
+      if (bigIntResult > INT64_MAX || bigIntResult < INT64_MIN) {
+        throw new BSONError(`EJSON numberLong must be in int64 range; got ${bigIntResult}`);
+      }
+      return bigIntResult;
+    }
+
+    const longResult = Long.fromString(doc.$numberLong);
+    if (relaxed) {
+      return longResult.toNumber();
+    }
+    return longResult;
   }
 
   /** @internal */