Merge branch 'main' into NODE-4871/support_bigint_deserialization

Author: W-A-James

.evergreen/install-dependencies.sh

@@ -43,21 +43,8 @@ nvm use --lts
 
 set -o xtrace
 
-
-
-# setup npm cache in a local directory
-cat <<EOT > .npmrc
-devdir=${NPM_CACHE_DIR}/.node-gyp
-init-module=${NPM_CACHE_DIR}/.npm-init.js
-cache=${NPM_CACHE_DIR}
-tmp=${NPM_TMP_DIR}
-registry=https://registry.npmjs.org
-EOT
-
 # install node dependencies
-# npm prepare runs after install and will compile the library
-# TODO(NODE-3555): rollup dependencies for node polyfills have broken peerDeps. We can remove this flag once we've removed them.
-npm install --legacy-peer-deps
+npm install
 
 set +o xtrace
 echo "Running: nvm use ${NODE_VERSION}"

.evergreen/run-typescript.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -o errexit # Exit the script with error if any of the commands fail
 
-# source "${PROJECT_DIRECTORY}/.evergreen/init-nvm.sh"
+source "${PROJECT_DIRECTORY}/.evergreen/init-nvm.sh"
 
 set -o xtrace
 

.mocharc.json

@@ -12,5 +12,8 @@
   "timeout": 10000,
   "failZero": true,
   "sort": true,
-  "color": true
+  "color": true,
+  "node-option": [
+    "experimental-vm-modules"
+  ]
 }

README.md

@@ -1,10 +1,7 @@
 # BSON parser
 
