docs(NODE-4794): Clean up migration guide for BSON v5 (#557)

alexbevi · web-flow · commit 1c6be19efa00 · 2023-01-18T15:11:33.000-05:00
diff --git a/docs/upgrade-to-v5.md b/docs/upgrade-to-v5.md
@@ -3,18 +3,17 @@
 ## TOC
 
 - [Changes to Support Cross-platform JS API Compatibility](#changes-to-support-cross-platform-js-api-compatibility)
-  - [Remove reliance on Node.js Buffer](#remove-reliance-on-nodejs-buffer)
-    - [Impacted APIs now return Uint8Array in web environments; Node.js environments unaffected](#apis-impacted)
+  - [Remove reliance on Node.js `Buffer`](#remove-reliance-on-nodejs-buffer)
+    - [Impacted APIs now return `Uint8Array` in web environments; Node.js environments are unaffected](#apis-impacted)
   - [Restrict supported encodings in `ObjectId.toString` / `UUID.toString` / `Binary.toString`](#restrict-supported-encodings-in-objectidtostring--uuidtostring--binarytostring)
     - [Migration available if types beyond `'hex' | 'base64' | 'utf8'` are desired](#migration-example)
 - [Other Changes](#other-changes)
-  - [serializeFunctions bug fix](#serializefunctions-bug-fix)
+  - [`serializeFunctions` bug fix](#serializefunctions-bug-fix)
   - [TS "target" set to es2020](#ts-target-set-to-es2020)
 
 ## About
 
-The following is a detailed collection of the changes in the major v5 release of the bson package
-for Node.js and web platforms.
+The following is a detailed collection of the changes in the major v5 release of the BSON package for Node.js and web platforms.
 
 <!--
 1. a brief statement of what is breaking (brief as in "x will now return y instead of z", or "x is no longer supported, use y instead", etc
@@ -26,15 +25,15 @@ for Node.js and web platforms.
 
 ### Remove reliance on Node.js Buffer
 
-> **TL;DR**: Impacted APIs now return Uint8Array in web environments; Node.js environments unaffected
+> **TL;DR**: Impacted APIs now return `Uint8Array` in web environments; Node.js environments are unaffected
 
-For those that use the BSON library on Node.js, there is no change - the BSON APIs will still return and accept instances of Node.js Buffer. Since we no longer depend on the Buffer web shim for compatibility with browsers, in non-Node.js environments a Uint8Array will be returned instead.
+For those that use the BSON library on Node.js, there is no change - the BSON APIs will still return and accept instances of Node.js `Buffer`. Since we no longer depend on the `Buffer` web shim for compatibility with browsers, in non-Node.js environments a `Uint8Array` will be returned instead.
 
-This allows the BSON library to be better at platform independence while keeping its behavior consistent cross platform. The Buffer shim served the library well but brought in more than was necessary for the concerns of the code here.
+This allows the BSON library to be more platform independent while keeping its behavior consistent cross platform. 
 
 #### APIs impacted
 
-The following APIs now return Uint8Arrays when the library is loaded in an environment that does not define a global Node.js Buffer.
+The following APIs now return `Uint8Arrays` when the library is loaded in an environment that does not define a global Node.js `Buffer`.
 
 - `Binary.prototype.buffer`
 - `Binary.prototype.read()`
@@ -50,7 +49,7 @@ The following APIs now return Uint8Arrays when the library is loaded in an envir
 
 > **TL;DR**: The only supported encodings are: `'hex' | 'base64' | 'utf8'`
 
-The methods: `ObjectId.toString`, `UUID.toString`, and `Binary.toString` took encodings that were passed through to the Node.js Buffer API. As a result of no longer relying on the presence of `Buffer` we can no longer support [every encoding that Node.js does](https://nodejs.org/dist/latest-v16.x/docs/api/buffer.html#buffers-and-character-encodings). We continue to support `'hex'` and `'base64'` on all three methods and additionally `'utf-8' | 'utf8'` on `Binary.toString`. If any of the other encodings are desired the underlying buffer for all these classes are publicly accessible and while in Node.js will be stored as a Node.js buffer:
+The methods: `ObjectId.toString`, `UUID.toString`, and `Binary.toString` took encodings that were passed through to the Node.js `Buffer` API. As a result of no longer relying on the presence of `Buffer` we can no longer support [every encoding that Node.js does](https://nodejs.org/dist/latest-v16.x/docs/api/buffer.html#buffers-and-character-encodings). We continue to support `'hex'` and `'base64'` on all three methods and additionally `'utf-8' | 'utf8'` on `Binary.toString`. If any of the other encodings are desired the underlying buffer for all these classes are publicly accessible and while in Node.js will be stored as a Node.js buffer:
 
 #### Migration Example
 
@@ -70,34 +69,36 @@ new TextDecoder('utf-16le').decode(bin.value(true));
 
 ### TS "target" set to es2020
 
-We have set our typescript compilation target to `es2020` which aligns with our minimum supported Node.js version 14+. The following is from the typescript release notes on es2020 support, so it's some of the syntax that can be expected to be preserved after compilation:
+We have set our TypeScript compilation target to `es2020` which aligns with our minimum supported Node.js version 14+. The following is from the [TypeScript release notes on `es2020` support](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#es2020-for-target-and-module), so it's some of the syntax that can be expected to be preserved after compilation:
 
 > This will preserve newer ECMAScript 2020 features like optional chaining, nullish coalescing, export \* as ns, and dynamic import(...) syntax. It also means bigint literals now have a stable target below esnext.
 
-### serializeFunctions bug fix
+### `serializeFunctions` bug fix
 
-If serializeFunctions was enabled and the functions being serialized had a name that is outside of [Controls and Basic Latin](https://en.wikibooks.org/wiki/Unicode/Character_reference/0000-0FFF) character ranges (a.k.a utf8 bytes: 0x00-0x7F) they would be incorrectly serialized.
+If `serializeFunctions` was enabled and the functions being serialized had a name that is outside of [Controls and Basic Latin](https://en.wikibooks.org/wiki/Unicode/Character_reference/0000-0FFF) character ranges (a.k.a utf8 bytes: `0x00-0x7F`) they would be incorrectly serialized.
 
 ### Remove `Map` export
 
-This library no longer polyfills [ES Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and the export "Map" was removed. Users should migrate to using the global Map constructor available in all supported JS environments.
+This library no longer polyfills [ES Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and the export "`Map`" was removed. Users should migrate to using the global `Map` constructor available in all supported JS environments.
 
 ### `Decimal128` `toObject()` mapper support removed
 
-`Decimal128` can no longer have a `toObject()` method added on to its prototype for mapping to a custom value. This feature was undocumented and inconsistent with the rest of our BSON types. At this time there is no direct migration: cursors in the driver support transformations via `.map`, otherwise the `Decimal128` instances will require manual transformation. There is a plan to provide a better mechanism for consistently transforming BSON values tracked in [NODE-4680](https://jira.mongodb.org/browse/NODE-4680), please feel free to add a vote or comment with a use case to help us land the feature in the most useful form.
+`Decimal128` can no longer have a `toObject()` method added on to its prototype for mapping to a custom value. This feature was undocumented and inconsistent with the rest of our BSON types. 
 
-### Remove deprecated ObjectId methods
+At this time there is no direct migration. Cursors in the driver support transformations via `.map`, otherwise the `Decimal128` instances will require manual transformation. There is a plan to provide a better mechanism for consistently transforming BSON values tracked in [NODE-4680](https://jira.mongodb.org/browse/NODE-4680). Please feel free to add a vote or comment with a use case to help us land the feature in the most useful form.
+
+### Remove deprecated `ObjectId` methods
 
 The following deprecated methods have been removed:
 
 - `ObjectId.prototype.generate`
-  - Instead, generate a new ObjectId with the constructor: `new ObjectId()` or using the `static generate(time?: number)` method.
+  - Instead, generate a new `ObjectId` with the constructor: `new ObjectId()` or using the `static generate(time?: number)` method.
 - `ObjectId.prototype.generationTime`
   - Instead, use `static createFromTime()` and `getTimestamp()` to set and inspect these values on an `ObjectId()`
 - `ObjectId.prototype.getInc`
 - `ObjectId.prototype.get_inc`
 - `ObjectId.get_inc`
-  - The `static getInc()` is private since invoking it increments the next `ObjectId` index, so invoking would impact the creation of subsequent ObjectIds.
+  - The `static getInc()` is private since invoking it increments the next `ObjectId` index, so invoking would impact the creation of subsequent `ObjectId`s.
 
 ### BSON Element names are now fetched only from object's own properties
 
@@ -129,13 +130,13 @@ BSON.deserialize(BSON.serialize({ d: -0 }))
 // type preservation, returns { d: -0 }
 ```
 
-### Capital "D" ObjectID export removed
+### Capital "D" `ObjectID` export removed
 
 For clarity the deprecated and duplicate export `ObjectID` has been removed. `ObjectId` matches the class name and is equal in every way to the capital "D" export.
 
 ### Timestamp constructor validation
 
-The `Timestamp` type no longer accepts two number arguments for the low and high bits of the int64 value.
+The `Timestamp` type no longer accepts two number arguments for the low and high bits of the `int64` value.
 
 Supported constructors are as follows:
 
@@ -147,7 +148,7 @@ class Timestamp {
 }
 ```
 
-Any code that use the two number argument style of constructing a Timestamp will need to be migrated to one of the supported constructors. We recommend using the `{ t: number; i: number }` style input, representing the timestamp and increment respectively.
+Any code that uses the two number argument style of constructing a `Timestamp` will need to be migrated to one of the supported constructors. We recommend using the `{ t: number; i: number }` style input, representing the timestamp and increment respectively.
 
 ```typescript
 // in 4.x BSON
@@ -156,7 +157,7 @@ new Timestamp(1, 2); // as an int64: 8589934593
 new Timestamp({ t: 2, i: 1 }); // as an int64: 8589934593
 ```
 
-Additionally, the `t` and `i` fields of `{ t: number; i: number }` are now validated more strictly to ensure your Timestamps are being constructed as expected.
+Additionally, the `t` and `i` fields of `{ t: number; i: number }` are now validated more strictly to ensure your timestamps are being constructed as expected.
 
 For example:
 ```typescript
@@ -183,8 +184,8 @@ EJSON.stringify({}, { strict: false }); /* migrate to */ EJSON.stringify({}, { r
 
 ### The BSON default export has been removed.
 
-* If you import BSON commonjs style `const BSON = require('bson')` then the `BSON.default` property is no longer present.
-* If you import BSON esmodule style `import BSON from 'bson'` then this code will crash upon loading. **TODO: This is not the case right now but it will be after NODE-4713.**
+* If you import BSON `commonjs` style `const BSON = require('bson')` then the `BSON.default` property is no longer present.
+* If you import BSON `esmodule` style `import BSON from 'bson'` then this code will crash upon loading.
   * This error will throw: `SyntaxError: The requested module 'bson' does not provide an export named 'default'`.
 
 ### `class Code` always converts `.code` to string
@@ -201,9 +202,10 @@ const myCode = new Code(function iLoveJavascript() { console.log('I love javascr
 ### `BSON.deserialize()` only returns `Code` instances
 
 The deserialize options: `evalFunctions`, `cacheFunctions`, and `cacheFunctionsCrc32` have been removed.
-The `evalFunctions` option, when enabled, would return BSON Code typed values as eval-ed javascript functions, now it will always return Code instances.
+The `evalFunctions` option, when enabled, would return BSON `Code` typed values as eval-ed JavaScript functions, now it will always return `Code` instances.
 
 See the following snippet for how to migrate:
+
 ```typescript
 const bsonBytes = BSON.serialize(
   { iLoveJavascript: function () { console.log('I love javascript') } },
@@ -221,7 +223,7 @@ iLoveJavascript();
 ### `BSON.serialize()` validation
 
 The BSON format does not support encoding arrays as the **root** object.
-However, in javascript arrays are just objects where the keys are numeric (and a magic `length` property), so round tripping an array (ex. `[1, 2]`) though BSON would return `{ '0': 1, '1': 2 }`.
+However, in JavaScript arrays are just objects where the keys are numeric (and a magic `length` property), so round tripping an array (ex. `[1, 2]`) though BSON would return `{ '0': 1, '1': 2 }`.
 
 `BSON.serialize()` now validates input types, the input to serialize must be an object or a `Map`, arrays will now cause an error.
 
@@ -230,7 +232,7 @@ BSON.serialize([1, 2, 3])
 // BSONError: serialize does not support an array as the root input
 ```
 
-if the functionality of turning arrays into an object with numeric keys is useful see the following example:
+If the functionality of turning arrays into an object with numeric keys is useful, see the following example:
 
 ```typescript
 // Migration example:
@@ -242,20 +244,21 @@ BSON.deserialize(result)
 ### Exports and available bundles
 
 Most users should be unaffected by these changes, Node.js `require()` / Node.js `import` will fetch the corresponding BSON library as expected.
-And for folks using bundlers like, webpack or rollup a tree shakable es module bundle will be pulled in because of the settings in our package.json.
+And for folks using bundlers like webpack or rollup, a tree shakable ES module bundle will be pulled in because of the settings in our `package.json`.
 
-Our package.json defines the following `"exports"` settings.
+Our `package.json` defines the following `"exports"` settings.
 ```json
 {
   "main": "./lib/bson.cjs",
   "module": "./lib/bson.mjs",
-  "browser": "./lib/bson.mjs",
   "exports": {
-    "browser": "./lib/bson.mjs",
     "import": "./lib/bson.mjs",
-    "require": "./lib/bson.cjs"
-  }
+    "require": "./lib/bson.cjs",
+    "react-native": "./lib/bson.cjs",
+    "browser": "./lib/bson.mjs"
+  },
 }
+
 ```
 
 You can now find compiled bundles of the BSON library in 3 common formats in the `lib` directory.
@@ -267,14 +270,16 @@ You can now find compiled bundles of the BSON library in 3 common formats in the
 
 ### `BSONTypeError` removed and `BSONError` offers filtering functionality with `static isBSONError()`
 
-`BSONTypeError` has been removed because it was not a subclass of BSONError so would not return true for an `instanceof` check against `BSONError`. To learn more about our expectations of error handling see [this section of the mongodb driver's readme](https://github.com/mongodb/node-mongodb-native/tree/main#error-handling).
+`BSONTypeError` has been removed because it was not a subclass of BSONError so would not return true for an `instanceof` check against `BSONError`. To learn more about our expectations of error handling see [this section of the MongoDB Node.js Driver's README](https://github.com/mongodb/node-mongodb-native/tree/main#error-handling).
 
 
 A `BSONError` can be thrown from deep within a library that relies on BSON, having one error super class for the library helps with programmatic filtering of an error's origin.
+
 Since BSON can be used in environments where instances may originate from across realms, `BSONError` has a static `isBSONError()` method that helps with determining if an object is a `BSONError` instance (much like [Array.isArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)).
+
 It is our recommendation to use `isBSONError()` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `isBSONError()` 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.
 
-Hypothetical example: A collection in our Db has an issue with UTF-8 data:
+Hypothetical example: A collection in our database contains invalid UTF-8 data:
 ```ts
 let documentCount = 0;
 const cursor = collection.find({}, { utf8Validation: true });
@@ -291,8 +296,8 @@ try {
 
 ### Explicit cross version incompatibility
 
-Starting with v5.0.0 of the BSON library instances of types from previous versions will throw an error when passed to the serializer.
-This is to ensure that types are always serialized correctly and that there is no unexpected silent BSON serialization mistakes that could occur when mixing versions.
+Starting with v5.0.0 of the BSON library instances of types from previous versions will throw an error when passed to the serializer. This is to ensure that types are always serialized correctly and that there is no unexpected silent BSON serialization mistakes that could occur when mixing versions.
+
 It's unexpected for any applications to have more than one version of the BSON library but with nested dependencies and re-exporting, this new error will illuminate those incorrect combinations.
 
 ```ts
