bson 5.1.0 → 5.3.0

package/package.json

@@ -13,7 +13,7 @@
     "etc/prepare.js"
   ],
   "types": "bson.d.ts",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -26,37 +26,37 @@
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
-    "@microsoft/api-extractor": "^7.33.7",
-    "@rollup/plugin-node-resolve": "^15.0.1",
-    "@rollup/plugin-typescript": "^10.0.1",
-    "@types/chai": "^4.3.4",
+    "@microsoft/api-extractor": "^7.34.7",
+    "@rollup/plugin-node-resolve": "^15.0.2",
+    "@rollup/plugin-typescript": "^11.1.0",
+    "@types/chai": "^4.3.5",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^18.11.12",
-    "@types/sinon": "^10.0.13",
+    "@types/node": "^18.16.3",
+    "@types/sinon": "^10.0.14",
     "@types/sinon-chai": "^3.2.9",
-    "@typescript-eslint/eslint-plugin": "^5.46.0",
-    "@typescript-eslint/parser": "^5.46.0",
+    "@typescript-eslint/eslint-plugin": "^5.59.2",
+    "@typescript-eslint/parser": "^5.59.2",
     "benchmark": "^2.1.4",
     "chai": "^4.3.7",
-    "chalk": "^5.1.2",
-    "eslint": "^8.29.0",
-    "eslint-config-prettier": "^8.5.0",
+    "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",
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-tsdoc": "^0.2.17",
-    "magic-string": "^0.27.0",
-    "mocha": "10.1.0",
-    "node-fetch": "^3.2.10",
+    "magic-string": "^0.30.0",
+    "mocha": "10.2.0",
+    "node-fetch": "^3.3.1",
     "nyc": "^15.1.0",
-    "prettier": "^2.8.1",
-    "rimraf": "^3.0.2",
-    "rollup": "^3.7.1",
-    "sinon": "^15.0.0",
+    "prettier": "^2.8.8",
+    "rimraf": "^5.0.0",
+    "rollup": "^3.21.4",
+    "sinon": "^15.0.4",
     "sinon-chai": "^3.7.0",
     "source-map-support": "^0.5.21",
     "standard-version": "^9.5.0",
     "ts-node": "^10.9.1",
-    "tsd": "^0.25.0",
+    "tsd": "^0.28.1",
     "typescript": "^4.9.4",
     "typescript-cached-transpile": "0.0.6",
     "uuid": "^9.0.0",

package/src/binary.ts

@@ -1,4 +1,3 @@
-import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
 import { isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
 import { BSONError } from './error';
@@ -258,6 +257,16 @@ export class Binary extends BSONValue {
     );
   }
 
+  /** Creates an Binary instance from a hex digit string */
+  static createFromHexString(hex: string, subType?: number): Binary {
+    return new Binary(ByteUtils.fromHex(hex), subType);
+  }
+
+  /** Creates an Binary instance from a base64 string */
+  static createFromBase64(base64: string, subType?: number): Binary {
+    return new Binary(ByteUtils.fromBase64(base64), subType);
+  }
+
   /** @internal */
   static fromExtendedJSON(
     doc: BinaryExtendedLegacy | BinaryExtended | UUIDExtended,
@@ -278,7 +287,7 @@ export class Binary extends BSONValue {
       }
     } else if ('$uuid' in doc) {
       type = 4;
-      data = uuidHexStringToBuffer(doc.$uuid);
+      data = UUID.bytesFromString(doc.$uuid);
     }
     if (!data) {
       throw new BSONError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
@@ -292,7 +301,8 @@ export class Binary extends BSONValue {
   }
 
   inspect(): string {
-    return `new Binary(Buffer.from("${ByteUtils.toHex(this.buffer)}", "hex"), ${this.sub_type})`;
+    const base64 = ByteUtils.toBase64(this.buffer.subarray(0, this.position));
+    return `Binary.createFromBase64("${base64}", ${this.sub_type})`;
   }
 }
 
