bson 6.4.0 → 6.6.0

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "6.4.0",
+  "version": "6.6.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"

package/src/binary.ts

@@ -56,6 +56,8 @@ export class Binary extends BSONValue {
   static readonly SUBTYPE_ENCRYPTED = 6;
   /** Column BSON type */
   static readonly SUBTYPE_COLUMN = 7;
+  /** Sensitive BSON type */
+  static readonly SUBTYPE_SENSITIVE = 8;
   /** User BSON type */
   static readonly SUBTYPE_USER_DEFINED = 128;
 
@@ -184,15 +186,15 @@ export class Binary extends BSONValue {
   }
 
   toJSON(): string {
-    return ByteUtils.toBase64(this.buffer);
+    return ByteUtils.toBase64(this.buffer.subarray(0, this.position));
   }
 
   toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string {
-    if (encoding === 'hex') return ByteUtils.toHex(this.buffer);
-    if (encoding === 'base64') return ByteUtils.toBase64(this.buffer);
+    if (encoding === 'hex') return ByteUtils.toHex(this.buffer.subarray(0, this.position));
+    if (encoding === 'base64') return ByteUtils.toBase64(this.buffer.subarray(0, this.position));
     if (encoding === 'utf8' || encoding === 'utf-8')
-      return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
-    return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
+      return ByteUtils.toUTF8(this.buffer, 0, this.position, false);
+    return ByteUtils.toUTF8(this.buffer, 0, this.position, false);
   }
 
   /** @internal */

package/src/bson.ts

@@ -51,9 +51,10 @@ export {
   Decimal128
 };
 export { BSONValue } from './bson_value';
-export { BSONError, BSONVersionError, BSONRuntimeError } from './error';
+export { BSONError, BSONVersionError, BSONRuntimeError, BSONOffsetError } from './error';
 export { BSONType } from './constants';
 export { EJSON } from './extended_json';
+export { onDemand, type OnDemand } from './parser/on_demand/index';
 
 /** @public */
 export interface Document {

package/src/constants.ts

@@ -109,6 +109,9 @@ export const BSON_BINARY_SUBTYPE_ENCRYPTED = 6;
 /** Column BSON type @internal */
 export const BSON_BINARY_SUBTYPE_COLUMN = 7;
 
+/** Sensitive BSON type @internal */
+export const BSON_BINARY_SUBTYPE_SENSITIVE = 8;
+
 /** Binary User Defined Type @internal */
 export const BSON_BINARY_SUBTYPE_USER_DEFINED = 128;
 

package/src/error.ts

@@ -81,3 +81,25 @@ export class BSONRuntimeError extends BSONError {
     super(message);
   }
 }
+
+/**
+ * @public
+ * @category Error
+ *
+ * @experimental
+ *
+ * An error generated when BSON bytes are invalid.
+ * Reports the offset the parser was able to reach before encountering the error.
+ */
+export class BSONOffsetError extends BSONError {
+  public get name(): 'BSONOffsetError' {
+    return 'BSONOffsetError';
+  }
+
+  public offset: number;
+
+  constructor(message: string, offset: number, options?: { cause?: unknown }) {
+    super(`${message}. offset: ${offset}`, options);
+    this.offset = offset;
+  }
+}

package/src/parser/on_demand/index.ts

@@ -0,0 +1,32 @@
+import { ByteUtils } from '../../utils/byte_utils';
+import { NumberUtils } from '../../utils/number_utils';
+import { type BSONElement, parseToElements } from './parse_to_elements';
+/**
+ * @experimental
+ * @public
+ *
+ * A new set of BSON APIs that are currently experimental and not intended for production use.
+ */
+export type OnDemand = {
+  parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+  // Types
+  BSONElement: BSONElement;
+
+  // Utils
+  ByteUtils: ByteUtils;
+  NumberUtils: NumberUtils;
+};
+
+/**
+ * @experimental
+ * @public
+ */
+const onDemand: OnDemand = Object.create(null);
+
+onDemand.parseToElements = parseToElements;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
+
+Object.freeze(onDemand);
+
+export { onDemand };

package/src/parser/on_demand/parse_to_elements.ts

@@ -0,0 +1,188 @@
+import { BSONOffsetError } from '../../error';
+import { NumberUtils } from '../../utils/number_utils';
+
+/**
+ * @internal
+ *
+ * @remarks
+ * - This enum is const so the code we produce will inline the numbers
+ * - `minKey` is set to 255 so unsigned comparisons succeed
+ * - Modify with caution, double check the bundle contains literals
+ */
+const enum BSONElementType {
+  double = 1,
+  string = 2,
+  object = 3,
+  array = 4,
+  binData = 5,
+  undefined = 6,
+  objectId = 7,
+  bool = 8,
+  date = 9,
+  null = 10,
+  regex = 11,
+  dbPointer = 12,
+  javascript = 13,
+  symbol = 14,
+  javascriptWithScope = 15,
+  int = 16,
+  timestamp = 17,
+  long = 18,
+  decimal = 19,
+  minKey = 255,
+  maxKey = 127
+}
+
+/**
+ * @public
+ * @experimental
+ */
+export type BSONElement = [
+  type: number,
+  nameOffset: number,
+  nameLength: number,
+  offset: number,
+  length: number
+];
+
+function getSize(source: Uint8Array, offset: number) {
+  try {
+    return NumberUtils.getNonnegativeInt32LE(source, offset);
+  } catch (cause) {
+    throw new BSONOffsetError('BSON size cannot be negative', offset, { cause });
+  }
+}
+
+/**
+ * Searches for null terminator of a BSON element's value (Never the document null terminator)
+ * **Does not** bounds check since this should **ONLY** be used within parseToElements which has asserted that `bytes` ends with a `0x00`.
+ * So this will at most iterate to the document's terminator and error if that is the offset reached.
+ */
+function findNull(bytes: Uint8Array, offset: number): number {
+  let nullTerminatorOffset = offset;
+
+  for (; bytes[nullTerminatorOffset] !== 0x00; nullTerminatorOffset++);
+
+  if (nullTerminatorOffset === bytes.length - 1) {
+    // We reached the null terminator of the document, not a value's
+    throw new BSONOffsetError('Null terminator not found', offset);
+  }
+
+  return nullTerminatorOffset;
+}
+
+/**
+ * @public
+ * @experimental
+ */
+export function parseToElements(
+  bytes: Uint8Array,
+  startOffset: number | null = 0
+): Iterable<BSONElement> {
+  startOffset ??= 0;
+
+  if (bytes.length < 5) {
+    throw new BSONOffsetError(
+      `Input must be at least 5 bytes, got ${bytes.length} bytes`,
+      startOffset
+    );
+  }
+
+  const documentSize = getSize(bytes, startOffset);
+
+  if (documentSize > bytes.length - startOffset) {
+    throw new BSONOffsetError(
+      `Parsed documentSize (${documentSize} bytes) does not match input length (${bytes.length} bytes)`,
+      startOffset
+    );
+  }
+
+  if (bytes[startOffset + documentSize - 1] !== 0x00) {
+    throw new BSONOffsetError('BSON documents must end in 0x00', startOffset + documentSize);
+  }
+
+  const elements: BSONElement[] = [];
+  let offset = startOffset + 4;
+
+  while (offset <= documentSize + startOffset) {
+    const type = bytes[offset];
+    offset += 1;
+
+    if (type === 0) {
+      if (offset - startOffset !== documentSize) {
+        throw new BSONOffsetError(`Invalid 0x00 type byte`, offset);
+      }
+      break;
+    }
+
+    const nameOffset = offset;
+    const nameLength = findNull(bytes, offset) - nameOffset;
+    offset += nameLength + 1;
+
+    let length: number;
+
+    if (
+      type === BSONElementType.double ||
+      type === BSONElementType.long ||
+      type === BSONElementType.date ||
+      type === BSONElementType.timestamp
+    ) {
+      length = 8;
+    } else if (type === BSONElementType.int) {
+      length = 4;
+    } else if (type === BSONElementType.objectId) {
+      length = 12;
+    } else if (type === BSONElementType.decimal) {
+      length = 16;
+    } else if (type === BSONElementType.bool) {
+      length = 1;
+    } else if (
+      type === BSONElementType.null ||
+      type === BSONElementType.undefined ||
+      type === BSONElementType.maxKey ||
+      type === BSONElementType.minKey
+    ) {
+      length = 0;
+    }
+    // Needs a size calculation
+    else if (type === BSONElementType.regex) {
+      length = findNull(bytes, findNull(bytes, offset) + 1) + 1 - offset;
+    } else if (
+      type === BSONElementType.object ||
+      type === BSONElementType.array ||
+      type === BSONElementType.javascriptWithScope
+    ) {
+      length = getSize(bytes, offset);
+    } else if (
+      type === BSONElementType.string ||
+      type === BSONElementType.binData ||
+      type === BSONElementType.dbPointer ||
+      type === BSONElementType.javascript ||
+      type === BSONElementType.symbol
+    ) {
+      length = getSize(bytes, offset) + 4;
+      if (type === BSONElementType.binData) {
+        // binary subtype
+        length += 1;
+      }
+      if (type === BSONElementType.dbPointer) {
+        // dbPointer's objectId
+        length += 12;
+      }
+    } else {
+      throw new BSONOffsetError(
+        `Invalid 0x${type.toString(16).padStart(2, '0')} type byte`,
+        offset
+      );
+    }
+
+    if (length > documentSize) {
+      throw new BSONOffsetError('value reports length larger than document', offset);
+    }
+
+    elements.push([type, nameOffset, nameLength, offset, length]);
+    offset += length;
+  }
+
+  return elements;
+}

package/src/utils/byte_utils.ts

@@ -1,10 +1,16 @@
 import { nodeJsByteUtils } from './node_byte_utils';
 import { webByteUtils } from './web_byte_utils';
 
-/** @internal */
+/**
+ * @public
+ * @experimental
+ *
+ * A collection of functions that help work with data in a Uint8Array.
+ * ByteUtils is configured at load time to use Node.js or Web based APIs for the internal implementations.
+ */
 export type ByteUtils = {
   /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
-  toLocalBufferType(buffer: Uint8Array | ArrayBufferView | ArrayBuffer): Uint8Array;
+  toLocalBufferType: (buffer: Uint8Array | ArrayBufferView | ArrayBuffer) => Uint8Array;
   /** Create empty space of size */
   allocate: (size: number) => Uint8Array;
   /** Create empty space of size, use pooled memory when available */
@@ -30,9 +36,9 @@ export type ByteUtils = {
   /** 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;
+  encodeUTF8Into: (destination: Uint8Array, source: string, byteOffset: number) => number;
   /** Generate a Uint8Array filled with random bytes with byteLength */
-  randomBytes(byteLength: number): Uint8Array;
+  randomBytes: (byteLength: number) => Uint8Array;
 };
 
 declare const Buffer: { new (): unknown; prototype?: { _isBuffer?: boolean } } | undefined;

package/src/utils/number_utils.ts

@@ -1,12 +1,52 @@
 const FLOAT = new Float64Array(1);
 const FLOAT_BYTES = new Uint8Array(FLOAT.buffer, 0, 8);
 
+FLOAT[0] = -1;
+// Little endian [0, 0, 0, 0, 0, 0,  240, 191]
+// Big endian    [191, 240, 0, 0, 0, 0, 0, 0]
+const isBigEndian = FLOAT_BYTES[7] === 0;
+
+/**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+export type NumberUtils = {
+  /**
+   * Parses a signed int32 at offset. Throws a `RangeError` if value is negative.
+   */
+  getNonnegativeInt32LE: (source: Uint8Array, offset: number) => number;
+  getInt32LE: (source: Uint8Array, offset: number) => number;
+  getUint32LE: (source: Uint8Array, offset: number) => number;
+  getUint32BE: (source: Uint8Array, offset: number) => number;
+  getBigInt64LE: (source: Uint8Array, offset: number) => bigint;
+  getFloat64LE: (source: Uint8Array, offset: number) => number;
+  setInt32BE: (destination: Uint8Array, offset: number, value: number) => 4;
+  setInt32LE: (destination: Uint8Array, offset: number, value: number) => 4;
+  setBigInt64LE: (destination: Uint8Array, offset: number, value: bigint) => 8;
+  setFloat64LE: (destination: Uint8Array, offset: number, value: number) => 8;
+};
+
 /**
  * Number parsing and serializing utilities.
  *
- * @internal
+ * @experimental
+ * @public
  */
-export const NumberUtils = {
+export const NumberUtils: NumberUtils = {
+  getNonnegativeInt32LE(source: Uint8Array, offset: number): number {
+    if (source[offset + 3] > 127) {
+      throw new RangeError(`Size cannot be negative at offset: ${offset}`);
+    }
+    return (
+      source[offset] |
+      (source[offset + 1] << 8) |
+      (source[offset + 2] << 16) |
+      (source[offset + 3] << 24)
+    );
+  },
+
   /** Reads a little-endian 32-bit integer from source */
   getInt32LE(source: Uint8Array, offset: number): number {
     return (
@@ -50,17 +90,29 @@ export const NumberUtils = {
   },
 
   /** Reads a little-endian 64-bit float from source */
-  getFloat64LE(source: Uint8Array, offset: number): number {
-    FLOAT_BYTES[0] = source[offset];
-    FLOAT_BYTES[1] = source[offset + 1];
-    FLOAT_BYTES[2] = source[offset + 2];
-    FLOAT_BYTES[3] = source[offset + 3];
-    FLOAT_BYTES[4] = source[offset + 4];
-    FLOAT_BYTES[5] = source[offset + 5];
-    FLOAT_BYTES[6] = source[offset + 6];
-    FLOAT_BYTES[7] = source[offset + 7];
-    return FLOAT[0];
-  },
+  getFloat64LE: isBigEndian
+    ? (source: Uint8Array, offset: number) => {
+        FLOAT_BYTES[7] = source[offset];
+        FLOAT_BYTES[6] = source[offset + 1];
+        FLOAT_BYTES[5] = source[offset + 2];
+        FLOAT_BYTES[4] = source[offset + 3];
+        FLOAT_BYTES[3] = source[offset + 4];
+        FLOAT_BYTES[2] = source[offset + 5];
+        FLOAT_BYTES[1] = source[offset + 6];
+        FLOAT_BYTES[0] = source[offset + 7];
+        return FLOAT[0];
+      }
+    : (source: Uint8Array, offset: number) => {
+        FLOAT_BYTES[0] = source[offset];
+        FLOAT_BYTES[1] = source[offset + 1];
+        FLOAT_BYTES[2] = source[offset + 2];
+        FLOAT_BYTES[3] = source[offset + 3];
+        FLOAT_BYTES[4] = source[offset + 4];
+        FLOAT_BYTES[5] = source[offset + 5];
+        FLOAT_BYTES[6] = source[offset + 6];
+        FLOAT_BYTES[7] = source[offset + 7];
+        return FLOAT[0];
+      },
 
   /** Writes a big-endian 32-bit integer to destination, can be signed or unsigned */
   setInt32BE(destination: Uint8Array, offset: number, value: number): 4 {
@@ -120,16 +172,29 @@ export const NumberUtils = {
   },
 
   /** Writes a little-endian 64-bit float to destination */
-  setFloat64LE(destination: Uint8Array, offset: number, value: number): 8 {
-    FLOAT[0] = value;
-    destination[offset] = FLOAT_BYTES[0];
-    destination[offset + 1] = FLOAT_BYTES[1];
-    destination[offset + 2] = FLOAT_BYTES[2];
-    destination[offset + 3] = FLOAT_BYTES[3];
-    destination[offset + 4] = FLOAT_BYTES[4];
-    destination[offset + 5] = FLOAT_BYTES[5];
-    destination[offset + 6] = FLOAT_BYTES[6];
-    destination[offset + 7] = FLOAT_BYTES[7];
-    return 8;
-  }
+  setFloat64LE: isBigEndian
+    ? (destination: Uint8Array, offset: number, value: number) => {
+        FLOAT[0] = value;
+        destination[offset] = FLOAT_BYTES[7];
+        destination[offset + 1] = FLOAT_BYTES[6];
+        destination[offset + 2] = FLOAT_BYTES[5];
+        destination[offset + 3] = FLOAT_BYTES[4];
+        destination[offset + 4] = FLOAT_BYTES[3];
+        destination[offset + 5] = FLOAT_BYTES[2];
+        destination[offset + 6] = FLOAT_BYTES[1];
+        destination[offset + 7] = FLOAT_BYTES[0];
+        return 8;
+      }
+    : (destination: Uint8Array, offset: number, value: number) => {
+        FLOAT[0] = value;
+        destination[offset] = FLOAT_BYTES[0];
+        destination[offset + 1] = FLOAT_BYTES[1];
+        destination[offset + 2] = FLOAT_BYTES[2];
+        destination[offset + 3] = FLOAT_BYTES[3];
+        destination[offset + 4] = FLOAT_BYTES[4];
+        destination[offset + 5] = FLOAT_BYTES[5];
+        destination[offset + 6] = FLOAT_BYTES[6];
+        destination[offset + 7] = FLOAT_BYTES[7];
+        return 8;
+      }
 };