Merge branch 'main' into NODE-4892-version-tag

Author: nbbeeken

README.md

@@ -285,6 +285,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

@@ -264,3 +264,27 @@ You can now find compiled bundles of the BSON library in 3 common formats in the
 - 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;
+}
+```

src/binary.ts

@@ -1,7 +1,7 @@
 import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
 import { isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
-import { BSONError, BSONTypeError } from './error';
+import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW, BSON_MAJOR_VERSION } from './constants';
 import { ByteUtils } from './utils/byte_utils';
 
@@ -86,7 +86,7 @@ export class Binary {
       !(buffer instanceof ArrayBuffer) &&
       !Array.isArray(buffer)
     ) {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Binary can only be constructed from string, Buffer, TypedArray, or Array<number>'
       );
     }
@@ -121,9 +121,9 @@ export class Binary {
   put(byteValue: string | number | Uint8Array | number[]): void {
     // If it's a string and a has more than one character throw an error
     if (typeof byteValue === 'string' && byteValue.length !== 1) {
-      throw new BSONTypeError('only accepts single character String');
+      throw new BSONError('only accepts single character String');
     } else if (typeof byteValue !== 'number' && byteValue.length !== 1)
-      throw new BSONTypeError('only accepts single character Uint8Array or Array');
+      throw new BSONError('only accepts single character Uint8Array or Array');
 
     // Decode the byte value once
     let decodedByte: number;
@@ -136,7 +136,7 @@ export class Binary {
     }
 
     if (decodedByte < 0 || decodedByte > 255) {
-      throw new BSONTypeError('only accepts number in a valid unsigned byte range 0-255');
+      throw new BSONError('only accepts number in a valid unsigned byte range 0-255');
     }
 
     if (this.buffer.byteLength > this.position) {
@@ -283,7 +283,7 @@ export class Binary {
       data = uuidHexStringToBuffer(doc.$uuid);
     }
     if (!data) {
-      throw new BSONTypeError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
+      throw new BSONError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
     }
     return type === BSON_BINARY_SUBTYPE_UUID_NEW ? new UUID(data) : new Binary(data, type);
   }
@@ -337,7 +337,7 @@ export class UUID extends Binary {
     } else if (typeof input === 'string') {
       bytes = uuidHexStringToBuffer(input);
     } else {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Argument passed in UUID constructor must be a UUID, a 16 byte Buffer or a 32/36 character hex string (dashes excluded/included, format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).'
       );
     }

src/bson.ts

@@ -49,7 +49,7 @@ export {
   BSONRegExp,
   Decimal128
 };
-export { BSONError, BSONTypeError } from './error';
+export { BSONError } from './error';
 export { BSONType } from './constants';
 export { EJSON } from './extended_json';
 

src/decimal128.ts

@@ -1,5 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
-import { BSONTypeError } from './error';
+import { BSONError } from './error';
 import { Long } from './long';
 import { isUint8Array } from './parser/utils';
 import { ByteUtils } from './utils/byte_utils';
@@ -114,7 +114,7 @@ function lessThan(left: Long, right: Long): boolean {
 }
 
 function invalidErr(string: string, message: string) {
-  throw new BSONTypeError(`"${string}" is not a valid Decimal128 string - ${message}`);
+  throw new BSONError(`"${string}" is not a valid Decimal128 string - ${message}`);
 }
 
 /** @public */
@@ -147,11 +147,11 @@ export class Decimal128 {
       this.bytes = Decimal128.fromString(bytes).bytes;
     } else if (isUint8Array(bytes)) {
       if (bytes.byteLength !== 16) {
-        throw new BSONTypeError('Decimal128 must take a Buffer of 16 bytes');
+        throw new BSONError('Decimal128 must take a Buffer of 16 bytes');
       }
       this.bytes = bytes;
     } else {
-      throw new BSONTypeError('Decimal128 must take a Buffer or string');
+      throw new BSONError('Decimal128 must take a Buffer or string');
     }
   }
 
@@ -206,7 +206,7 @@ export class Decimal128 {
     // TODO: implementing a custom parsing for this, or refactoring the regex would yield
     //       further gains.
     if (representation.length >= 7000) {
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
     }
 
     // Results
@@ -216,7 +216,7 @@ export class Decimal128 {
 
     // Validate the string
     if ((!stringMatch && !infMatch && !nanMatch) || representation.length === 0) {
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
     }
 
     if (stringMatch) {
@@ -288,7 +288,7 @@ export class Decimal128 {
     }
 
     if (sawRadix && !nDigitsRead)
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
 
     // Read exponent if exists
     if (representation[index] === 'e' || representation[index] === 'E') {

src/error.ts

@@ -1,21 +1,45 @@
-/** @public */
+/**
+ * @public
+ * `BSONError` objects are thrown when runtime errors occur.
+ */
 export class BSONError extends Error {
-  constructor(message: string) {
-    super(message);
+  /**
+   * @internal
+   * The underlying algorithm for isBSONError may change to improve how strict it is
+   * about determining if an input is a BSONError. But it must remain backwards compatible
+   * with previous minors & patches of the current major version.
+   */
+  protected get bsonError(): true {
+    return true;
   }
 
-  get name(): string {
+  override get name(): string {
     return 'BSONError';
   }
-}
 
-/** @public */
-export class BSONTypeError extends TypeError {
   constructor(message: string) {
     super(message);
   }
 
-  get name(): string {
-    return 'BSONTypeError';
+  /**
+   * @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
+   */
+  public static isBSONError(value: unknown): value is BSONError {
+    return (
+      value != null &&
+      typeof value === 'object' &&
+      'bsonError' in value &&
+      value.bsonError === true &&
+      // Do not access the following properties, just check existence
+      'name' in value &&
+      'message' in value &&
+      'stack' in value
+    );
   }
 }

src/extended_json.ts

@@ -5,7 +5,7 @@ import { BSON_INT32_MAX, BSON_INT32_MIN, BSON_INT64_MAX, BSON_INT64_MIN } from '
 import { DBRef, isDBRefLike } from './db_ref';
 import { Decimal128 } from './decimal128';
 import { Double } from './double';
-import { BSONError, BSONTypeError } from './error';
+import { BSONError } from './error';
 import { Int32 } from './int_32';
 import { Long } from './long';
 import { MaxKey } from './max_key';
@@ -192,7 +192,7 @@ function serializeValue(value: any, options: EJSONSerializeOptions): any {
         circularPart.length + (alreadySeen.length + current.length) / 2 - 1
       );
 
-      throw new BSONTypeError(
+      throw new BSONError(
         'Converting circular structure to EJSON:\n' +
           `    ${leadingPart}${alreadySeen}${circularPart}${current}\n` +
           `    ${leadingSpace}\\${dashes}/`
@@ -324,7 +324,7 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
       // Copy the object into this library's version of that type.
       const mapper = BSON_TYPE_MAPPINGS[doc._bsontype];
       if (!mapper) {
-        throw new BSONTypeError('Unrecognized or invalid _bsontype: ' + doc._bsontype);
+        throw new BSONError('Unrecognized or invalid _bsontype: ' + doc._bsontype);
       }
       outDoc = mapper(outDoc);
     }

src/long.ts

@@ -1,4 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
+import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import type { Timestamp } from './timestamp';
 
@@ -250,7 +251,7 @@ export class Long {
    * @returns The corresponding Long value
    */
   static fromString(str: string, unsigned?: boolean, radix?: number): Long {
-    if (str.length === 0) throw Error('empty string');
+    if (str.length === 0) throw new BSONError('empty string');
     if (str === 'NaN' || str === 'Infinity' || str === '+Infinity' || str === '-Infinity')
       return Long.ZERO;
     if (typeof unsigned === 'number') {
@@ -260,10 +261,10 @@ export class Long {
       unsigned = !!unsigned;
     }
     radix = radix || 10;
-    if (radix < 2 || 36 < radix) throw RangeError('radix');
+    if (radix < 2 || 36 < radix) throw new BSONError('radix');
 
     let p;
-    if ((p = str.indexOf('-')) > 0) throw Error('interior hyphen');
+    if ((p = str.indexOf('-')) > 0) throw new BSONError('interior hyphen');
     else if (p === 0) {
       return Long.fromString(str.substring(1), unsigned, radix).neg();
     }
@@ -431,7 +432,7 @@ export class Long {
    */
   divide(divisor: string | number | Long | Timestamp): Long {
     if (!Long.isLong(divisor)) divisor = Long.fromValue(divisor);
-    if (divisor.isZero()) throw Error('division by zero');
+    if (divisor.isZero()) throw new BSONError('division by zero');
 
     // use wasm support if present
     if (wasm) {
@@ -959,7 +960,7 @@ export class Long {
    */
   toString(radix?: number): string {
     radix = radix || 10;
-    if (radix < 2 || 36 < radix) throw RangeError('radix');
+    if (radix < 2 || 36 < radix) throw new BSONError('radix');
     if (this.isZero()) return '0';
     if (this.isNegative()) {
       // Unsigned Longs are never negative

src/objectid.ts

@@ -1,5 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
-import { BSONTypeError } from './error';
+import { BSONError } from './error';
 import { isUint8Array } from './parser/utils';
 import { BSONDataView, ByteUtils } from './utils/byte_utils';
 
@@ -57,9 +57,7 @@ export class ObjectId {
     let workingId;
     if (typeof inputId === 'object' && inputId && 'id' in inputId) {
       if (typeof inputId.id !== 'string' && !ArrayBuffer.isView(inputId.id)) {
-        throw new BSONTypeError(
-          'Argument passed in must have an id that is of type string or Buffer'
-        );
+        throw new BSONError('Argument passed in must have an id that is of type string or Buffer');
       }
       if ('toHexString' in inputId && typeof inputId.toHexString === 'function') {
         workingId = ByteUtils.fromHex(inputId.toHexString());
@@ -85,17 +83,17 @@ export class ObjectId {
         if (bytes.byteLength === 12) {
           this[kId] = bytes;
         } else {
-          throw new BSONTypeError('Argument passed in must be a string of 12 bytes');
+          throw new BSONError('Argument passed in must be a string of 12 bytes');
         }
       } else if (workingId.length === 24 && checkForHexRegExp.test(workingId)) {
         this[kId] = ByteUtils.fromHex(workingId);
       } else {
-        throw new BSONTypeError(
+        throw new BSONError(
           'Argument passed in must be a string of 12 bytes or a string of 24 hex characters or an integer'
         );
       }
     } else {
-      throw new BSONTypeError('Argument passed in does not match the accepted types');
+      throw new BSONError('Argument passed in does not match the accepted types');
     }
     // If we are caching the hex string
     if (ObjectId.cacheHexString) {
@@ -271,7 +269,7 @@ export class ObjectId {
   static createFromHexString(hexString: string): ObjectId {
     // Throw an error if it's not a valid setup
     if (typeof hexString === 'undefined' || (hexString != null && hexString.length !== 24)) {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Argument passed in must be a single String of 12 bytes or a string of 24 hex characters'
       );
     }