bson 6.2.0 → 6.3.0

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -27,41 +27,42 @@
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
-    "@microsoft/api-extractor": "^7.36.4",
+    "@microsoft/api-extractor": "^7.38.4",
     "@octokit/core": "^4.2.4",
-    "@rollup/plugin-node-resolve": "^15.1.0",
-    "@rollup/plugin-typescript": "^11.1.2",
-    "@types/chai": "^4.3.5",
-    "@types/mocha": "^10.0.1",
-    "@types/node": "^18.17.3",
-    "@types/sinon": "^10.0.16",
-    "@types/sinon-chai": "^3.2.9",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^18.19.2",
+    "@types/sinon": "^10.0.20",
+    "@types/sinon-chai": "^3.2.12",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "benchmark": "^2.1.4",
-    "chai": "^4.3.7",
+    "chai": "^4.3.10",
     "chalk": "^5.3.0",
-    "eslint": "^8.46.0",
+    "dbx-js-tools": "github:mongodb-js/dbx-js-tools",
+    "eslint": "^8.55.0",
     "eslint-config-prettier": "^8.10.0",
     "eslint-plugin-no-bigint-usage": "file:etc/eslint/no-bigint-usage",
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-tsdoc": "^0.2.17",
-    "magic-string": "^0.30.2",
+    "magic-string": "^0.30.5",
     "mocha": "10.2.0",
     "node-fetch": "^3.3.2",
     "nyc": "^15.1.0",
     "prettier": "^2.8.8",
-    "rollup": "^3.27.2",
+    "rollup": "^3.29.4",
     "sinon": "^15.2.0",
     "sinon-chai": "^3.7.0",
     "source-map-support": "^0.5.21",
     "standard-version": "^9.5.0",
-    "tar": "^6.1.15",
+    "tar": "^6.2.0",
     "ts-node": "^10.9.1",
     "tsd": "^0.28.1",
     "typescript": "^5.0.4",
     "typescript-cached-transpile": "0.0.6",
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.1"
   },
   "tsd": {
     "directory": "test/types",
@@ -103,7 +104,9 @@
     "check:tsd": "npm run build:dts && tsd",
     "check:web": "WEB=true mocha test/node",
     "check:web-no-bigint": "WEB=true NO_BIGINT=true mocha test/node",
-    "check:bench": "cd test/bench && npx tsc && node ./lib/index.js && mv benchmarks.json ../../.",
+    "check:granular-bench": "npm run build:bench && node ./test/bench/etc/run_granular_benchmarks.js",
+    "check:spec-bench": "npm run build:bench && node ./test/bench/lib/spec/bsonBench.js",
+    "build:bench": "cd test/bench && npx tsc",
     "build:ts": "node ./node_modules/typescript/bin/tsc",
     "build:dts": "npm run build:ts && api-extractor run --typescript-compiler-folder node_modules/typescript --local && node etc/clean_definition_files.cjs",
     "build:bundle": "rollup -c rollup.config.mjs",

package/src/binary.ts

@@ -191,8 +191,8 @@ export class Binary extends BSONValue {
     if (encoding === 'hex') return ByteUtils.toHex(this.buffer);
     if (encoding === 'base64') return ByteUtils.toBase64(this.buffer);
     if (encoding === 'utf8' || encoding === 'utf-8')
-      return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength);
-    return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength);
+      return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
+    return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
   }
 
   /** @internal */

package/src/error.ts

@@ -4,7 +4,7 @@ import { BSON_MAJOR_VERSION } from './constants';
  * @public
  * @category Error
  *
- * `BSONError` objects are thrown when BSON ecounters an error.
+ * `BSONError` objects are thrown when BSON encounters an error.
  *
  * This is the parent class for all the other errors thrown by this library.
  */