-BSON is short for "Binary JSON," and is the binary-encoded serialization of JSON-like documents. You can learn more about it in [the specification](http://bsonspec.org).
-
-This browser version of the BSON parser is compiled using [rollup](https://rollupjs.org/) and the current version is pre-compiled in the `dist` directory.
-
-This is the default BSON parser, however, there is a C++ Node.js addon version as well that does not support the browser. It can be found at [mongod-js/bson-ext](https://github.com/mongodb-js/bson-ext).
+BSON is short for "Binary JSON," and is the binary-encoded serialization of JSON-like documents.
+You can learn more about it in [the specification](http://bsonspec.org).
 
 ### Table of Contents
 - [Usage](#usage)
@@ -32,106 +29,43 @@ npm install
 npm run build
 ```
 
-### Node (no bundling)
-A simple example of how to use BSON in `Node.js`:
+### Node.js or Bundling Usage
 
-```js
-const BSON = require('bson');
-const Long = BSON.Long;
+When using a bundler or Node.js you can import bson using the package name:
 
-// Serialize a document
-const doc = { long: Long.fromNumber(100) };
-const data = BSON.serialize(doc);
-console.log('data:', data);
+```js
+import { BSON, EJSON, ObjectId } from 'bson';
+// or:
+// const { BSON, EJSON, ObjectId } = require('bson');
 
-// Deserialize the resulting Buffer
-const doc_2 = BSON.deserialize(data);
-console.log('doc_2:', doc_2);
+const bytes = BSON.serialize({ _id: new ObjectId() });
+console.log(bytes);
+const doc = BSON.deserialize(bytes);
+console.log(EJSON.stringify(doc));
+// {"_id":{"$oid":"..."}}
 ```
 
-### Browser (no bundling)
+### Browser Usage
 
-If you are not using a bundler like webpack, you can include `dist/bson.bundle.js` using a script tag.  It includes polyfills for built-in node types like `Buffer`.
+If you are working directly in the browser without a bundler please use the `.mjs` bundle like so:
 
 ```html
-<script src="./dist/bson.bundle.js"></script>
-
-<script>
-  function start() {
-    // Get the Long type
-    const Long = BSON.Long;
-
-    // Serialize a document
-    const doc = { long: Long.fromNumber(100) }
-    const data = BSON.serialize(doc);
-    console.log('data:', data);
-
-    // De serialize it again
-    const doc_2 = BSON.deserialize(data);
-    console.log('doc_2:', doc_2);
-  }
+<script type="module">
+  import { BSON, EJSON, ObjectId } from './lib/bson.mjs';
+
+  const bytes = BSON.serialize({ _id: new ObjectId() });
+  console.log(bytes);
+  const doc = BSON.deserialize(bytes);
+  console.log(EJSON.stringify(doc));
+  // {"_id":{"$oid":"..."}}
 </script>
 ```
 
-### Using webpack
-
-If using webpack, you can use your normal import/require syntax of your project to pull in the `bson` library.
-
-ES6 Example:
-
-```js
-import { Long, serialize, deserialize } from 'bson';
-
-// Serialize a document
-const doc = { long: Long.fromNumber(100) };
-const data = serialize(doc);
-console.log('data:', data);
-
-// De serialize it again
-const doc_2 = deserialize(data);
-console.log('doc_2:', doc_2);
-```
-
-ES5 Example:
-
-```js
-const BSON = require('bson');
-const Long = BSON.Long;
-
-// Serialize a document
-const doc = { long: Long.fromNumber(100) };
-const data = BSON.serialize(doc);
-console.log('data:', data);
-
-// Deserialize the resulting Buffer
-const doc_2 = BSON.deserialize(data);
-console.log('doc_2:', doc_2);
-```
-
-Depending on your settings, webpack will under the hood resolve to one of the following:
-
-- `dist/bson.browser.esm.js` If your project is in the browser and using ES6 modules (Default for `webworker` and `web` targets)
-- `dist/bson.browser.umd.js` If your project is in the browser and not using ES6 modules
-- `dist/bson.esm.js` If your project is in Node.js and using ES6 modules (Default for `node` targets)
-- `lib/bson.js` (the normal include path) If your project is in Node.js and not using ES6 modules
-
-For more information, see [this page on webpack's `resolve.mainFields`](https://webpack.js.org/configuration/resolve/#resolvemainfields) and [the `package.json` for this project](./package.json#L52)
-
-### Usage with Angular
-
-Starting with Angular 6, Angular CLI removed the shim for `global` and other node built-in variables (original comment [here](https://github.com/angular/angular-cli/issues/9827#issuecomment-386154063)). If you are using BSON with Angular, you may need to add the following shim to your `polyfills.ts` file:
-
-```js
-// In polyfills.ts
-(window as any).global = window;
-```
-
-- [Original Comment by Angular CLI](https://github.com/angular/angular-cli/issues/9827#issuecomment-386154063)
-- [Original Source for Solution](https://stackoverflow.com/a/50488337/4930088)
-
 ## Installation
 
-`npm install bson`
+```sh
+npm install bson
+```
 
 ## Documentation
 
@@ -352,6 +286,29 @@ Deserialize stream data as BSON documents.
 
 **Returns**: <code>Number</code> - returns the next index in the buffer after deserialization **x** numbers of documents.
 
+## Error Handling
+
+It is our recommendation to use `BSONError.isBSONError()` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `BSONError.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.
+
+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 `BSONError.isBSONError()` will always be able to accurately capture the errors that our BSON library throws.
+
+Hypothetical example: A collection in our Db has an issue with UTF-8 data:
+
+```ts
+let documentCount = 0;
+const cursor = collection.find({}, { utf8Validation: true });
+try {
+  for await (const doc of cursor) documentCount += 1;
+} catch (error) {
+  if (BSONError.isBSONError(error)) {
+    console.log(`Found the troublemaker UTF-8!: ${documentCount} ${error.message}`);
+    return documentCount;
+  }
+  throw error;
+}
+```
+
 ## FAQ
 
 #### Why does `undefined` get converted to `null`?

docs/upgrade-to-v5.md

@@ -238,3 +238,53 @@ const result = BSON.serialize(Object.fromEntries([1, true, 'blue'].entries()))
 BSON.deserialize(result)
 // { '0': 1, '1': true, '2': 'blue' }
 ```
+
+### 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.
+
+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"
+  }
+}
+```
+
+You can now find compiled bundles of the BSON library in 3 common formats in the `lib` directory.
+
+- CommonJS - `lib/bson.cjs`
+- ES Module - `lib/bson.mjs`
+- Immediate Invoked Function Expression (IIFE) - `lib/bson.bundle.js`
+  - Typically used when trying to import JS on the web CDN style, but the ES Module (`.mjs`) bundle is fully browser compatible and should be preferred if it works in your use case.
+
+### `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).
+
+
+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:
+```ts
+let documentCount = 0;
+const cursor = collection.find({}, { utf8Validation: true });
+try {
+  for await (const doc of cursor) documentCount += 1;
+} catch (error) {
+  if (BSONError.isBSONError(error)) {
+    console.log(`Found the troublemaker UTF-8!: ${documentCount} ${error.message}`);
+    return documentCount;
+  }
+  throw error;
+}
+```

etc/rollup/rollup-plugin-require-rewriter/require_rewriter.mjs

@@ -0,0 +1,44 @@
+import MagicString from 'magic-string';
+
+const CRYPTO_IMPORT_ESM_SRC = `const nodejsRandomBytes = await (async () => {
+    try {
+        return (await import('node:crypto')).randomBytes;`;
+
+export class RequireRewriter {
+  /**
+   * Take the compiled source code input; types are expected to already have been removed
+   * Look for the function that depends on crypto, replace it with a top-level await
+   * and dynamic import for the node:crypto module.
+   *
+   * @param {string} code - source code of the module being transformed
+   * @param {string} id - module id (usually the source file name)
+   * @returns {{ code: string; map: import('magic-string').SourceMap }}
+   */
+  transform(code, id) {
+    if (!id.includes('node_byte_utils')) {
+      return;
+    }
+    if (!code.includes('const nodejsRandomBytes')) {
+      throw new Error(`Unexpected! 'const nodejsRandomBytes' is missing from ${id}`);
+    }
+
+    const start = code.indexOf('const nodejsRandomBytes');
+    const endString = `return require('node:crypto').randomBytes;`;
+    const end = code.indexOf(endString) + endString.length;
+
+    if (start < 0 || end < 0) {
+      throw new Error(
+        `Unexpected! 'const nodejsRandomBytes' or 'return require('node:crypto').randomBytes;' not found`
+      );
+    }
+
+    // MagicString lets us edit the source code and still generate an accurate source map
+    const magicString = new MagicString(code);
+    magicString.overwrite(start, end, CRYPTO_IMPORT_ESM_SRC);
+
+    return {
+      code: magicString.toString(),
+      map: magicString.generateMap({ hires: true })
+    };
+  }
+}