bson 4.7.0 → 5.0.0-alpha.1

package/src/parser/utils.ts

@@ -1,73 +1,3 @@
-import { Buffer } from 'buffer';
-import { getGlobal } from '../utils/global';
-
-type RandomBytesFunction = (size: number) => Uint8Array;
-
-/**
- * Normalizes our expected stringified form of a function across versions of node
- * @param fn - The function to stringify
- */
-export function normalizedFunctionString(fn: Function): string {
-  return fn.toString().replace('function(', 'function (');
-}
-
-function isReactNative() {
-  const g = getGlobal<{ navigator?: { product?: string } }>();
-  return typeof g.navigator === 'object' && g.navigator.product === 'ReactNative';
-}
-
-const insecureRandomBytes: RandomBytesFunction = function insecureRandomBytes(size: number) {
-  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.';
-  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
-declare let window: any;
-declare let require: Function;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-declare let global: any;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-declare let process: any; // Used by @rollup/plugin-replace
-
-const detectRandomBytes = (): RandomBytesFunction => {
-  if (process.browser) {
-    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));
-    }
-
-    return insecureRandomBytes;
-  } else {
-    let requiredRandomBytes: RandomBytesFunction | null | undefined;
-    try {
-      requiredRandomBytes = require('crypto').randomBytes;
-    } catch (e) {
-      // keep the fallback
-    }
-
-    // NOTE: in transpiled cases the above require might return null/undefined
-
-    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)
@@ -94,34 +24,6 @@ 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';
-}
-
-// 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]';
-}
-
-/**
- * @internal
- * this is to solve the `'someKey' in x` problem where x is unknown.
- * https://github.com/typescript-eslint/typescript-eslint/issues/1071#issuecomment-541955753
- */
-export function isObjectLike(candidate: unknown): candidate is Record<string, unknown> {
-  return typeof candidate === 'object' && candidate !== null;
-}
-
-declare let console: { warn(...message: unknown[]): void };
-export function deprecate<T extends Function>(fn: T, message: string): T {
-  let warned = false;
-  function deprecated(this: unknown, ...args: unknown[]) {
-    if (!warned) {
-      console.warn(message);
-      warned = true;
-    }
-    return fn.apply(this, args);
-  }
-  return deprecated as unknown as T;
+  return Object.prototype.toString.call(d) === '[object Date]';
 }

package/src/regexp.ts

@@ -1,3 +1,4 @@
+import { BSON_MAJOR_VERSION } from './constants';
 import { BSONError, BSONTypeError } from './error';
 import type { EJSONOptions } from './extended_json';
 
@@ -25,7 +26,13 @@ export interface BSONRegExpExtended {
  * @category BSONType
  */
 export class BSONRegExp {
-  _bsontype!: 'BSONRegExp';
+  get _bsontype(): 'BSONRegExp' {
+    return 'BSONRegExp';
+  }
+  /** @internal */
+  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
+    return BSON_MAJOR_VERSION;
+  }
 
   pattern!: string;
   options!: string;
@@ -34,8 +41,6 @@ export class BSONRegExp {
    * @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 = alphabetize(options ?? '');
 
@@ -100,6 +105,13 @@ export class BSONRegExp {
     }
     throw new BSONTypeError(`Unexpected BSONRegExp EJSON object form: ${JSON.stringify(doc)}`);
   }
-}
 
-Object.defineProperty(BSONRegExp.prototype, '_bsontype', { value: 'BSONRegExp' });
+  /** @internal */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    return `new BSONRegExp(${JSON.stringify(this.pattern)}, ${JSON.stringify(this.options)})`;
+  }
+}

package/src/symbol.ts

