feat(NODE-4877): Add support for useBigInt64 (#3519)

Co-authored-by: Neal Beeken <neal.beeken@mongodb.com>
Co-authored-by: Bailey Pearson <bailey.pearson@mongodb.com>

.gitignore

@@ -87,3 +87,4 @@ etc/docs/build
 !docs/**/*.png
 !docs/**/*.css
 !docs/**/*.js
+.nvmrc

package.json

@@ -25,7 +25,7 @@
     "email": "dbx-node@mongodb.com"
   },
   "dependencies": {
-    "bson": "^5.0.0",
+    "bson": "^5.0.1",
     "mongodb-connection-string-url": "^2.6.0",
     "socks": "^2.7.1"
   },

src/bson.ts

@@ -36,7 +36,6 @@ export interface BSONSerializeOptions
       | 'allowObjectSmallerThanBufferSize'
       | 'index'
       | 'validation'
-      | 'useBigInt64'
     > {
   /**
    * Enabling the raw option will return a [Node.js Buffer](https://nodejs.org/api/buffer.html)
@@ -67,6 +66,7 @@ export interface BSONSerializeOptions
 export function pluckBSONSerializeOptions(options: BSONSerializeOptions): BSONSerializeOptions {
   const {
     fieldsAsRaw,
+    useBigInt64,
     promoteValues,
     promoteBuffers,
     promoteLongs,
@@ -78,6 +78,7 @@ export function pluckBSONSerializeOptions(options: BSONSerializeOptions): BSONSe
   } = options;
   return {
     fieldsAsRaw,
+    useBigInt64,
     promoteValues,
     promoteBuffers,
     promoteLongs,
@@ -102,6 +103,7 @@ export function resolveBSONOptions(
   const parentOptions = parent?.bsonOptions;
   return {
     raw: options?.raw ?? parentOptions?.raw ?? false,
+    useBigInt64: options?.useBigInt64 ?? parentOptions?.useBigInt64 ?? false,
     promoteLongs: options?.promoteLongs ?? parentOptions?.promoteLongs ?? true,
     promoteValues: options?.promoteValues ?? parentOptions?.promoteValues ?? true,
     promoteBuffers: options?.promoteBuffers ?? parentOptions?.promoteBuffers ?? false,

src/cmap/auth/mongodb_aws.ts

@@ -21,6 +21,7 @@ const AWS_RELATIVE_URI = 'http://169.254.170.2';
 const AWS_EC2_URI = 'http://169.254.169.254';
 const AWS_EC2_PATH = '/latest/meta-data/iam/security-credentials';
 const bsonOptions: BSONSerializeOptions = {
+  useBigInt64: false,
   promoteLongs: true,
   promoteValues: true,
   promoteBuffers: false,

src/cmap/commands.ts

@@ -304,6 +304,7 @@ export class Response {
   queryFailure?: boolean;
   shardConfigStale?: boolean;
   awaitCapable?: boolean;
+  useBigInt64: boolean;
   promoteLongs: boolean;
   promoteValues: boolean;
   promoteBuffers: boolean;
@@ -320,6 +321,7 @@ export class Response {
     this.raw = message;
     this.data = msgBody;
     this.opts = opts ?? {
+      useBigInt64: false,
       promoteLongs: true,
       promoteValues: true,
       promoteBuffers: false,
@@ -334,6 +336,7 @@ export class Response {
     this.fromCompressed = msgHeader.fromCompressed;
 
     // Flag values
+    this.useBigInt64 = typeof this.opts.useBigInt64 === 'boolean' ? this.opts.useBigInt64 : false;
     this.promoteLongs = typeof this.opts.promoteLongs === 'boolean' ? this.opts.promoteLongs : true;
     this.promoteValues =
       typeof this.opts.promoteValues === 'boolean' ? this.opts.promoteValues : true;
@@ -354,6 +357,7 @@ export class Response {
     // Allow the return of raw documents instead of parsing
     const raw = options.raw || false;
     const documentsReturnedIn = options.documentsReturnedIn || null;
+    const useBigInt64 = options.useBigInt64 ?? this.opts.useBigInt64;
     const promoteLongs = options.promoteLongs ?? this.opts.promoteLongs;
     const promoteValues = options.promoteValues ?? this.opts.promoteValues;
     const promoteBuffers = options.promoteBuffers ?? this.opts.promoteBuffers;
@@ -362,6 +366,7 @@ export class Response {
 
     // Set up the options
     const _options: BSONSerializeOptions = {
+      useBigInt64,
       promoteLongs,
       promoteValues,
       promoteBuffers,
@@ -590,6 +595,7 @@ export class BinMsg {
   checksumPresent: boolean;
   moreToCome: boolean;
   exhaustAllowed: boolean;
+  useBigInt64: boolean;
   promoteLongs: boolean;
   promoteValues: boolean;
   promoteBuffers: boolean;
@@ -607,6 +613,7 @@ export class BinMsg {
     this.raw = message;
     this.data = msgBody;
     this.opts = opts ?? {
+      useBigInt64: false,
       promoteLongs: true,
       promoteValues: true,
       promoteBuffers: false,
@@ -625,6 +632,7 @@ export class BinMsg {
     this.checksumPresent = (this.responseFlags & OPTS_CHECKSUM_PRESENT) !== 0;
     this.moreToCome = (this.responseFlags & OPTS_MORE_TO_COME) !== 0;
     this.exhaustAllowed = (this.responseFlags & OPTS_EXHAUST_ALLOWED) !== 0;
+    this.useBigInt64 = typeof this.opts.useBigInt64 === 'boolean' ? this.opts.useBigInt64 : false;
     this.promoteLongs = typeof this.opts.promoteLongs === 'boolean' ? this.opts.promoteLongs : true;
     this.promoteValues =
       typeof this.opts.promoteValues === 'boolean' ? this.opts.promoteValues : true;
@@ -648,6 +656,7 @@ export class BinMsg {
     // Allow the return of raw documents instead of parsing
     const raw = options.raw || false;
     const documentsReturnedIn = options.documentsReturnedIn || null;
+    const useBigInt64 = options.useBigInt64 ?? this.opts.useBigInt64;
     const promoteLongs = options.promoteLongs ?? this.opts.promoteLongs;
     const promoteValues = options.promoteValues ?? this.opts.promoteValues;
     const promoteBuffers = options.promoteBuffers ?? this.opts.promoteBuffers;
@@ -656,6 +665,7 @@ export class BinMsg {
 
     // Set up the options
     const bsonOptions: BSONSerializeOptions = {
+      useBigInt64,
       promoteLongs,
       promoteValues,
       promoteBuffers,

src/cmap/connection.ts

@@ -661,6 +661,7 @@ function write(
     command: !!options.command,
 
     // for BSON parsing
+    useBigInt64: typeof options.useBigInt64 === 'boolean' ? options.useBigInt64 : false,
     promoteLongs: typeof options.promoteLongs === 'boolean' ? options.promoteLongs : true,
     promoteValues: typeof options.promoteValues === 'boolean' ? options.promoteValues : true,
     promoteBuffers: typeof options.promoteBuffers === 'boolean' ? options.promoteBuffers : false,

src/connection_string.ts

@@ -255,6 +255,15 @@ export function parseOptions(
     mongoClient = undefined;
   }
 
+  // validate BSONOptions
+  if (options.useBigInt64 && typeof options.promoteLongs === 'boolean' && !options.promoteLongs) {
+    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');
+  }
+
+  if (options.useBigInt64 && typeof options.promoteValues === 'boolean' && !options.promoteValues) {
+    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');
+  }
+
   const url = new ConnectionString(uri);
   const { hosts, isSRV } = url;
 
@@ -955,6 +964,9 @@ export const OPTIONS = {
   promoteValues: {
     type: 'boolean'
   },
+  useBigInt64: {
+    type: 'boolean'
+  },
   proxyHost: {
     type: 'string'
   },

src/cursor/abstract_cursor.ts

@@ -642,6 +642,8 @@ export abstract class AbstractCursor<
           this[kId] =
             typeof response.cursor.id === 'number'
               ? Long.fromNumber(response.cursor.id)
+              : typeof response.cursor.id === 'bigint'
+              ? Long.fromBigInt(response.cursor.id)
               : response.cursor.id;
 
           if (response.cursor.ns) {
@@ -741,6 +743,8 @@ export function next<T>(
       const cursorId =
         typeof response.cursor.id === 'number'
           ? Long.fromNumber(response.cursor.id)
+          : typeof response.cursor.id === 'bigint'
+          ? Long.fromBigInt(response.cursor.id)
           : response.cursor.id;
 
       cursor[kDocuments].pushMany(response.cursor.nextBatch);

src/db.ts

@@ -57,6 +57,7 @@ const DB_OPTIONS_ALLOW_LIST = [
   'readConcern',
   'retryMiliSeconds',
   'numberOfRetries',
+  'useBigInt64',
   'promoteBuffers',
   'promoteLongs',
   'bsonRegExp',

src/mongo_types.ts

@@ -176,7 +176,7 @@ export type ArrayElement<Type> = Type extends ReadonlyArray<infer Item> ? Item :
 export type SchemaMember<T, V> = { [P in keyof T]?: V } | { [key: string]: V };
 
 /** @public */
-export type IntegerType = number | Int32 | Long;
+export type IntegerType = number | Int32 | Long | bigint;
 
 /** @public */
 export type NumericType = IntegerType | Decimal128 | Double;
@@ -454,6 +454,7 @@ export type NestedPaths<Type, Depth extends number[]> = Depth['length'] extends
   : Type extends
       | string
       | number
+      | bigint
       | boolean
       | Date
       | RegExp

src/operations/create_collection.ts

@@ -23,6 +23,7 @@ const ILLEGAL_COMMAND_FIELDS = new Set([
   'writeConcern',
   'raw',
   'fieldsAsRaw',
+  'useBigInt64',
   'promoteLongs',
   'promoteValues',
   'promoteBuffers',

src/sdam/monitor.ts

@@ -120,6 +120,7 @@ export class Monitor extends TypedEventEmitter<MonitorEvents> {
       // force BSON serialization options
       {
         raw: false,
+        useBigInt64: false,
         promoteLongs: true,
         promoteValues: true,
         promoteBuffers: true

src/sessions.ts

@@ -307,7 +307,8 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     if (
       !clusterTime.signature ||
       clusterTime.signature.hash?._bsontype !== 'Binary' ||
-      (typeof clusterTime.signature.keyId !== 'number' &&
+      (typeof clusterTime.signature.keyId !== 'bigint' &&
+        typeof clusterTime.signature.keyId !== 'number' &&
         clusterTime.signature.keyId?._bsontype !== 'Long') // apparently we decode the key to number?
     ) {
       throw new MongoInvalidArgumentError(

test/integration/change-streams/change_stream.test.ts

@@ -162,12 +162,14 @@ describe('Change Streams', function () {
   it('should close the listeners after the cursor is closed', {
     metadata: { requires: { topology: 'replicaset' } },
     async test() {
+      const collection = db.collection('closesListeners');
+      const changeStream = collection.watch(pipeline);
       const willBeChanges = on(changeStream, 'change');
       await once(changeStream.cursor, 'init');
       await collection.insertOne({ a: 1 });
 
       await willBeChanges.next();
-      expect(changeStream.cursorStream.listenerCount('data')).to.equal(1);
+      expect(changeStream.cursorStream?.listenerCount('data')).to.equal(1);
 
       await changeStream.close();
       expect(changeStream.cursorStream).to.not.exist;
@@ -1670,7 +1672,7 @@ describe('Change Streams', function () {
         it('does not convert Longs to numbers', {
           metadata: { requires: { topology: '!single' } },
           test: async function () {
-            cs = collection.watch([], { promoteLongs: true });
+            cs = collection.watch([], { promoteLongs: true, useBigInt64: false });
 
             const willBeChange = once(cs, 'change').then(args => args[0]);
             await once(cs.cursor, 'init');
@@ -1689,7 +1691,7 @@ describe('Change Streams', function () {
         it('converts Long values to native numbers', {
           metadata: { requires: { topology: '!single' } },
           test: async function () {
-            cs = collection.watch([], { promoteLongs: false });
+            cs = collection.watch([], { promoteLongs: false, useBigInt64: false });
 
             const willBeChange = once(cs, 'change').then(args => args[0]);
             await once(cs.cursor, 'init');
@@ -1707,7 +1709,7 @@ describe('Change Streams', function () {
         it('defaults to true', {
           metadata: { requires: { topology: '!single' } },
           test: async function () {
-            cs = collection.watch([]);
+            cs = collection.watch([], { useBigInt64: false });
 
             const willBeChange = once(cs, 'change').then(args => args[0]);
             await once(cs.cursor, 'init');
@@ -1722,6 +1724,60 @@ describe('Change Streams', function () {
       });
     });
 
+    context('useBigInt64', () => {
+      const useBigInt64FalseTest = async (options: ChangeStreamOptions) => {
+        cs = collection.watch([], options);
+        const willBeChange = once(cs, 'change').then(args => args[0]);
+        await once(cs.cursor, 'init');
+
+        await collection.insertOne({ a: Long.fromNumber(10) });
+
+        const change = await willBeChange;
+
+        expect(typeof change.fullDocument.a).to.equal('number');
+      };
+
+      context('when set to false', function () {
+        it('converts Long to number', {
+          metadata: {
+            requires: { topology: '!single' }
+          },
+          test: async function () {
+            await useBigInt64FalseTest({ useBigInt64: false });
+          }
+        });
+      });
+
+      context('when set to true', function () {
+        it('converts Long to bigint', {
+          metadata: {
+            requires: { topology: '!single' }
+          },
+          test: async function () {
+            cs = collection.watch([], { useBigInt64: true });
+            const willBeChange = once(cs, 'change').then(args => args[0]);
+            await once(cs.cursor, 'init');
+
+            await collection.insertOne({ a: Long.fromNumber(10) });
+
+            const change = await willBeChange;
+
+            expect(change.fullDocument).property('a').to.be.a('bigint');
+            expect(change.fullDocument).property('a', 10n);
+          }
+        });
+      });
+
+      context('when unset', function () {
+        it('defaults to false', {
+          metadata: { requires: { topology: '!single' } },
+          test: async function () {
+            await useBigInt64FalseTest({});
+          }
+        });
+      });
+    });
+
     context('invalid options', function () {
       it('does not send invalid options on the aggregate command', {
         metadata: { requires: { topology: '!single' } },