@@ -23,8 +23,8 @@ export class BSONError extends Error {
     return 'BSONError';
   }
 
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
   }
 
   /**

package/src/objectid.ts

@@ -44,9 +44,48 @@ export class ObjectId extends BSONValue {
   private __id?: string;
 
   /**
-   * Create an ObjectId type
+   * Create ObjectId from a number.
    *
-   * @param inputId - Can be a 24 character hex string, 12 byte binary Buffer, or a number.
+   * @param inputId - A number.
+   * @deprecated Instead, use `static createFromTime()` to set a numeric value for the new ObjectId.
+   */
+  constructor(inputId: number);
+  /**
+   * Create ObjectId from a 24 character hex string.
+   *
+   * @param inputId - A 24 character hex string.
+   */
+  constructor(inputId: string);
+  /**
+   * Create ObjectId from the BSON ObjectId type.
+   *
+   * @param inputId - The BSON ObjectId type.
+   */
+  constructor(inputId: ObjectId);
+  /**
+   * Create ObjectId from the object type that has the toHexString method.
+   *
+   * @param inputId - The ObjectIdLike type.
+   */
+  constructor(inputId: ObjectIdLike);
+  /**
+   * Create ObjectId from a 12 byte binary Buffer.
+   *
+   * @param inputId - A 12 byte binary Buffer.
+   */
+  constructor(inputId: Uint8Array);
+  /** To generate a new ObjectId, use ObjectId() with no argument. */
+  constructor();
+  /**
+   * Implementation overload.
+   *
+   * @param inputId - All input types that are used in the constructor implementation.
+   */
+  constructor(inputId?: string | number | ObjectId | ObjectIdLike | Uint8Array);
+  /**
+   * Create a new ObjectId.
+   *
+   * @param inputId - An input value to create a new ObjectId from.
    */
   constructor(inputId?: string | number | ObjectId | ObjectIdLike | Uint8Array) {
     super();
@@ -65,7 +104,7 @@ export class ObjectId extends BSONValue {
       workingId = inputId;
     }
 
-    // the following cases use workingId to construct an ObjectId
+    // The following cases use workingId to construct an ObjectId
     if (workingId == null || typeof workingId === 'number') {
       // The most common use case (blank id, new objectId instance)
       // Generate a new id

package/src/parser/deserializer.ts

@@ -236,7 +236,7 @@ function deserializeObject(
     if (i >= buffer.byteLength) throw new BSONError('Bad BSON Document: illegal CString');
 
     // Represents the key
-    const name = isArray ? arrayIndex++ : ByteUtils.toUTF8(buffer, index, i);
+    const name = isArray ? arrayIndex++ : ByteUtils.toUTF8(buffer, index, i, false);
 
     // shouldValidateKey is true if the key should be validated, false otherwise
     let shouldValidateKey = true;
@@ -266,7 +266,7 @@ function deserializeObject(
       ) {
         throw new BSONError('bad string length in bson');
       }
-      value = getValidatedString(buffer, index, index + stringSize - 1, shouldValidateKey);
+      value = ByteUtils.toUTF8(buffer, index, index + stringSize - 1, shouldValidateKey);
       index = index + stringSize;
     } else if (elementType === constants.BSON_DATA_OID) {
       const oid = ByteUtils.allocate(12);
@@ -476,7 +476,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const source = ByteUtils.toUTF8(buffer, index, i);
+      const source = ByteUtils.toUTF8(buffer, index, i, false);
       // Create the regexp
       index = i + 1;
 
@@ -489,7 +489,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const regExpOptions = ByteUtils.toUTF8(buffer, index, i);
+      const regExpOptions = ByteUtils.toUTF8(buffer, index, i, false);
       index = i + 1;
 
       // For each option add the corresponding one for javascript
@@ -521,7 +521,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const source = ByteUtils.toUTF8(buffer, index, i);
+      const source = ByteUtils.toUTF8(buffer, index, i, false);
       index = i + 1;
 
       // Get the start search index
@@ -533,7 +533,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const regExpOptions = ByteUtils.toUTF8(buffer, index, i);
+      const regExpOptions = ByteUtils.toUTF8(buffer, index, i, false);
       index = i + 1;
 
       // Set the object
@@ -551,7 +551,7 @@ function deserializeObject(
       ) {
         throw new BSONError('bad string length in bson');
       }
-      const symbol = getValidatedString(buffer, index, index + stringSize - 1, shouldValidateKey);
+      const symbol = ByteUtils.toUTF8(buffer, index, index + stringSize - 1, shouldValidateKey);
       value = promoteValues ? symbol : new BSONSymbol(symbol);
       index = index + stringSize;
     } else if (elementType === constants.BSON_DATA_TIMESTAMP) {
@@ -587,7 +587,7 @@ function deserializeObject(
       ) {
         throw new BSONError('bad string length in bson');
       }
-      const functionString = getValidatedString(
+      const functionString = ByteUtils.toUTF8(
         buffer,
         index,
         index + stringSize - 1,
@@ -626,7 +626,7 @@ function deserializeObject(
       }
 
       // Javascript function
-      const functionString = getValidatedString(
+      const functionString = ByteUtils.toUTF8(
         buffer,
         index,
         index + stringSize - 1,
@@ -678,7 +678,7 @@ function deserializeObject(
           throw new BSONError('Invalid UTF-8 string in BSON document');
         }
       }
-      const namespace = ByteUtils.toUTF8(buffer, index, index + stringSize - 1);
+      const namespace = ByteUtils.toUTF8(buffer, index, index + stringSize - 1, false);
       // Update parse index position
       index = index + stringSize;
 
@@ -728,24 +728,3 @@ function deserializeObject(
 
   return object;
 }
-
-function getValidatedString(
-  buffer: Uint8Array,
-  start: number,
-  end: number,
-  shouldValidateUtf8: boolean
-) {
-  const value = ByteUtils.toUTF8(buffer, start, end);
-  // if utf8 validation is on, do the check
-  if (shouldValidateUtf8) {
-    for (let i = 0; i < value.length; i++) {
-      if (value.charCodeAt(i) === 0xfffd) {
-        if (!validateUtf8(buffer, start, end)) {
-          throw new BSONError('Invalid UTF-8 string in BSON document');
-        }
-        break;
-      }
-    }
-  }
-  return value;
-}

package/src/utils/byte_utils.ts

@@ -25,8 +25,8 @@ export type ByteUtils = {
   toHex: (buffer: Uint8Array) => string;
   /** Create a Uint8Array containing utf8 code units from a string */
   fromUTF8: (text: string) => Uint8Array;
-  /** Create a string from utf8 code units */
-  toUTF8: (buffer: Uint8Array, start: number, end: number) => string;
+  /** Create a string from utf8 code units, fatal=true will throw an error if UTF-8 bytes are invalid, fatal=false will insert replacement characters */
+  toUTF8: (buffer: Uint8Array, start: number, end: number, fatal: boolean) => string;
   /** Get the utf8 code unit count from a string if it were to be transformed to utf8 */
   utf8ByteLength: (input: string) => number;
   /** Encode UTF8 bytes generated from `source` string into `destination` at byteOffset. Returns the number of bytes encoded. */

package/src/utils/latin.ts

@@ -0,0 +1,61 @@
+/**
+ * This function is an optimization for small basic latin strings.
+ * @internal
+ * @remarks
+ * ### Important characteristics:
+ * - If the uint8array or distance between start and end is 0 this function returns an empty string
+ * - If the byteLength of the string is 1, 2, or 3 we invoke String.fromCharCode and manually offset into the buffer
+ * - If the byteLength of the string is less than or equal to 20 an array of bytes is built and `String.fromCharCode.apply` is called with the result
+ * - If any byte exceeds 128 this function returns null
+ *
+ * @param uint8array - A sequence of bytes that may contain basic latin characters
+ * @param start - The start index from which to search the uint8array
+ * @param end - The index to stop searching the uint8array
+ * @returns string if all bytes are within the basic latin range, otherwise null
+ */
+export function tryLatin(uint8array: Uint8Array, start: number, end: number): string | null {
+  if (uint8array.length === 0) {
+    return '';
+  }
+
+  const stringByteLength = end - start;
+  if (stringByteLength === 0) {
+    return '';
+  }
+
+  if (stringByteLength > 20) {
+    return null;
+  }
+
+  if (stringByteLength === 1 && uint8array[start] < 128) {
+    return String.fromCharCode(uint8array[start]);
+  }
+
+  if (stringByteLength === 2 && uint8array[start] < 128 && uint8array[start + 1] < 128) {
+    return String.fromCharCode(uint8array[start]) + String.fromCharCode(uint8array[start + 1]);
+  }
+
+  if (
+    stringByteLength === 3 &&
+    uint8array[start] < 128 &&
+    uint8array[start + 1] < 128 &&
+    uint8array[start + 2] < 128
+  ) {
+    return (
+      String.fromCharCode(uint8array[start]) +
+      String.fromCharCode(uint8array[start + 1]) +
+      String.fromCharCode(uint8array[start + 2])
+    );
+  }
+
+  const latinBytes = [];
+  for (let i = start; i < end; i++) {
+    const byte = uint8array[i];
+    if (byte > 127) {
+      return null;
+    }
+    latinBytes.push(byte);
+  }
+
+  return String.fromCharCode(...latinBytes);
+}

package/src/utils/node_byte_utils.ts

@@ -1,4 +1,6 @@
 import { BSONError } from '../error';
+import { validateUtf8 } from '../validate_utf8';
+import { tryLatin } from './latin';
 
 type NodeJsEncoding = 'base64' | 'hex' | 'utf8' | 'binary';
 type NodeJsBuffer = ArrayBufferView &
@@ -125,8 +127,25 @@ export const nodeJsByteUtils = {
     return Buffer.from(text, 'utf8');
   },
 
-  toUTF8(buffer: Uint8Array, start: number, end: number): string {
-    return nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
+  toUTF8(buffer: Uint8Array, start: number, end: number, fatal: boolean): string {
+    const basicLatin = end - start <= 20 ? tryLatin(buffer, start, end) : null;
+    if (basicLatin != null) {
+      return basicLatin;
+    }
+
+    const string = nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
+    if (fatal) {
+      // TODO(NODE-4930): Insufficiently strict BSON UTF8 validation
+      for (let i = 0; i < string.length; i++) {
+        if (string.charCodeAt(i) === 0xfffd) {
+          if (!validateUtf8(buffer, start, end)) {
+            throw new BSONError('Invalid UTF-8 string in BSON document');
+          }
+          break;
+        }
+      }
+    }
+    return string;
   },
 
   utf8ByteLength(input: string): number {

package/src/utils/web_byte_utils.ts

@@ -1,4 +1,5 @@
 import { BSONError } from '../error';
+import { tryLatin } from './latin';
 
 type TextDecoder = {
   readonly encoding: string;
@@ -172,8 +173,20 @@ export const webByteUtils = {
     return new TextEncoder().encode(text);
   },
 
-  toUTF8(uint8array: Uint8Array, start: number, end: number): string {
-    return new TextDecoder('utf8', { fatal: false }).decode(uint8array.slice(start, end));
+  toUTF8(uint8array: Uint8Array, start: number, end: number, fatal: boolean): string {
+    const basicLatin = end - start <= 20 ? tryLatin(uint8array, start, end) : null;
+    if (basicLatin != null) {
+      return basicLatin;
+    }
+
+    if (fatal) {
+      try {
+        return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
+      } catch (cause) {
+        throw new BSONError('Invalid UTF-8 string in BSON document', { cause });
+      }
+    }
+    return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
   },
 
   utf8ByteLength(input: string): number {