bson 5.4.0 → 6.0.0-alpha.0

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "5.4.0",
+  "version": "6.0.0-alpha.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -27,41 +27,41 @@
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
-    "@microsoft/api-extractor": "^7.35.1",
+    "@microsoft/api-extractor": "^7.36.4",
     "@octokit/core": "^4.2.4",
-    "@rollup/plugin-node-resolve": "^15.0.2",
-    "@rollup/plugin-typescript": "^11.1.0",
+    "@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.16.3",
-    "@types/sinon": "^10.0.14",
+    "@types/node": "^18.17.3",
+    "@types/sinon": "^10.0.16",
     "@types/sinon-chai": "^3.2.9",
-    "@typescript-eslint/eslint-plugin": "^5.59.2",
-    "@typescript-eslint/parser": "^5.59.2",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
     "benchmark": "^2.1.4",
     "chai": "^4.3.7",
-    "chalk": "^5.2.0",
-    "eslint": "^8.39.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-no-bigint-usage": "file:./etc/eslint/no-bigint-usage",
+    "chalk": "^5.3.0",
+    "eslint": "^8.46.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.0",
+    "magic-string": "^0.30.2",
     "mocha": "10.2.0",
-    "node-fetch": "^3.3.1",
+    "node-fetch": "^3.3.2",
     "nyc": "^15.1.0",
     "prettier": "^2.8.8",
-    "rollup": "^3.21.4",
-    "sinon": "^15.0.4",
+    "rollup": "^3.27.2",
+    "sinon": "^15.2.0",
     "sinon-chai": "^3.7.0",
     "source-map-support": "^0.5.21",
     "standard-version": "^9.5.0",
+    "tar": "^6.1.15",
     "ts-node": "^10.9.1",
     "tsd": "^0.28.1",
     "typescript": "^5.0.4",
     "typescript-cached-transpile": "0.0.6",
