bson 5.0.0-alpha.1 → 5.0.0-alpha.2

package/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
 
@@ -304,12 +238,13 @@ Serialize a Javascript object using a predefined Buffer and index into the buffe
 | buffer | <code>Buffer</code> |  | the buffer containing the serialized set of BSON documents. |
 | [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
 | [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
+| [options.useBigInt64] | <code>Object</code> | <code>false</code> | when deserializing a Long will return a BigInt. |
 | [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
 | [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
 | [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
 | [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
 | [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
-| [options.allowObjectSmallerThanBufferSize] | <code>boolean</code> | <code>false</code> | allows the buffer to be larger than the parsed BSON object |
+| [options.allowObjectSmallerThanBufferSize] | <code>boolean</code> | <code>false</code> | allows the buffer to be larger than the parsed BSON object. |
 
 Deserialize data as BSON.
 
@@ -351,6 +286,63 @@ 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;
+}
+```
+
+## React Native
+
+BSON requires that `TextEncoder`, `TextDecoder`, `atob`, `btoa`, and `crypto.getRandomValues` are available globally.  These are present in most Javascript runtimes but require polyfilling in React Native.  Polyfills for the missing functionality can be installed with the following command:
+```sh
+npm install --save react-native-get-random-values text-encoding-polyfill base-64
+```
+
+The following snippet should be placed at the top of the entrypoint (by default this is the root `index.js` file) for React Native projects using the BSON library.  These lines must be placed for any code that imports `BSON`.
+
+```typescript
+// Required Polyfills For ReactNative
+import {encode, decode} from 'base-64';
+if (global.btoa == null) {
+  global.btoa = encode;
+}
+if (global.atob == null) {
+  global.atob = decode;
+}
+import 'text-encoding-polyfill';
+import 'react-native-get-random-values';
+```
+
+Finally, import the `BSON` library like so:
+
+```typescript
+import { BSON, EJSON } from 'bson';
+```
+
+This will cause React Native to import the `node_modules/bson/lib/bson.cjs` bundle (see the `"react-native"` setting we have in the `"exports"` section of our [package.json](./package.json).)
+
+### Technical Note about React Native module import
+
+The `"exports"` definition in our `package.json` will result in BSON's CommonJS bundle being imported in a React Native project instead of the ES module bundle.  Importing the CommonJS bundle is necessary because BSON's ES module bundle of BSON uses top-level await, which is not supported syntax in [React Native's runtime hermes](https://hermesengine.dev/).
+
 ## FAQ
 
 #### Why does `undefined` get converted to `null`?

package/bson.d.ts

@@ -142,7 +142,6 @@ declare namespace BSON {
         BSONRegExp,
         Decimal128,
         BSONError,
-        BSONTypeError,
         BSONType,
         EJSON,
         Document,
@@ -151,10 +150,24 @@ declare namespace BSON {
 }
 export { BSON }
 
-/** @public */
+/**
+ * @public
+ * `BSONError` objects are thrown when runtime errors occur.
+ */
 export declare class BSONError extends Error {
-    constructor(message: string);
+    /* Excluded from this release type: bsonError */
     get name(): string;
+    constructor(message: string);
+    /**
+     * @public
+     *
+     * All errors thrown from the BSON library inherit from `BSONError`.
+     * This method can assist with determining if an error originates from the BSON library
+     * even if it does not pass an `instanceof` check against this class' constructor.
+     *
+     * @param value - any javascript value that needs type checking
+     */
+    static isBSONError(value: unknown): value is BSONError;
 }
 
 /**
@@ -245,12 +258,6 @@ export declare const BSONType: Readonly<{
 /** @public */
 export declare type BSONType = typeof BSONType[keyof typeof BSONType];
 
-/** @public */
-export declare class BSONTypeError extends TypeError {
-    constructor(message: string);
-    get name(): string;
-}
-
 /**
  * Calculate the bson size for a passed in Javascript object.
  *
@@ -367,7 +374,9 @@ export declare function deserialize(buffer: Uint8Array, options?: DeserializeOpt
 
 /** @public */
 export declare interface DeserializeOptions {
-    /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits */
+    /** when deserializing a Long will return as a BigInt. */
+    useBigInt64?: boolean;
+    /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
     promoteLongs?: boolean;
     /** when deserializing a Binary will return it as a node.js Buffer instance. */
     promoteBuffers?: boolean;
@@ -377,7 +386,7 @@ export declare interface DeserializeOptions {
     fieldsAsRaw?: Document;
     /** return BSON regular expressions as BSONRegExp instances. */
     bsonRegExp?: boolean;
-    /** allows the buffer to be larger than the parsed BSON object */
+    /** allows the buffer to be larger than the parsed BSON object. */
     allowObjectSmallerThanBufferSize?: boolean;
     /** Offset into buffer to begin reading document from */
     index?: number;