bson 4.2.2 → 4.4.1

package/src/parser/serializer.ts

@@ -18,8 +18,9 @@ import type { BSONRegExp } from '../regexp';
 import {
   isBigInt64Array,
   isBigUInt64Array,
-  isBuffer,
   isDate,
+  isMap,
+  isRegExp,
   isUint8Array,
   normalizedFunctionString
 } from './utils';
@@ -41,10 +42,6 @@ export interface SerializeOptions {
 const regexp = /\x00/; // eslint-disable-line no-control-regex
 const ignoreKeys = new Set(['$db', '$ref', '$id', '$clusterTime']);
 
-function isRegExp(d: unknown): d is RegExp {
-  return Object.prototype.toString.call(d) === '[object RegExp]';
-}
-
 /*
  * isArray indicates if we are writing to a BSON array (type 0x04)
  * which forces the "key" which really an array index as a string to be written as ascii
@@ -309,8 +306,10 @@ function serializeObjectId(
   // Write the objectId into the shared buffer
   if (typeof value.id === 'string') {
     buffer.write(value.id, index, undefined, 'binary');
-  } else if (value.id && value.id.copy) {
-    value.id.copy(buffer, index, 0, 12);
+  } else if (isUint8Array(value.id)) {
+    // Use the standard JS methods here because buffer.copy() is buggy with the
+    // browser polyfill
+    buffer.set(value.id.subarray(0, 12), index);
   } else {
     throw new TypeError('object [' + JSON.stringify(value) + '] is not a valid ObjectId');
   }
@@ -409,7 +408,9 @@ function serializeDecimal128(
   index = index + numberOfWrittenBytes;
   buffer[index++] = 0;
   // Write the data from the value
-  value.bytes.copy(buffer, index, 0, 16);
+  // Prefer the standard JS methods because their typechecking is not buggy,
+  // unlike the `buffer` polyfill's.
+  buffer.set(value.bytes.subarray(0, 16), index);
   return index + 16;
 }
 
@@ -786,7 +787,7 @@ export function serializeInto(
         index = serializeNull(buffer, key, value, index, true);
       } else if (value['_bsontype'] === 'ObjectId' || value['_bsontype'] === 'ObjectID') {
         index = serializeObjectId(buffer, key, value, index, true);
-      } else if (isBuffer(value) || isUint8Array(value)) {
+      } else if (isUint8Array(value)) {
         index = serializeBuffer(buffer, key, value, index, true);
       } else if (value instanceof RegExp || isRegExp(value)) {
         index = serializeRegExp(buffer, key, value, index, true);
@@ -843,7 +844,7 @@ export function serializeInto(
         throw new TypeError('Unrecognized or invalid _bsontype: ' + value['_bsontype']);
       }
     }
-  } else if (object instanceof Map) {
+  } else if (object instanceof Map || isMap(object)) {
     const iterator = object.entries();
     let done = false;
 
@@ -892,7 +893,7 @@ export function serializeInto(
         index = serializeNull(buffer, key, value, index);
       } else if (value['_bsontype'] === 'ObjectId' || value['_bsontype'] === 'ObjectID') {
         index = serializeObjectId(buffer, key, value, index);
-      } else if (isBuffer(value) || isUint8Array(value)) {
+      } else if (isUint8Array(value)) {
         index = serializeBuffer(buffer, key, value, index);
       } else if (value instanceof RegExp || isRegExp(value)) {
         index = serializeRegExp(buffer, key, value, index);
@@ -998,7 +999,7 @@ export function serializeInto(
         index = serializeNull(buffer, key, value, index);
       } else if (value['_bsontype'] === 'ObjectId' || value['_bsontype'] === 'ObjectID') {
         index = serializeObjectId(buffer, key, value, index);
-      } else if (isBuffer(value) || isUint8Array(value)) {
+      } else if (isUint8Array(value)) {
         index = serializeBuffer(buffer, key, value, index);
       } else if (value instanceof RegExp || isRegExp(value)) {
         index = serializeRegExp(buffer, key, value, index);

package/src/parser/utils.ts

@@ -1,5 +1,7 @@
 import { Buffer } from 'buffer';
 
+type RandomBytesFunction = (size: number) => Uint8Array;
+
 /**
  * Normalizes our expected stringified form of a function across versions of node
  * @param fn - The function to stringify
@@ -8,11 +10,20 @@ export function normalizedFunctionString(fn: Function): string {
   return fn.toString().replace('function(', 'function (');
 }
 
-function insecureRandomBytes(size: number): Uint8Array {
+const isReactNative =
+  typeof global.navigator === 'object' && global.navigator.product === 'ReactNative';
+
+const insecureWarning = isReactNative
+  ? 'BSON: For React Native please polyfill crypto.getRandomValues, e.g. using: https://www.npmjs.com/package/react-native-get-random-values.'
+  : 'BSON: No cryptographic implementation for random bytes present, falling back to a less secure implementation.';
+
+const insecureRandomBytes: RandomBytesFunction = function insecureRandomBytes(size: number) {
+  console.warn(insecureWarning);
+
   const result = Buffer.alloc(size);
   for (let i = 0; i < size; ++i) result[i] = Math.floor(Math.random() * 256);
   return result;
-}
+};
 
 /* We do not want to have to include DOM types just for this check */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -22,21 +33,39 @@ declare let require: Function;
 declare let global: any;
 declare const self: unknown;
 
-export let randomBytes = insecureRandomBytes;
-if (typeof window !== 'undefined' && window.crypto && window.crypto.getRandomValues) {
-  randomBytes = size => window.crypto.getRandomValues(Buffer.alloc(size));
-} else {
+const detectRandomBytes = (): RandomBytesFunction => {
+  if (typeof window !== 'undefined') {
+    // browser crypto implementation(s)
+    const target = window.crypto || window.msCrypto; // allow for IE11
+    if (target && target.getRandomValues) {
+      return size => target.getRandomValues(Buffer.alloc(size));
+    }
+  }
+
+  if (typeof global !== 'undefined' && global.crypto && global.crypto.getRandomValues) {
+    // allow for RN packages such as https://www.npmjs.com/package/react-native-get-random-values to populate global
+    return size => global.crypto.getRandomValues(Buffer.alloc(size));
+  }
+
+  let requiredRandomBytes: RandomBytesFunction | null | undefined;
   try {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    randomBytes = require('crypto').randomBytes;
+    requiredRandomBytes = require('crypto').randomBytes;
   } catch (e) {
     // keep the fallback
   }
 
   // NOTE: in transpiled cases the above require might return null/undefined
-  if (randomBytes == null) {
-    randomBytes = insecureRandomBytes;
-  }
+
+  return requiredRandomBytes || insecureRandomBytes;
+};
+
+export const randomBytes = detectRandomBytes();
+
+export function isAnyArrayBuffer(value: unknown): value is ArrayBuffer {
+  return ['[object ArrayBuffer]', '[object SharedArrayBuffer]'].includes(
+    Object.prototype.toString.call(value)
+  );
 }
 
 export function isUint8Array(value: unknown): value is Uint8Array {
@@ -51,16 +80,19 @@ export function isBigUInt64Array(value: unknown): value is BigUint64Array {
   return Object.prototype.toString.call(value) === '[object BigUint64Array]';
 }
 
+export function isRegExp(d: unknown): d is RegExp {
+  return Object.prototype.toString.call(d) === '[object RegExp]';
+}
+
+export function isMap(d: unknown): d is Map<unknown, unknown> {
+  return Object.prototype.toString.call(d) === '[object Map]';
+}
+
 /** Call to check if your environment has `Buffer` */
 export function haveBuffer(): boolean {
   return typeof global !== 'undefined' && typeof global.Buffer !== 'undefined';
 }
 
-/** Callable in any environment to check if value is a Buffer */
-export function isBuffer(value: unknown): value is Buffer {
-  return typeof value === 'object' && value?.constructor?.name === 'Buffer';
-}
-
 // To ensure that 0.4 of node works correctly
 export function isDate(d: unknown): d is Date {
   return isObjectLike(d) && Object.prototype.toString.call(d) === '[object Date]';
@@ -77,7 +109,7 @@ export function isObjectLike(candidate: unknown): candidate is Record<string, un
 
 declare let console: { warn(...message: unknown[]): void };
 export function deprecate<T extends Function>(fn: T, message: string): T {
-  if (typeof window === 'undefined' || typeof self === 'undefined') {
+  if (typeof window === 'undefined' && typeof self === 'undefined') {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     return require('util').deprecate(fn, message);
   }
@@ -87,7 +119,7 @@ export function deprecate<T extends Function>(fn: T, message: string): T {
       console.warn(message);
       warned = true;
     }
-    return fn.apply(this, ...args);
+    return fn.apply(this, args);
   }
   return (deprecated as unknown) as T;
 }

package/src/regexp.ts

@@ -25,17 +25,17 @@ export interface BSONRegExpExtended {
 export class BSONRegExp {
   _bsontype!: 'BSONRegExp';
 
-  pattern: string;
-  options: string;
+  pattern!: string;
+  options!: string;
   /**
    * @param pattern - The regular expression pattern to match
    * @param options - The regular expression options
    */
   constructor(pattern: string, options?: string) {
+    if (!(this instanceof BSONRegExp)) return new BSONRegExp(pattern, options);
+
     this.pattern = pattern;
-    this.options = options ?? '';
-    // Execute
-    alphabetize(this.options);
+    this.options = alphabetize(options ?? '');
 
     // Validate options
     for (let i = 0; i < this.options.length; i++) {

package/src/symbol.ts

@@ -10,11 +10,13 @@ export interface BSONSymbolExtended {
 export class BSONSymbol {
   _bsontype!: 'Symbol';
 
-  value: string;
+  value!: string;
   /**
    * @param value - the string representing the symbol.
    */
   constructor(value: string) {
+    if (!(this instanceof BSONSymbol)) return new BSONSymbol(value);
+
     this.value = value;
   }
 
@@ -30,7 +32,7 @@ export class BSONSymbol {
 
   /** @internal */
   inspect(): string {
-    return `BSONSymbol("${this.value}")`;
+    return `new BSONSymbol("${this.value}")`;
   }
 
   /** @internal */

package/src/timestamp.ts

@@ -31,8 +31,13 @@ export class Timestamp extends LongWithoutOverridesClass {
    * @param low - the low (signed) 32 bits of the Timestamp.
    * @param high - the high (signed) 32 bits of the Timestamp.
    */
+  constructor(low: Long);
   constructor(low: number, high: number);
   constructor(low: number | Long, high?: number) {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    ///@ts-expect-error
+    if (!(this instanceof Timestamp)) return new Timestamp(low, high);
+
     if (Long.isLong(low)) {
       super(low.low, low.high, true);
     } else {
@@ -98,6 +103,6 @@ export class Timestamp extends LongWithoutOverridesClass {
   }
 
   inspect(): string {
-    return `Timestamp(${this.getLowBits().toString()}, ${this.getHighBits().toString()})`;
+    return `new Timestamp(${this.getLowBits().toString()}, ${this.getHighBits().toString()})`;
   }
 }

package/src/uuid.ts

@@ -1,57 +1,209 @@
-/**
- * UUID regular expression pattern copied from `uuid` npm module.
- * @see https://github.com/uuidjs/uuid/blob/master/src/regex.js
- */
-const UUID_RX = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;
+import { Buffer } from 'buffer';
+import { ensureBuffer } from './ensure_buffer';
+import { Binary } from './binary';
+import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
+import { isUint8Array, randomBytes } from './parser/utils';
 
 /** @public */
-export interface UUIDExtended {
+export type UUIDExtended = {
   $uuid: string;
-}
+};
+
+const BYTE_LENGTH = 16;
+
+const kId = Symbol('id');
 
 /**
- * Parser function copied from `uuid` npm module.
- * @see https://github.com/uuidjs/uuid/blob/master/src/parse.js
- * @internal
+ * A class representation of the BSON UUID type.
+ * @public
  */
-export function parseUUID(uuid: string): Uint8Array {
-  if (typeof uuid !== 'string') {
-    throw new TypeError('Invalid type for UUID, expected string but got ' + typeof uuid);
+export class UUID {
+  // This property is not meant for direct serialization, but simply an indication that this type originates from this package.
+  _bsontype!: 'UUID';
+
+  static cacheHexString: boolean;
+
+  /** UUID Bytes @internal */
+  private [kId]: Buffer;
+  /** UUID hexString cache @internal */
+  private __id?: string;
+
+  /**
+   * Create an UUID type
+   *
+   * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
+   */
+  constructor(input?: string | Buffer | UUID) {
+    if (typeof input === 'undefined') {
+      // The most common use case (blank id, new UUID() instance)
+      this.id = UUID.generate();
+    } else if (input instanceof UUID) {
+      this[kId] = Buffer.from(input.id);
+      this.__id = input.__id;
+    } else if (ArrayBuffer.isView(input) && input.byteLength === BYTE_LENGTH) {
+      this.id = ensureBuffer(input);
+    } else if (typeof input === 'string') {
+      this.id = uuidHexStringToBuffer(input);
+    } else {
+      throw new TypeError(
+        '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).'
+      );
+    }
+  }
+
+  /**
+   * The UUID bytes
+   * @readonly
+   */
+  get id(): Buffer {
+    return this[kId];
+  }
+
+  set id(value: Buffer) {
+    this[kId] = value;
+
+    if (UUID.cacheHexString) {
+      this.__id = bufferToUuidHexString(value);
+    }
+  }
+
+  /**
+   * Generate a 16 byte uuid v4 buffer used in UUIDs
+   */
+
+  /**
+   * 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;
+    }
+
+    return uuidHexString;
   }
 
-  if (!UUID_RX.test(uuid)) {
-    throw new TypeError('Invalid format for UUID: ' + uuid);
+  /**
+   * Converts the id into a 36 character (dashes included) hex string, unless a encoding is specified.
+   * @internal
+   */
+  toString(encoding?: string): string {
+    return encoding ? this.id.toString(encoding) : this.toHexString();
   }
 
-  let v;
-  const arr = new Uint8Array(16);
+  /**
+   * Converts the id into its JSON string representation. A 36 character (dashes included) hex string in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+   * @internal
+   */
+  toJSON(): string {
+    return this.toHexString();
+  }
+
+  /**
+   * Compares the equality of this UUID with `otherID`.
+   *
+   * @param otherId - UUID instance to compare against.
+   */
+  equals(otherId: string | Buffer | UUID): boolean {
+    if (!otherId) {
+      return false;
+    }
+
+    if (otherId instanceof UUID) {
+      return otherId.id.equals(this.id);
+    }
+
+    try {
+      return new UUID(otherId).id.equals(this.id);
+    } catch {
+      return false;
+    }
+  }
 
-  // Parse ########-....-....-....-............
-  arr[0] = (v = parseInt(uuid.slice(0, 8), 16)) >>> 24;
-  arr[1] = (v >>> 16) & 0xff;
-  arr[2] = (v >>> 8) & 0xff;
-  arr[3] = v & 0xff;
+  /**
+   * Creates a Binary instance from the current UUID.
+   */
+  toBinary(): Binary {
+    return new Binary(this.id, Binary.SUBTYPE_UUID);
+  }
+
+  /**
+   * Generates a populated buffer containing a v4 uuid
+   */
+  static generate(): Buffer {
+    const bytes = randomBytes(BYTE_LENGTH);
+
+    // Per 4.4, set bits for version and `clock_seq_hi_and_reserved`
+    // Kindly borrowed from https://github.com/uuidjs/uuid/blob/master/src/v4.js
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+    return Buffer.from(bytes);
+  }
 
-  // Parse ........-####-....-....-............
-  arr[4] = (v = parseInt(uuid.slice(9, 13), 16)) >>> 8;
-  arr[5] = v & 0xff;
+  /**
+   * Checks if a value is a valid bson UUID
+   * @param input - UUID, string or Buffer to validate.
+   */
+  static isValid(input: string | Buffer | UUID): boolean {
+    if (!input) {
+      return false;
+    }
 
-  // Parse ........-....-####-....-............
-  arr[6] = (v = parseInt(uuid.slice(14, 18), 16)) >>> 8;
-  arr[7] = v & 0xff;
+    if (input instanceof UUID) {
+      return true;
+    }
 
-  // Parse ........-....-....-####-............
-  arr[8] = (v = parseInt(uuid.slice(19, 23), 16)) >>> 8;
-  arr[9] = v & 0xff;
+    if (typeof input === 'string') {
+      return uuidValidateString(input);
+    }
 
-  // Parse ........-....-....-....-############
-  // (Use "/" to avoid 32-bit truncation when bit-shifting high-order bytes)
-  arr[10] = ((v = parseInt(uuid.slice(24, 36), 16)) / 0x10000000000) & 0xff;
-  arr[11] = (v / 0x100000000) & 0xff;
-  arr[12] = (v >>> 24) & 0xff;
-  arr[13] = (v >>> 16) & 0xff;
-  arr[14] = (v >>> 8) & 0xff;
-  arr[15] = v & 0xff;
+    if (isUint8Array(input)) {
+      // check for length & uuid version (https://tools.ietf.org/html/rfc4122#section-4.1.3)
+      if (input.length !== BYTE_LENGTH) {
+        return false;
+      }
 
-  return arr;
+      try {
+        // get this byte as hex:             xxxxxxxx-xxxx-XXxx-xxxx-xxxxxxxxxxxx
+        // check first part as uuid version: xxxxxxxx-xxxx-Xxxx-xxxx-xxxxxxxxxxxx
+        return parseInt(input[6].toString(16)[0], 10) === Binary.SUBTYPE_UUID;
+      } catch {
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 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);
+    return new UUID(buffer);
+  }
+
+  /**
+   * Converts to a string representation of this Id.
+   *
+   * @returns return the 36 character hex string representation.
+   * @internal
+   */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    return `new UUID("${this.toHexString()}")`;
+  }
 }
+
+Object.defineProperty(UUID.prototype, '_bsontype', { value: 'UUID' });

package/src/uuid_utils.ts

@@ -0,0 +1,31 @@
+import { Buffer } from 'buffer';
+
+// 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): Buffer => {
+  if (!uuidValidateString(hexString)) {
+    throw new TypeError(
+      '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 Buffer.from(sanitizedHexString, 'hex');
+};
+
+export const bufferToUuidHexString = (buffer: Buffer, includeDashes = true): string =>
+  includeDashes
+    ? buffer.toString('hex', 0, 4) +
+      '-' +
+      buffer.toString('hex', 4, 6) +
+      '-' +
+      buffer.toString('hex', 6, 8) +
+      '-' +
+      buffer.toString('hex', 8, 10) +
+      '-' +
+      buffer.toString('hex', 10, 16)
+    : buffer.toString('hex');