feat(NODE-4522)!: remove callback support (#3499)

Author: nbbeeken

.evergreen/run-tests.sh

@@ -52,7 +52,7 @@ else
   source "$DRIVERS_TOOLS"/.evergreen/csfle/set-temp-creds.sh
 fi
 
-npm install mongodb-client-encryption@">=2.3.0"
+npm install mongodb-client-encryption@">=2.4.0-alpha.0"
 npm install @mongodb-js/zstd
 npm install snappy
 

etc/notes/CHANGES_5.0.0.md

@@ -16,9 +16,56 @@ The following is a detailed collection of the changes in the major v5 release of
 
 ## Changes
 
+### Optional callback support migrated to `mongodb-legacy`
+
+If you are a callback user and you are not ready to use promises, support for your workflow has **not** been removed.
+We have migrated it to a new package:
+
+- [`mongodb-legacy` Github](https://github.com./mongodb-js/nodejs-mongodb-legacy#readme)
+- [`mongodb-legacy` npm](https://www.npmjs.com/package/mongodb-legacy)
+
+The package wraps all of the driver's asynchronous operations that previously supported both promises and callbacks. All the wrapped APIs offer callback support via an optional callback argument alongside a Promise return value so projects with mixed usage will continue to work.
+
+#### Example usage of equivalent callback and promise usage
+
+After installing the package and modifying imports the following example demonstrates equivalent usages of either `async`/`await` syntax, `.then`/`.catch` chaining, or callbacks:
+
+```ts
+// Just add '-legacy' to my mongodb import
+import { MongoClient } from 'mongodb-legacy';
+const client = new MongoClient();
+const db = client.db();
+const collection = db.collection('pets');
+
+// Legacy projects may have intermixed API usage:
+app.get('/endpoint_async_await', async (req, res) => {
+  try {
+    const result = await collection.findOne({})
+    res.end(JSON.stringify(result));
+  } catch (error) {
+    res.errorHandling(error)
+  }
+});
+
+app.get('/endpoint_promises', (req, res) => {
+  collection
+    .findOne({})
+    .then(result => res.end(JSON.stringify(result)))
+    .catch(error => res.errorHandling(error));
+});
+
+app.get('/endpoint_callbacks', (req, res) => {
+  collection.findOne({}, (error, result) => {
+    if (error) return res.errorHandling(error);
+    res.end(JSON.stringify(result));
+  });
+});
+```
+
+
 ### Dot Notation Typescript Support Removed By Default
 
-**NOTE** This is a **Typescript compile-time only** change. Dot notation in filters sent to MongoDB will still work the same.
+**NOTE:** This is a **Typescript compile-time only** change. Dot notation in filters sent to MongoDB will still work the same.
 
 Version 4.3.0 introduced Typescript support for dot notation in filter predicates.  For example:
 

src/admin.ts

@@ -23,7 +23,6 @@ import {
   Callback,
   getTopology,
   hasAtomicOperators,
-  maybeCallback,
   MongoDBNamespace,
   resolveOptions
 } from '../utils';
@@ -1175,56 +1174,34 @@ export abstract class BulkOperationBase {
     return batches;
   }
 
-  execute(options?: BulkWriteOptions): Promise<BulkWriteResult>;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  execute(callback: Callback<BulkWriteResult>): void;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  execute(options: BulkWriteOptions | undefined, callback: Callback<BulkWriteResult>): void;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  execute(
-    options?: BulkWriteOptions | Callback<BulkWriteResult>,
-    callback?: Callback<BulkWriteResult>
-  ): Promise<BulkWriteResult> | void;
-  execute(
-    options?: BulkWriteOptions | Callback<BulkWriteResult>,
-    callback?: Callback<BulkWriteResult>
-  ): Promise<BulkWriteResult> | void {
-    callback =
-      typeof callback === 'function'
-        ? callback
-        : typeof options === 'function'
-        ? options
-        : undefined;
-    return maybeCallback(async () => {
-      options = options != null && typeof options !== 'function' ? options : {};
-
-      if (this.s.executed) {
-        throw new MongoBatchReExecutionError();
-      }
+  async execute(options: BulkWriteOptions = {}): Promise<BulkWriteResult> {
+    if (this.s.executed) {
+      throw new MongoBatchReExecutionError();
+    }
 
-      const writeConcern = WriteConcern.fromOptions(options);
-      if (writeConcern) {
-        this.s.writeConcern = writeConcern;
-      }
+    const writeConcern = WriteConcern.fromOptions(options);
+    if (writeConcern) {
+      this.s.writeConcern = writeConcern;
+    }
 
-      // If we have current batch
-      if (this.isOrdered) {
-        if (this.s.currentBatch) this.s.batches.push(this.s.currentBatch);
-      } else {
-        if (this.s.currentInsertBatch) this.s.batches.push(this.s.currentInsertBatch);
-        if (this.s.currentUpdateBatch) this.s.batches.push(this.s.currentUpdateBatch);
-        if (this.s.currentRemoveBatch) this.s.batches.push(this.s.currentRemoveBatch);
-      }
-      // If we have no operations in the bulk raise an error
-      if (this.s.batches.length === 0) {
-        throw new MongoInvalidArgumentError('Invalid BulkOperation, Batch cannot be empty');
-      }
+    // If we have current batch
+    if (this.isOrdered) {
+      if (this.s.currentBatch) this.s.batches.push(this.s.currentBatch);
+    } else {
+      if (this.s.currentInsertBatch) this.s.batches.push(this.s.currentInsertBatch);
+      if (this.s.currentUpdateBatch) this.s.batches.push(this.s.currentUpdateBatch);
+      if (this.s.currentRemoveBatch) this.s.batches.push(this.s.currentRemoveBatch);
+    }
+    // If we have no operations in the bulk raise an error
+    if (this.s.batches.length === 0) {
+      throw new MongoInvalidArgumentError('Invalid BulkOperation, Batch cannot be empty');
+    }
+
+    this.s.executed = true;
+    const finalOptions = { ...this.s.options, ...options };
+    const operation = new BulkWriteShimOperation(this, finalOptions);
 
-      this.s.executed = true;
-      const finalOptions = { ...this.s.options, ...options };
-      const operation = new BulkWriteShimOperation(this, finalOptions);
-      return executeOperation(this.s.collection.s.db.s.client, operation);
-    }, callback);
+    return executeOperation(this.s.collection.s.db.s.client, operation);
   }
 
   /**

src/bulk/common.ts

@@ -19,7 +19,7 @@ import type { AggregateOptions } from './operations/aggregate';
 import type { CollationOptions, OperationParent } from './operations/command';
 import type { ReadPreference } from './read_preference';
 import type { ServerSessionId } from './sessions';
-import { Callback, filterOptions, getTopology, maybeCallback, MongoDBNamespace } from './utils';
+import { filterOptions, getTopology, MongoDBNamespace } from './utils';
 
 /** @internal */
 const kCursorStream = Symbol('cursorStream');
@@ -637,99 +637,84 @@ export class ChangeStream<
   }
 
   /** Check if there is any document still available in the Change Stream */
-  hasNext(): Promise<boolean>;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  hasNext(callback: Callback<boolean>): void;
-  hasNext(callback?: Callback): Promise<boolean> | void {
+  async hasNext(): Promise<boolean> {
     this._setIsIterator();
-    return maybeCallback(async () => {
-      // Change streams must resume indefinitely while each resume event succeeds.
-      // This loop continues until either a change event is received or until a resume attempt
-      // fails.
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
+    // Change streams must resume indefinitely while each resume event succeeds.
+    // This loop continues until either a change event is received or until a resume attempt
+    // fails.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const hasNext = await this.cursor.hasNext();
+        return hasNext;
+      } catch (error) {
         try {
-          const hasNext = await this.cursor.hasNext();
-          return hasNext;
+          await this._processErrorIteratorMode(error);
         } catch (error) {
           try {
-            await this._processErrorIteratorMode(error);
-          } catch (error) {
-            try {
-              await this.close();
-            } catch {
-              // We are not concerned with errors from close()
-            }
-            throw error;
+            await this.close();
+          } catch {
+            // We are not concerned with errors from close()
           }
+          throw error;
         }
       }
-    }, callback);
+    }
   }
 
   /** Get the next available document from the Change Stream. */
-  next(): Promise<TChange>;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  next(callback: Callback<TChange>): void;
-  next(callback?: Callback<TChange>): Promise<TChange> | void {
+  async next(): Promise<TChange> {
     this._setIsIterator();
-    return maybeCallback(async () => {
-      // Change streams must resume indefinitely while each resume event succeeds.
-      // This loop continues until either a change event is received or until a resume attempt
-      // fails.
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
+    // Change streams must resume indefinitely while each resume event succeeds.
+    // This loop continues until either a change event is received or until a resume attempt
+    // fails.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const change = await this.cursor.next();
+        const processedChange = this._processChange(change ?? null);
+        return processedChange;
+      } catch (error) {
         try {
-          const change = await this.cursor.next();
-          const processedChange = this._processChange(change ?? null);
-          return processedChange;
+          await this._processErrorIteratorMode(error);
         } catch (error) {
           try {
-            await this._processErrorIteratorMode(error);
-          } catch (error) {
-            try {
-              await this.close();
-            } catch {
-              // We are not concerned with errors from close()
-            }
-            throw error;
+            await this.close();
+          } catch {
+            // We are not concerned with errors from close()
           }
+          throw error;
         }
       }
-    }, callback);
+    }
   }
 
   /**
    * Try to get the next available document from the Change Stream's cursor or `null` if an empty batch is returned
    */
-  tryNext(): Promise<Document | null>;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  tryNext(callback: Callback<Document | null>): void;
-  tryNext(callback?: Callback<Document | null>): Promise<Document | null> | void {
+  async tryNext(): Promise<Document | null> {
     this._setIsIterator();
-    return maybeCallback(async () => {
-      // Change streams must resume indefinitely while each resume event succeeds.
-      // This loop continues until either a change event is received or until a resume attempt
-      // fails.
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
+    // Change streams must resume indefinitely while each resume event succeeds.
+    // This loop continues until either a change event is received or until a resume attempt
+    // fails.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const change = await this.cursor.tryNext();
+        return change ?? null;
+      } catch (error) {
         try {
-          const change = await this.cursor.tryNext();
-          return change ?? null;
+          await this._processErrorIteratorMode(error);
         } catch (error) {
           try {
-            await this._processErrorIteratorMode(error);
-          } catch (error) {
-            try {
-              await this.close();
-            } catch {
-              // We are not concerned with errors from close()
-            }
-            throw error;
+            await this.close();
+          } catch {
+            // We are not concerned with errors from close()
           }
+          throw error;
         }
       }
-    }, callback);
+    }
   }
 
   async *[Symbol.asyncIterator](): AsyncGenerator<TChange, void, void> {
@@ -758,20 +743,15 @@ export class ChangeStream<
   }
 
   /** Close the Change Stream */
-  close(): Promise<void>;
-  /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com./mongodb-js/nodejs-mongodb-legacy) for migration assistance */
-  close(callback: Callback): void;
-  close(callback?: Callback): Promise<void> | void {
+  async close(): Promise<void> {
     this[kClosed] = true;
 
-    return maybeCallback(async () => {
-      const cursor = this.cursor;
-      try {
-        await cursor.close();
-      } finally {
-        this._endStream();
-      }
-    }, callback);
+    const cursor = this.cursor;
+    try {
+      await cursor.close();
+    } finally {
+      this._endStream();
+    }
   }
 
   /**
@@ -864,9 +844,7 @@ export class ChangeStream<
   private _closeEmitterModeWithError(error: AnyError): void {
     this.emit(ChangeStream.ERROR, error);
 
-    this.close(() => {
-      // nothing to do
-    });
+    this.close().catch(() => null);
   }
 
   /** @internal */