@@ -1,3 +1,5 @@
+import { BSON_MAJOR_VERSION } from './constants';
+
 /** @public */
 export interface BSONSymbolExtended {
   $symbol: string;
@@ -9,15 +11,19 @@ export interface BSONSymbolExtended {
  * @category BSONType
  */
 export class BSONSymbol {
-  _bsontype!: 'Symbol';
+  get _bsontype(): 'BSONSymbol' {
+    return 'BSONSymbol';
+  }
+  /** @internal */
+  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
+    return BSON_MAJOR_VERSION;
+  }
 
   value!: string;
   /**
    * @param value - the string representing the symbol.
    */
   constructor(value: string) {
-    if (!(this instanceof BSONSymbol)) return new BSONSymbol(value);
-
     this.value = value;
   }
 
@@ -54,5 +60,3 @@ export class BSONSymbol {
     return this.inspect();
   }
 }
-
-Object.defineProperty(BSONSymbol.prototype, '_bsontype', { value: 'Symbol' });

package/src/timestamp.ts

@@ -1,10 +1,16 @@
+import { BSON_MAJOR_VERSION } from './constants';
+import { BSONError } from './error';
+import type { Int32 } from './int_32';
 import { Long } from './long';
-import { isObjectLike } from './parser/utils';
 
 /** @public */
 export type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromExtendedJSON' | 'inspect';
 /** @public */
-export type LongWithoutOverrides = new (low: unknown, high?: number, unsigned?: boolean) => {
+export type LongWithoutOverrides = new (
+  low: unknown,
+  high?: number | boolean,
+  unsigned?: boolean
+) => {
   [P in Exclude<keyof Long, TimestampOverrides>]: Long[P];
 };
 /** @public */
@@ -24,42 +30,65 @@ export interface TimestampExtended {
  * @category BSONType
  * */
 export class Timestamp extends LongWithoutOverridesClass {
-  _bsontype!: 'Timestamp';
+  get _bsontype(): 'Timestamp' {
+    return 'Timestamp';
+  }
+  /** @internal */
+  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
+    return BSON_MAJOR_VERSION;
+  }
 
   static readonly MAX_VALUE = Long.MAX_UNSIGNED_VALUE;
 
   /**
-   * @param low - A 64-bit Long representing the Timestamp.
+   * @param int - A 64-bit bigint representing the Timestamp.
+   */
+  constructor(int: bigint);
+  /**
+   * @param long - A 64-bit Long representing the Timestamp.
    */
   constructor(long: Long);
   /**
    * @param value - A pair of two values indicating timestamp and increment.
    */
   constructor(value: { t: number; i: number });
-  /**
-   * @param low - the low (signed) 32 bits of the Timestamp.
-   * @param high - the high (signed) 32 bits of the Timestamp.
-   * @deprecated Please use `Timestamp({ t: high, i: low })` or `Timestamp(Long(low, high))` instead.
-   */
-  constructor(low: number, high: number);
-  constructor(low: number | Long | { t: number; i: number }, 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)) {
+  constructor(low?: bigint | Long | { t: number | Int32; i: number | Int32 }) {
+    if (low == null) {
+      super(0, 0, true);
+    } else if (typeof low === 'bigint') {
+      super(low, true);
+    } else if (Long.isLong(low)) {
       super(low.low, low.high, true);
-    } else if (isObjectLike(low) && typeof low.t !== 'undefined' && typeof low.i !== 'undefined') {
-      super(low.i, low.t, true);
+    } else if (typeof low === 'object' && 't' in low && 'i' in low) {
+      if (typeof low.t !== 'number' && (typeof low.t !== 'object' || low.t._bsontype !== 'Int32')) {
+        throw new BSONError('Timestamp constructed from { t, i } must provide t as a number');
+      }
+      if (typeof low.i !== 'number' && (typeof low.i !== 'object' || low.i._bsontype !== 'Int32')) {
+        throw new BSONError('Timestamp constructed from { t, i } must provide i as a number');
+      }
+      if (low.t < 0) {
+        throw new BSONError('Timestamp constructed from { t, i } must provide a positive t');
+      }
+      if (low.i < 0) {
+        throw new BSONError('Timestamp constructed from { t, i } must provide a positive i');
+      }
+      if (low.t > 0xffff_ffff) {
+        throw new BSONError(
+          'Timestamp constructed from { t, i } must provide t equal or less than uint32 max'
+        );
+      }
+      if (low.i > 0xffff_ffff) {
+        throw new BSONError(
+          'Timestamp constructed from { t, i } must provide i equal or less than uint32 max'
+        );
+      }
+
+      super(low.i.valueOf(), low.t.valueOf(), true);
     } else {
-      super(low, high, true);
+      throw new BSONError(
+        'A Timestamp can only be constructed with: bigint, Long, or { t: number; i: number }'
+      );
     }
-    Object.defineProperty(this, '_bsontype', {
-      value: 'Timestamp',
-      writable: false,
-      configurable: false,
-      enumerable: false
-    });
   }
 
   toJSON(): { $timestamp: string } {
@@ -85,7 +114,7 @@ export class Timestamp extends LongWithoutOverridesClass {
    * @param highBits - the high 32-bits.
    */
   static fromBits(lowBits: number, highBits: number): Timestamp {
-    return new Timestamp(lowBits, highBits);
+    return new Timestamp({ i: lowBits, t: highBits });
   }
 
   /**
@@ -105,7 +134,14 @@ export class Timestamp extends LongWithoutOverridesClass {
 
   /** @internal */
   static fromExtendedJSON(doc: TimestampExtended): Timestamp {
-    return new Timestamp(doc.$timestamp);
+    // The Long check is necessary because extended JSON has different behavior given the size of the input number
+    const i = Long.isLong(doc.$timestamp.i)
+      ? doc.$timestamp.i.getLowBitsUnsigned() // Need to fetch the least significant 32 bits
+      : doc.$timestamp.i;
+    const t = Long.isLong(doc.$timestamp.t)
+      ? doc.$timestamp.t.getLowBitsUnsigned() // Need to fetch the least significant 32 bits
+      : doc.$timestamp.t;
+    return new Timestamp({ t, i });
   }
 
   /** @internal */

package/src/utils/byte_utils.ts

@@ -0,0 +1,61 @@
+import { nodeJsByteUtils } from './node_byte_utils';
+import { webByteUtils } from './web_byte_utils';
+
+/** @internal */
+export type ByteUtils = {
+  /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
+  toLocalBufferType(buffer: Uint8Array | ArrayBufferView | ArrayBuffer): Uint8Array;
+  /** Create empty space of size */
+  allocate: (size: number) => Uint8Array;
+  /** Check if two Uint8Arrays are deep equal */
+  equals: (a: Uint8Array, b: Uint8Array) => boolean;
+  /** Check if two Uint8Arrays are deep equal */
+  fromNumberArray: (array: number[]) => Uint8Array;
+  /** Create a Uint8Array from a base64 string */
+  fromBase64: (base64: string) => Uint8Array;
+  /** Create a base64 string from bytes */
+  toBase64: (buffer: Uint8Array) => string;
+  /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+  fromISO88591: (codePoints: string) => Uint8Array;
+  /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+  toISO88591: (buffer: Uint8Array) => string;
+  /** Create a Uint8Array from a hex string */
+  fromHex: (hex: string) => Uint8Array;
+  /** Create a hex string from bytes */
+  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) => 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. */
+  encodeUTF8Into(destination: Uint8Array, source: string, byteOffset: number): number;
+  /** Generate a Uint8Array filled with random bytes with byteLength */
+  randomBytes(byteLength: number): Uint8Array;
+};
+
+declare const Buffer: { new (): unknown; prototype?: { _isBuffer?: boolean } } | undefined;
+
+/**
+ * Check that a global Buffer exists that is a function and
+ * does not have a '_isBuffer' property defined on the prototype
+ * (this is to prevent using the npm buffer)
+ */
+const hasGlobalBuffer = typeof Buffer === 'function' && Buffer.prototype?._isBuffer !== true;
+
+/**
+ * This is the only ByteUtils that should be used across the rest of the BSON library.
+ *
+ * The type annotation is important here, it asserts that each of the platform specific
+ * utils implementations are compatible with the common one.
+ *
+ * @internal
+ */
+export const ByteUtils: ByteUtils = hasGlobalBuffer ? nodeJsByteUtils : webByteUtils;
+
+export class BSONDataView extends DataView {
+  static fromUint8Array(input: Uint8Array) {
+    return new DataView(input.buffer, input.byteOffset, input.byteLength);
+  }
+}

package/src/utils/node_byte_utils.ts

@@ -0,0 +1,141 @@
+import { BSONError } from '../error';
+
+type NodeJsEncoding = 'base64' | 'hex' | 'utf8' | 'binary';
+type NodeJsBuffer = ArrayBufferView &
+  Uint8Array & {
+    write(string: string, offset: number, length: undefined, encoding: 'utf8'): number;
+    copy(target: Uint8Array, targetStart: number, sourceStart: number, sourceEnd: number): number;
+    toString: (this: Uint8Array, encoding: NodeJsEncoding) => string;
+    equals: (this: Uint8Array, other: Uint8Array) => boolean;
+  };
+type NodeJsBufferConstructor = Omit<Uint8ArrayConstructor, 'from'> & {
+  alloc: (size: number) => NodeJsBuffer;
+  from(array: number[]): NodeJsBuffer;
+  from(array: Uint8Array): NodeJsBuffer;
+  from(array: ArrayBuffer): NodeJsBuffer;
+  from(array: ArrayBuffer, byteOffset: number, byteLength: number): NodeJsBuffer;
+  from(base64: string, encoding: NodeJsEncoding): NodeJsBuffer;
+  byteLength(input: string, encoding: 'utf8'): number;
+  isBuffer(value: unknown): value is NodeJsBuffer;
+};
+
+// This can be nullish, but we gate the nodejs functions on being exported whether or not this exists
+// Node.js global
+declare const Buffer: NodeJsBufferConstructor;
+declare const require: (mod: 'node:crypto') => { randomBytes: (byteLength: number) => Uint8Array };
+
+/** @internal */
+export function nodejsMathRandomBytes(byteLength: number) {
+  return nodeJsByteUtils.fromNumberArray(
+    Array.from({ length: byteLength }, () => Math.floor(Math.random() * 256))
+  );
+}
+
+/**
+ * @internal
+ * WARNING: REQUIRE WILL BE REWRITTEN
+ *
+ * This code is carefully used by require_rewriter.mjs any modifications must be reflected in the plugin.
+ *
+ * @remarks
+ * "crypto" is the only dependency BSON needs. This presents a problem for creating a bundle of the BSON library
+ * in an es module format that can be used both on the browser and in Node.js. In Node.js when BSON is imported as
+ * an es module, there will be no global require function defined, making the code below fallback to the much less desireable math.random bytes.
+ * In order to make our es module bundle work as expected on Node.js we need to change this `require()` to a dynamic import, and the dynamic
+ * import must be top-level awaited since es modules are async. So we rely on a custom rollup plugin to seek out the following lines of code
+ * and replace `require` with `await import` and the IIFE line (`nodejsRandomBytes = (() => { ... })()`) with `nodejsRandomBytes = await (async () => { ... })()`
+ * when generating an es module bundle.
+ */
+const nodejsRandomBytes: (byteLength: number) => Uint8Array = (() => {
+  try {
+    return require('node:crypto').randomBytes;
+  } catch {
+    return nodejsMathRandomBytes;
+  }
+})();
+
+/** @internal */
+export const nodeJsByteUtils = {
+  toLocalBufferType(potentialBuffer: Uint8Array | NodeJsBuffer | ArrayBuffer): NodeJsBuffer {
+    if (Buffer.isBuffer(potentialBuffer)) {
+      return potentialBuffer;
+    }
+
+    if (ArrayBuffer.isView(potentialBuffer)) {
+      return Buffer.from(
+        potentialBuffer.buffer,
+        potentialBuffer.byteOffset,
+        potentialBuffer.byteLength
+      );
+    }
+
+    const stringTag =
+      potentialBuffer?.[Symbol.toStringTag] ?? Object.prototype.toString.call(potentialBuffer);
+    if (
+      stringTag === 'ArrayBuffer' ||
+      stringTag === 'SharedArrayBuffer' ||
+      stringTag === '[object ArrayBuffer]' ||
+      stringTag === '[object SharedArrayBuffer]'
+    ) {
+      return Buffer.from(potentialBuffer);
+    }
+
+    throw new BSONError(`Cannot create Buffer from ${String(potentialBuffer)}`);
+  },
+
+  allocate(size: number): NodeJsBuffer {
+    return Buffer.alloc(size);
+  },
+
+  equals(a: Uint8Array, b: Uint8Array): boolean {
+    return nodeJsByteUtils.toLocalBufferType(a).equals(b);
+  },
+
+  fromNumberArray(array: number[]): NodeJsBuffer {
+    return Buffer.from(array);
+  },
+
+  fromBase64(base64: string): NodeJsBuffer {
+    return Buffer.from(base64, 'base64');
+  },
+
+  toBase64(buffer: Uint8Array): string {
+    return nodeJsByteUtils.toLocalBufferType(buffer).toString('base64');
+  },
+
+  /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+  fromISO88591(codePoints: string): NodeJsBuffer {
+    return Buffer.from(codePoints, 'binary');
+  },
+
+  /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+  toISO88591(buffer: Uint8Array): string {
+    return nodeJsByteUtils.toLocalBufferType(buffer).toString('binary');
+  },
+
+  fromHex(hex: string): NodeJsBuffer {
+    return Buffer.from(hex, 'hex');
+  },
+
+  toHex(buffer: Uint8Array): string {
+    return nodeJsByteUtils.toLocalBufferType(buffer).toString('hex');
+  },
+
+  fromUTF8(text: string): NodeJsBuffer {
+    return Buffer.from(text, 'utf8');
+  },
+
+  toUTF8(buffer: Uint8Array): string {
+    return nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8');
+  },
+
+  utf8ByteLength(input: string): number {
+    return Buffer.byteLength(input, 'utf8');
+  },
+
+  encodeUTF8Into(buffer: Uint8Array, source: string, byteOffset: number): number {
+    return nodeJsByteUtils.toLocalBufferType(buffer).write(source, byteOffset, undefined, 'utf8');
+  },
+
+  randomBytes: nodejsRandomBytes
+};