docs(NODE-4916, NODE-4523): update readme and upgrade guide with callback removal information (#3540)

baileympearson · web-flow · commit c2da84e67667 · 2023-01-26T16:47:25.000-05:00
diff --git a/README.md b/README.md
@@ -2,20 +2,20 @@
 
 The official [MongoDB](https://www.mongodb.com/) driver for Node.js.
 
-**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_4.0.0.md)!**
+**Upgrading to version 5? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_5.0.0.md)!**
 
 ## Quick Links
 
-| what          | where                                                                                                   |
-| ------------- | ------------------------------------------------------------------------------------------------------- |
-| documentation | [www.mongodb.com/docs/drivers/node](https://www.mongodb.com/docs/drivers/node)                          |
-| api-doc       | [mongodb.github.io/node-mongodb-native](https://mongodb.github.io/node-mongodb-native)                  |
-| npm package   | [www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb)                                  |
-| source        | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native)                |
-| mongodb       | [www.mongodb.com](https://www.mongodb.com)                                                              |
-| changelog     | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md)                       |
-| upgrade to v4 | [etc/notes/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_4.0.0.md) |
-| contributing  | [CONTRIBUTING.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTING.md)             |
+| what          | where                                                                                                             |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| documentation | [www.mongodb.com/docs/drivers/node](https://www.mongodb.com/docs/drivers/node)                                    |
+| api-doc       | [mongodb.github.io/node-mongodb-native](https://mongodb.github.io/node-mongodb-native)                            |
+| npm package   | [www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb)                                            |
+| source        | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native)                          |
+| mongodb       | [www.mongodb.com](https://www.mongodb.com)                                                                        |
+| changelog     | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md)                                 |
+| upgrade to v5 | [etc/notes/CHANGES_5.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_5.0.0.md) |
+| contributing  | [CONTRIBUTING.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTING.md)                       |
 
 ### Bugs / Feature Requests
 
@@ -53,7 +53,7 @@ If you run into any unexpected compiler failures against our supported TypeScrip
 
 ## Installation
 
-The recommended way to get started using the Node.js 4.x driver is by using the `npm` (Node Package Manager) to install the dependency in your project.
+The recommended way to get started using the Node.js 5.x driver is by using the `npm` (Node Package Manager) to install the dependency in your project.
 
 After you've created your own project using `npm init`, you can run:
 
@@ -89,7 +89,6 @@ Third party:
 - Snappy network compression - [snappy](https://github.com/Brooooooklyn/snappy)
 - AWS authentication - [@aws-sdk/credential-providers](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/credential-providers)
 
-
 ## Quick Start
 
 This guide will show you how to set up a simple application using Node.js and MongoDB. Its scope is only how to set up the driver and perform the simple CRUD operations. For more in-depth coverage, see the [official documentation](https://docs.mongodb.com/drivers/node/).
@@ -136,18 +135,14 @@ operations using the MongoDB driver.
 
 Add code to connect to the server and the database **myProject**:
 
-> **NOTE:** All the examples below use async/await syntax.
->
-> However, all async API calls support an optional callback as the final argument,
-> if a callback is provided a Promise will not be returned.
-
 > **NOTE:** Resolving DNS Connection issues
 >
 > Node.js 18 changed the default DNS resolution ordering from always prioritizing ipv4 to the ordering
-> returned by the DNS provider.  In some environments, this can result in `localhost` resolving to
+> returned by the DNS provider. In some environments, this can result in `localhost` resolving to
 > an ipv6 address instead of ipv4 and a consequent failure to connect to the server.
 >
 > This can be resolved by:
+>
 > - specifying the ip address family using the MongoClient `family` option (`MongoClient(<uri>, { family: 4 } )`)
 > - launching mongod or mongos with the ipv6 flag enabled ([--ipv6 mongod option documentation](https://www.mongodb.com/docs/manual/reference/program/mongod/#std-option-mongod.--ipv6))
 > - using a host of `127.0.0.1` in place of localhost
@@ -267,7 +262,7 @@ It is our recommendation to use `instanceof` checks on errors and to avoid relyi
 We guarantee `instanceof` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.
 
 Any new errors we add to the driver will directly extend an existing error class and no existing error will be moved to a different parent class outside of a major release.
-This means `instanceof` will always be able to accurately capture the errors that our driver throws (or returns in a callback).
+This means `instanceof` will always be able to accurately capture the errors that our driver throws.
 
 ```typescript
 const client = new MongoClient(url);
diff --git a/etc/notes/CHANGES_5.0.0.md b/etc/notes/CHANGES_5.0.0.md
@@ -18,6 +18,74 @@ The following is a detailed collection of the changes in the major v5 release of
 
 ### Optional callback support migrated to `mongodb-legacy`
 
+Node v5 drops support for callbacks in favor of a promise-only API. Below are some strategies for
+callback users to adopt driver v5 in order of most recommended to least recommended.
+
+The Node driver team understands that a callback to promise migration can be a non-trivial refactor. To help inform your migration strategy, we've outlined three different approaches below.
+
+#### Migrate to promise based api (recommended!)
+
+The Node team strongly encourages anyone who is able to migrate from callbacks to promises to do so. Adopting the
+regular driver API will streamline the adoption of future driver updates, as well as provide better Typescript support
+than the other options outlined in this document.
+
+The promise-based API is identical to the callback API except:
+
+- no callback is accepted as the last argument
+- a promise is always returned
+
+For example, with a findOne query:
+
+```typescript
+// callback-based API
+collection.findOne({ name: 'john snow' }, (error, result) => {
+  if (error) {
+    /* do something with error */
+    return;
+  }
+
+  /* do something with result */
+});
+
+// promise-based API
+collection
+  .findOne({ name: 'john snow' })
+  .then(() => {
+    /* do something with result */
+  })
+  .catch(error => {
+    /* do something with error */
+  });
+
+// promise-based API with async/await
+try {
+  const result = await collection.findOne({ name: 'john snow' });
+  /* do something with result */
+} catch (error) {
+  /* do something with error */
+}
+```
+
+#### Use the promise-based API and `util.callbackify`
+
+If you only have a few callback instances where you are currently unable to adopt the promise API, we recommend using the promise API and Nodejs's `callbackify`
+utility to adapt the promise-based API to use callbacks.
+
+**Note** Manually converting a promise-based api to a callback-based API is error prone. We strongly encourage the use of `callbackify`.
+
+We recommend using callbackify with an anonymous function that has the same signature as the collection
+method.
+
+```typescript
+const callbackFindOne = callbackify((query, options) => collection.findOne(query, options));
+
+callbackFindOne({ name: 'john snow' }, {}, (error, result) => {
+  // handle error or result
+});
+```
+
+#### Add `mongodb-legacy` as a dependency and update imports to use `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:
 
@@ -26,7 +94,11 @@ We have migrated it to a new package:
 
 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
+`mongodb-legacy` is intended to preserve driver v4 behavior to enable a smoother transition between
+driver v4 and v5. However, new features will **only** only support a promise-based
+API in both the driver **and** the legacy driver.
+
+##### 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:
 
@@ -40,10 +112,10 @@ 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({})
+    const result = await collection.findOne({});
     res.end(JSON.stringify(result));
   } catch (error) {
-    res.errorHandling(error)
+    res.errorHandling(error);
   }
 });
 
@@ -62,45 +134,45 @@ app.get('/endpoint_callbacks', (req, res) => {
 });
 ```
 
-
 ### 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.
 
-Version 4.3.0 introduced Typescript support for dot notation in filter predicates.  For example:
+Version 4.3.0 introduced Typescript support for dot notation in filter predicates. For example:
 
 ```typescript
 interface Schema {
   user: {
-    name: string
-  }
+    name: string;
+  };
 }
 
 declare const collection: Collection<Schema>;
 // compiles pre-v4.3.0, fails in v4.3.0+
-collection.find({ 'user.name': 4 })
+collection.find({ 'user.name': 4 });
 ```
 
 This change caused a number of problems for users, including slow compilation times and compile errors for
 valid dot notation queries. While we have tried to mitigate this issue as much as possible
 in v4, ultimately we do not believe that this feature is fully production ready for all use cases.
 
-Driver 5.0 removes type checking for dot notation in filter predicates.  The preceding example will compile with
+Driver 5.0 removes type checking for dot notation in filter predicates. The preceding example will compile with
 driver v5.
 
 #### Dot Notation Helper Types Exported
 
 Although we removed support for type checking on dot notation filters by default, we have preserved the
 corresponding types in an experimental capacity.
-These helper types can be used for type checking.  We export the `StrictUpdateFilter` and the `StrictFilter`
+These helper types can be used for type checking. We export the `StrictUpdateFilter` and the `StrictFilter`
 types for type safety in updates and finds.
 
 To use one of the new types, simply create a predicate that uses dot notation and assign it the type of `StrictFilter<your schema>`.
+
 ```typescript
 interface Schema {
   user: {
-    name: string
-  }
+    name: string;
+  };
 }
 
 declare const collection: Collection<Schema>;
@@ -114,8 +186,8 @@ collection.find(filterPredicate);
 
 ### `Collection.mapReduce()` helper removed
 
-The `mapReduce` helper has been removed from the `Collection` class.  The `mapReduce` operation has been
-deprecated in favor of the aggregation pipeline since MongoDB server version 5.0.  It is recommended
+The `mapReduce` helper has been removed from the `Collection` class. The `mapReduce` operation has been
+deprecated in favor of the aggregation pipeline since MongoDB server version 5.0. It is recommended
 to migrate code that uses `Collection.mapReduce` to use the aggregation pipeline (see [Map-Reduce to Aggregation Pipeline](https://www.mongodb.com/docs/manual/reference/map-reduce-to-aggregation-pipeline/)).
 
 If the `mapReduce` command must be used, the `Db.command()` helper can be used to run the raw
@@ -126,13 +198,17 @@ If the `mapReduce` command must be used, the `Db.command()` helper can be used t
 const collection = db.collection('my-collection');
 
 await collection.mapReduce(
-  function() { emit(this.user_id, 1); },
-  function(k, vals) { return 1 },
+  function () {
+    emit(this.user_id, 1);
+  },
+  function (k, vals) {
+    return 1;
+  },
   {
     out: 'inline',
     readConcern: 'majority'
   }
-)
+);
 
 // manually running the command using `db.command()`
 const command = {
@@ -141,7 +217,7 @@ const command = {
   reduce: 'function(k,vals) { return 1; }',
   out: 'inline',
   readConcern: 'majority'
-}
+};
 
 await db.command(command);
 ```
@@ -155,7 +231,7 @@ The `digestPassword` option has been removed from the add user helper.
 
 ### Removal of Internal Types from Public API
 
-The following types are used internally the driver but were accidentally exported.  They have now been
+The following types are used internally the driver but were accidentally exported. They have now been
 marked internal and are no longer exported.
 
 - ServerSelector
@@ -176,7 +252,7 @@ For clarity the deprecated and duplicate export ObjectID has been removed. Objec
 
 ### `Projection` and `ProjectionOperations` Types Removed
 
-Both of these types were unused but exported.  These types have been removed.  Please
+Both of these types were unused but exported. These types have been removed. Please
 use `Document` instead.
 
 ### `CommandOperationOptions.fullResponse` Option Removed
@@ -185,11 +261,11 @@ The `fullResponse` option on the `CommandOperationOptions` as unused in the driv
 
 ### `BulkWriteOptions.keepGoing` Option Removed
 
-The `keepGoing` option on the `BulkWriteOptions` has been removed.  Please use the `ordered` option instead.
+The `keepGoing` option on the `BulkWriteOptions` has been removed. Please use the `ordered` option instead.
 
 ### `WriteConcernError.err()` Removed
 
-The `err()` getter on the WriteConcernError class has been removed.  The `toJSON()` method can be in place
+The `err()` getter on the WriteConcernError class has been removed. The `toJSON()` method can be in place
 of `err()`.
 
 ### slaveOk options removed
@@ -220,7 +296,6 @@ npm install --save "snappy@^7.2.2"
 
 The `.unref()` method was a no-op and has now been removed from the Db class.
 
-
 ### @aws-sdk/credential-providers v3.201.0 or later and optional peerDependency
 
 `@aws-sdk/credential-providers` has been added to the package.json as a peerDependency that is **optional**.
@@ -255,7 +330,7 @@ for await (const doc of cursor) {
   break;
 }
 
-cursor.closed // true
+cursor.closed; // true
 ```
 
 ### Driver now sends `1` instead of `true` for hello commands
@@ -267,14 +342,14 @@ previous `true` for spec compliance.
 
 Three legacy operation helpers on the collection class have been removed:
 
-| Removed API                                    | API to migrate to                                  |
-|------------------------------------------------|----------------------------------------------------|
-| `insert(document)`                             | `insertOne(document)`                              |
-| `insert(arrayOfDocuments)`                     | `insertMany(arrayOfDocuments)`                     |
-| `update(filter)`                               | `updateMany(filter)`                               |
-| `remove(filter)`                               | `deleteMany(filter)`                               |
+| Removed API                | API to migrate to              |
+| -------------------------- | ------------------------------ |
+| `insert(document)`         | `insertOne(document)`          |
+| `insert(arrayOfDocuments)` | `insertMany(arrayOfDocuments)` |
+| `update(filter)`           | `updateMany(filter)`           |
+| `remove(filter)`           | `deleteMany(filter)`           |
 
-The `insert` method accepted an array of documents for multi-document inserts and a single document for single document inserts.  `insertOne` should now be used for single-document inserts and `insertMany` should be used for multi-document inserts.
+The `insert` method accepted an array of documents for multi-document inserts and a single document for single document inserts. `insertOne` should now be used for single-document inserts and `insertMany` should be used for multi-document inserts.
 
 ```ts
 // Single document insert:
@@ -283,9 +358,9 @@ await collection.insert({ name: 'spot' });
 await collection.insertOne({ name: 'spot' });
 
 // Multi-document insert:
-await collection.insert([{ name: 'fido' }, { name: 'luna' }])
+await collection.insert([{ name: 'fido' }, { name: 'luna' }]);
 // Migration:
-await collection.insertMany([{ name: 'fido' }, { name: 'luna' }])
+await collection.insertMany([{ name: 'fido' }, { name: 'luna' }]);
 ```
 
 ### Removed `keepGoing` option from `BulkWriteOptions`
@@ -306,11 +381,11 @@ To access the raw result, please use `bulkWriteResult.getRawResponse()`.
 These can be accessed via:
 
 ```ts
-  bulkWriteResult.insertedCount;
-  bulkWriteResult.matchedCount;
-  bulkWriteResult.modifiedCount;
-  bulkWriteResult.deletedCount;
-  bulkWriteResult.upsertedCount;
-  bulkWriteResult.upsertedIds;
-  bulkWriteResult.insertedIds;
+bulkWriteResult.insertedCount;
+bulkWriteResult.matchedCount;
+bulkWriteResult.modifiedCount;
+bulkWriteResult.deletedCount;
+bulkWriteResult.upsertedCount;
+bulkWriteResult.upsertedIds;
+bulkWriteResult.insertedIds;
 ```