-    "uuid": "^9.0.0",
-    "v8-profiler-next": "^1.9.0"
+    "uuid": "^9.0.0"
   },
   "tsd": {
     "directory": "test/types",
@@ -94,7 +94,7 @@
     "require": "./lib/bson.cjs"
   },
   "engines": {
-    "node": ">=14.20.1"
+    "node": ">=16.20.1"
   },
   "scripts": {
     "pretest": "npm run build",
@@ -103,6 +103,7 @@
     "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 ../../.",
     "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

@@ -1,4 +1,4 @@
-import { isUint8Array } from './parser/utils';
+import { isAnyArrayBuffer, isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
 import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW } from './constants';
@@ -65,27 +65,19 @@ export class Binary extends BSONValue {
 
   /**
    * Create a new Binary instance.
-   *
-   * This constructor can accept a string as its first argument. In this case,
-   * this string will be encoded using ISO-8859-1, **not** using UTF-8.
-   * This is almost certainly not what you want. Use `new Binary(Buffer.from(string))`
-   * instead to convert the string to a Buffer using UTF-8 first.
-   *
    * @param buffer - a buffer object containing the binary data.
    * @param subType - the option binary type.
    */
-  constructor(buffer?: string | BinarySequence, subType?: number) {
+  constructor(buffer?: BinarySequence, subType?: number) {
     super();
     if (
       !(buffer == null) &&
-      !(typeof buffer === 'string') &&
+      typeof buffer === 'string' &&
       !ArrayBuffer.isView(buffer) &&
-      !(buffer instanceof ArrayBuffer) &&
+      !isAnyArrayBuffer(buffer) &&
       !Array.isArray(buffer)
     ) {
-      throw new BSONError(
-        'Binary can only be constructed from string, Buffer, TypedArray, or Array<number>'
-      );
+      throw new BSONError('Binary can only be constructed from Uint8Array or number[]');
     }
 
     this.sub_type = subType ?? Binary.BSON_BINARY_SUBTYPE_DEFAULT;
@@ -95,17 +87,9 @@ export class Binary extends BSONValue {
       this.buffer = ByteUtils.allocate(Binary.BUFFER_SIZE);
       this.position = 0;
     } else {
-      if (typeof buffer === 'string') {
-        // string
-        this.buffer = ByteUtils.fromISO88591(buffer);
-      } else if (Array.isArray(buffer)) {
-        // number[]
-        this.buffer = ByteUtils.fromNumberArray(buffer);
-      } else {
-        // Buffer | TypedArray | ArrayBuffer
-        this.buffer = ByteUtils.toLocalBufferType(buffer);
-      }
-
+      this.buffer = Array.isArray(buffer)
+        ? ByteUtils.fromNumberArray(buffer)
+        : ByteUtils.toLocalBufferType(buffer);
       this.position = this.buffer.byteLength;
     }
   }
@@ -147,12 +131,12 @@ export class Binary extends BSONValue {
   }
 
   /**
-   * Writes a buffer or string to the binary.
+   * Writes a buffer to the binary.
    *
    * @param sequence - a string or buffer to be written to the Binary BSON object.
    * @param offset - specify the binary of where to write the content.
    */
-  write(sequence: string | BinarySequence, offset: number): void {
+  write(sequence: BinarySequence, offset: number): void {
     offset = typeof offset === 'number' ? offset : this.position;
 
     // If the buffer is to small let's extend the buffer
@@ -169,10 +153,7 @@ export class Binary extends BSONValue {
       this.position =
         offset + sequence.byteLength > this.position ? offset + sequence.length : this.position;
     } else if (typeof sequence === 'string') {
-      const bytes = ByteUtils.fromISO88591(sequence);
-      this.buffer.set(bytes, offset);
-      this.position =
-        offset + sequence.length > this.position ? offset + sequence.length : this.position;
+      throw new BSONError('input cannot be string');
     }
   }
 
@@ -189,26 +170,12 @@ export class Binary extends BSONValue {
     return this.buffer.slice(position, position + length);
   }
 
-  /**
-   * Returns the value of this binary as a string.
-   * @param asRaw - Will skip converting to a string
-   * @remarks
-   * This is handy when calling this function conditionally for some key value pairs and not others
-   */
-  value(asRaw?: boolean): string | BinarySequence {
-    asRaw = !!asRaw;
-
+  /** returns a view of the binary value as a Uint8Array */
+  value(): Uint8Array {
     // Optimize to serialize for the situation where the data == size of buffer
-    if (asRaw && this.buffer.length === this.position) {
-      return this.buffer;
-    }
-
-    // If it's a node.js buffer object
-    if (asRaw) {
-      return this.buffer.slice(0, this.position);
-    }
-    // TODO(NODE-4361): remove binary string support, value(true) should be the default / only option here.
-    return ByteUtils.toISO88591(this.buffer.subarray(0, this.position));
+    return this.buffer.length === this.position
+      ? this.buffer
+      : this.buffer.subarray(0, this.position);
   }
 
   /** the length of the binary sequence */
@@ -321,8 +288,6 @@ const UUID_WITH_DASHES = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A
  * @public
  */
 export class UUID extends Binary {
-  /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
-  static cacheHexString = false;
   /**
    * Create a UUID type
    *

package/src/constants.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export const BSON_MAJOR_VERSION = 5 as const;
+export const BSON_MAJOR_VERSION = 6 as const;
 
 /** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;

package/src/objectid.ts

@@ -1,6 +1,5 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
-import { isUint8Array } from './parser/utils';
 import { BSONDataView, ByteUtils } from './utils/byte_utils';
 
 // Regular expression that checks for hex value
@@ -74,19 +73,11 @@ export class ObjectId extends BSONValue {
       // If intstanceof matches we can escape calling ensure buffer in Node.js environments
       this[kId] = ByteUtils.toLocalBufferType(workingId);
     } else if (typeof workingId === 'string') {
-      if (workingId.length === 12) {
-        // TODO(NODE-4361): Remove string of length 12 support
-        const bytes = ByteUtils.fromUTF8(workingId);
-        if (bytes.byteLength === 12) {
-          this[kId] = bytes;
-        } else {
-          throw new BSONError('Argument passed in must be a string of 12 bytes');
-        }
-      } else if (workingId.length === 24 && checkForHexRegExp.test(workingId)) {
+      if (workingId.length === 24 && checkForHexRegExp.test(workingId)) {
         this[kId] = ByteUtils.fromHex(workingId);
       } else {
         throw new BSONError(
-          'Argument passed in must be a string of 12 bytes or a string of 24 hex characters or an integer'
+          'input must be a 24 character hex string, 12 byte Uint8Array, or an integer'
         );
       }
     } else {
@@ -113,7 +104,7 @@ export class ObjectId extends BSONValue {
     }
   }
 
-  /** Returns the ObjectId id as a 24 character hex string representation */
+  /** Returns the ObjectId id as a 24 lowercase character hex string representation */
   toHexString(): string {
     if (ObjectId.cacheHexString && this.__id) {
       return this.__id;
@@ -188,44 +179,37 @@ export class ObjectId extends BSONValue {
     return this.toHexString();
   }
 
+  /** @internal */
+  private static is(variable: unknown): variable is ObjectId {
+    return (
+      variable != null &&
+      typeof variable === 'object' &&
+      '_bsontype' in variable &&
+      variable._bsontype === 'ObjectId'
+    );
+  }
+
   /**
    * Compares the equality of this ObjectId with `otherID`.
    *
    * @param otherId - ObjectId instance to compare against.
    */
-  equals(otherId: string | ObjectId | ObjectIdLike): boolean {
+  equals(otherId: string | ObjectId | ObjectIdLike | undefined | null): boolean {
     if (otherId === undefined || otherId === null) {
       return false;
     }
 
-    if (otherId instanceof ObjectId) {
+    if (ObjectId.is(otherId)) {
       return this[kId][11] === otherId[kId][11] && ByteUtils.equals(this[kId], otherId[kId]);
     }
 
-    if (
-      typeof otherId === 'string' &&
-      ObjectId.isValid(otherId) &&
-      otherId.length === 12 &&
-      isUint8Array(this.id)
-    ) {
-      return ByteUtils.equals(this.id, ByteUtils.fromISO88591(otherId));
-    }
-
-    if (typeof otherId === 'string' && ObjectId.isValid(otherId) && otherId.length === 24) {
+    if (typeof otherId === 'string') {
       return otherId.toLowerCase() === this.toHexString();
     }
 
-    if (typeof otherId === 'string' && ObjectId.isValid(otherId) && otherId.length === 12) {
-      return ByteUtils.equals(ByteUtils.fromUTF8(otherId), this.id);
-    }
-
-    if (
-      typeof otherId === 'object' &&
-      'toHexString' in otherId &&
-      typeof otherId.toHexString === 'function'
-    ) {
+    if (typeof otherId === 'object' && typeof otherId.toHexString === 'function') {
       const otherIdString = otherId.toHexString();
-      const thisIdString = this.toHexString().toLowerCase();
+      const thisIdString = this.toHexString();
       return typeof otherIdString === 'string' && otherIdString.toLowerCase() === thisIdString;
     }
 
@@ -281,9 +265,8 @@ export class ObjectId extends BSONValue {
   }
 
   /**
-   * Checks if a value is a valid bson ObjectId
-   *
-   * @param id - ObjectId instance to validate.
+   * Checks if a value can be used to create a valid bson ObjectId
+   * @param id - any JS value
    */
   static isValid(id: string | number | ObjectId | ObjectIdLike | Uint8Array): boolean {
     if (id == null) return false;

package/src/utils/byte_utils.ts

@@ -21,7 +21,7 @@ export type ByteUtils = {
   toISO88591: (buffer: Uint8Array) => string;
   /** Create a Uint8Array from a hex string */
   fromHex: (hex: string) => Uint8Array;
-  /** Create a hex string from bytes */
+  /** Create a lowercase hex string from bytes */
   toHex: (buffer: Uint8Array) => string;
   /** Create a Uint8Array containing utf8 code units from a string */
   fromUTF8: (text: string) => Uint8Array;