@@ -300,42 +310,41 @@ export class Binary extends BSONValue {
 export type UUIDExtended = {
   $uuid: string;
 };
+
 const UUID_BYTE_LENGTH = 16;
+const UUID_WITHOUT_DASHES = /^[0-9A-F]{32}$/i;
+const UUID_WITH_DASHES = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
 
 /**
  * A class representation of the BSON UUID type.
  * @public
  */
 export class UUID extends Binary {
-  static cacheHexString: boolean;
-
-  /** UUID hexString cache @internal */
-  private __id?: string;
-
+  /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
+  static cacheHexString = false;
   /**
-   * Create an UUID type
+   * Create a UUID type
+   *
+   * When the argument to the constructor is omitted a random v4 UUID will be generated.
    *
    * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
    */
   constructor(input?: string | Uint8Array | UUID) {
     let bytes: Uint8Array;
-    let hexStr;
     if (input == null) {
       bytes = UUID.generate();
     } else if (input instanceof UUID) {
       bytes = ByteUtils.toLocalBufferType(new Uint8Array(input.buffer));
-      hexStr = input.__id;
     } else if (ArrayBuffer.isView(input) && input.byteLength === UUID_BYTE_LENGTH) {
       bytes = ByteUtils.toLocalBufferType(input);
     } else if (typeof input === 'string') {
-      bytes = uuidHexStringToBuffer(input);
+      bytes = UUID.bytesFromString(input);
     } else {
       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).'
       );
     }
     super(bytes, BSON_BINARY_SUBTYPE_UUID_NEW);
-    this.__id = hexStr;
   }
 
   /**
@@ -348,28 +357,23 @@ export class UUID extends Binary {
 
   set id(value: Uint8Array) {
     this.buffer = value;
-
-    if (UUID.cacheHexString) {
-      this.__id = bufferToUuidHexString(value);
-    }
   }
 
   /**
    * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
    * @param includeDashes - should the string exclude dash-separators.
-   * */
+   */
   toHexString(includeDashes = true): string {
-    if (UUID.cacheHexString && this.__id) {
-      return this.__id;
-    }
-
-    const uuidHexString = bufferToUuidHexString(this.id, includeDashes);
-
-    if (UUID.cacheHexString) {
-      this.__id = uuidHexString;
+    if (includeDashes) {
+      return [
+        ByteUtils.toHex(this.buffer.subarray(0, 4)),
+        ByteUtils.toHex(this.buffer.subarray(4, 6)),
+        ByteUtils.toHex(this.buffer.subarray(6, 8)),
+        ByteUtils.toHex(this.buffer.subarray(8, 10)),
+        ByteUtils.toHex(this.buffer.subarray(10, 16))
+      ].join('-');
     }
-
-    return uuidHexString;
+    return ByteUtils.toHex(this.buffer);
   }
 
   /**
@@ -435,40 +439,60 @@ export class UUID extends Binary {
    * Checks if a value is a valid bson UUID
    * @param input - UUID, string or Buffer to validate.
    */
-  static isValid(input: string | Uint8Array | UUID): boolean {
+  static isValid(input: string | Uint8Array | UUID | Binary): boolean {
     if (!input) {
       return false;
     }
 
-    if (input instanceof UUID) {
-      return true;
-    }
-
     if (typeof input === 'string') {
-      return uuidValidateString(input);
+      return UUID.isValidUUIDString(input);
     }
 
     if (isUint8Array(input)) {
-      // check for length & uuid version (https://tools.ietf.org/html/rfc4122#section-4.1.3)
-      if (input.byteLength !== UUID_BYTE_LENGTH) {
-        return false;
-      }
-
-      return (input[6] & 0xf0) === 0x40 && (input[8] & 0x80) === 0x80;
+      return input.byteLength === UUID_BYTE_LENGTH;
     }
 
-    return false;
+    return (
+      input._bsontype === 'Binary' &&
+      input.sub_type === this.SUBTYPE_UUID &&
+      input.buffer.byteLength === 16
+    );
   }
 
   /**
    * Creates an UUID from a hex string representation of an UUID.
    * @param hexString - 32 or 36 character hex string (dashes excluded/included).
    */
-  static createFromHexString(hexString: string): UUID {
-    const buffer = uuidHexStringToBuffer(hexString);
+  static override createFromHexString(hexString: string): UUID {
+    const buffer = UUID.bytesFromString(hexString);
     return new UUID(buffer);
   }
 
+  /** Creates an UUID from a base64 string representation of an UUID. */
+  static override createFromBase64(base64: string): UUID {
+    return new UUID(ByteUtils.fromBase64(base64));
+  }
+
+  /** @internal */
+  static bytesFromString(representation: string) {
+    if (!UUID.isValidUUIDString(representation)) {
+      throw new BSONError(
+        'UUID string representation must be 32 hex digits or canonical hyphenated representation'
+      );
+    }
+    return ByteUtils.fromHex(representation.replace(/-/g, ''));
+  }
+
+  /**
+   * @internal
+   *
+   * Validates a string to be a hex digit sequence with or without dashes.
+   * The canonical hyphenated representation of a uuid is hex in 8-4-4-4-12 groups.
+   */
+  static isValidUUIDString(representation: string) {
+    return UUID_WITHOUT_DASHES.test(representation) || UUID_WITH_DASHES.test(representation);
+  }
+
   /**
    * Converts to a string representation of this Id.
    *

package/src/bson.ts

@@ -70,7 +70,7 @@ let buffer = ByteUtils.allocate(MAXSIZE);
 /**
  * Sets the size of the internal serialization buffer.
  *
- * @param size - The desired size for the internal serialization buffer
+ * @param size - The desired size for the internal serialization buffer in bytes
  * @public
  */
 export function setInternalBufferSize(size: number): void {

package/src/constants.ts

@@ -138,4 +138,4 @@ export const BSONType = Object.freeze({
 } as const);
 
 /** @public */
-export type BSONType = typeof BSONType[keyof typeof BSONType];
+export type BSONType = (typeof BSONType)[keyof typeof BSONType];

package/src/extended_json.ts

@@ -24,11 +24,19 @@ import { Timestamp } from './timestamp';
 
 /** @public */
 export type EJSONOptions = {
-  /** Output using the Extended JSON v1 spec */
+  /**
+   * Output using the Extended JSON v1 spec
+   * @defaultValue `false`
+   */
   legacy?: boolean;
-  /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
+  /**
+   * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
+   * @defaultValue `false` */
   relaxed?: boolean;
-  /** Enable native bigint support */
+  /**
+   * Enable native bigint support
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
 };
 

package/src/objectid.ts

@@ -264,16 +264,22 @@ export class ObjectId extends BSONValue {
    * @param hexString - create a ObjectId from a passed in 24 character hexstring.
    */
   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 BSONError(
-        'Argument passed in must be a single String of 12 bytes or a string of 24 hex characters'
-      );
+    if (hexString?.length !== 24) {
+      throw new BSONError('hex string must be 24 characters');
     }
 
     return new ObjectId(ByteUtils.fromHex(hexString));
   }
 
+  /** Creates an ObjectId instance from a base64 string */
+  static createFromBase64(base64: string): ObjectId {
+    if (base64?.length !== 16) {
+      throw new BSONError('base64 string must be 16 characters');
+    }
+
+    return new ObjectId(ByteUtils.fromBase64(base64));
+  }
+
   /**
    * Checks if a value is a valid bson ObjectId
    *

package/src/parser/deserializer.ts

@@ -1,4 +1,4 @@
-import { Binary } from '../binary';
+import { Binary, UUID } from '../binary';
 import type { Document } from '../bson';
 import { Code } from '../code';
 import * as constants from '../constants';
@@ -19,21 +19,45 @@ import { validateUtf8 } from '../validate_utf8';
 
 /** @public */
 export interface DeserializeOptions {
-  /** when deserializing a Long will return as a BigInt. */
+  /**
+   * when deserializing a Long return as a BigInt.
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
-  /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
+  /**
+   * when deserializing a Long will fit it into a Number if it's smaller than 53 bits.
+   * @defaultValue `true`
+   */
   promoteLongs?: boolean;
-  /** when deserializing a Binary will return it as a node.js Buffer instance. */
+  /**
+   * when deserializing a Binary will return it as a node.js Buffer instance.
+   * @defaultValue `false`
+   */
   promoteBuffers?: boolean;
-  /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
+  /**
+   * when deserializing will promote BSON values to their Node.js closest equivalent types.
+   * @defaultValue `true`
+   */
   promoteValues?: boolean;
-  /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
+  /**
+   * allow to specify if there what fields we wish to return as unserialized raw buffer.
+   * @defaultValue `null`
+   */
   fieldsAsRaw?: Document;
-  /** return BSON regular expressions as BSONRegExp instances. */
+  /**
+   * return BSON regular expressions as BSONRegExp instances.
+   * @defaultValue `false`
+   */
   bsonRegExp?: boolean;
-  /** allows the buffer to be larger than the parsed BSON object. */
+  /**
+   * allows the buffer to be larger than the parsed BSON object.
+   * @defaultValue `false`
+   */
   allowObjectSmallerThanBufferSize?: boolean;
-  /** Offset into buffer to begin reading document from */
+  /**
+   * Offset into buffer to begin reading document from
+   * @defaultValue `0`
+   */
   index?: number;
 
   raw?: boolean;
@@ -404,7 +428,7 @@ function deserializeObject(
           value = ByteUtils.toLocalBufferType(buffer.slice(index, index + binarySize));
         } else {
           value = new Binary(buffer.slice(index, index + binarySize), subType);
-          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW) {
+          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
             value = value.toUUID();
           }
         }
@@ -432,10 +456,11 @@ function deserializeObject(
 
         if (promoteBuffers && promoteValues) {
           value = _buffer;
-        } else if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW) {
-          value = new Binary(buffer.slice(index, index + binarySize), subType).toUUID();
         } else {
           value = new Binary(buffer.slice(index, index + binarySize), subType);
+          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
+            value = value.toUUID();
+          }
         }
       }
 

package/src/parser/serializer.ts

@@ -16,15 +16,28 @@ import { isAnyArrayBuffer, isDate, isMap, isRegExp, isUint8Array } from './utils
 
 /** @public */
 export interface SerializeOptions {
-  /** the serializer will check if keys are valid. */
+  /**
+   * the serializer will check if keys are valid.
+   * @defaultValue `false`
+   */
   checkKeys?: boolean;
-  /** serialize the javascript functions **(default:false)**. */
+  /**
+   * serialize the javascript functions
+   * @defaultValue `false`
+   */
   serializeFunctions?: boolean;
-  /** serialize will not emit undefined fields **(default:true)** */
+  /**
+   * serialize will not emit undefined fields
+   * note that the driver sets this to `false`
+   * @defaultValue `true`
+   */
   ignoreUndefined?: boolean;
   /** @internal Resize internal buffer */
   minInternalBufferSize?: number;
-  /** the index in the buffer where we wish to start serializing into */
+  /**
+   * the index in the buffer where we wish to start serializing into
+   * @defaultValue `0`
+   */
   index?: number;
 }
 

package/src/timestamp.ts

@@ -27,7 +27,7 @@ export interface TimestampExtended {
 /**
  * @public
  * @category BSONType
- * */
+ */
 export class Timestamp extends LongWithoutOverridesClass {
   get _bsontype(): 'Timestamp' {
     return 'Timestamp';

package/src/uuid_utils.ts

@@ -1,33 +0,0 @@
-import { BSONError } from './error';
-import { ByteUtils } from './utils/byte_utils';
-
-// Validation regex for v4 uuid (validates with or without dashes)
-const VALIDATION_REGEX =
-  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[0-9a-f]{12}4[0-9a-f]{3}[89ab][0-9a-f]{15})$/i;
-
-export const uuidValidateString = (str: string): boolean =>
-  typeof str === 'string' && VALIDATION_REGEX.test(str);
-
-export const uuidHexStringToBuffer = (hexString: string): Uint8Array => {
-  if (!uuidValidateString(hexString)) {
-    throw new BSONError(
-      'UUID string representations must be a 32 or 36 character hex string (dashes excluded/included). Format: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" or "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".'
-    );
-  }
-
-  const sanitizedHexString = hexString.replace(/-/g, '');
-  return ByteUtils.fromHex(sanitizedHexString);
-};
-
-export function bufferToUuidHexString(buffer: Uint8Array, includeDashes = true): string {
-  if (includeDashes) {
-    return [
-      ByteUtils.toHex(buffer.subarray(0, 4)),
-      ByteUtils.toHex(buffer.subarray(4, 6)),
-      ByteUtils.toHex(buffer.subarray(6, 8)),
-      ByteUtils.toHex(buffer.subarray(8, 10)),
-      ByteUtils.toHex(buffer.subarray(10, 16))
-    ].join('-');
-  }
-  return ByteUtils.toHex(buffer);
-}