bson 6.4.0 → 6.6.0

package/bson.d.ts

@@ -24,6 +24,8 @@ export declare 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;
     buffer: Uint8Array;
@@ -138,14 +140,29 @@ declare namespace BSON {
         BSONError,
         BSONVersionError,
         BSONRuntimeError,
+        BSONOffsetError,
         BSONType,
         EJSON,
+        onDemand,
+        OnDemand,
         Document,
         CalculateObjectSizeOptions
     }
 }
 export { BSON }
 
+/**
+ * @public
+ * @experimental
+ */
+declare type BSONElement = [
+type: number,
+nameOffset: number,
+nameLength: number,
+offset: number,
+length: number
+];
+
 /**
  * @public
  * @category Error
@@ -172,6 +189,23 @@ export declare class BSONError extends Error {
     static isBSONError(value: unknown): value is BSONError;
 }
 
+/**
+ * @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 declare class BSONOffsetError extends BSONError {
+    get name(): 'BSONOffsetError';
+    offset: number;
+    constructor(message: string, offset: number, options?: {
+        cause?: unknown;
+    });
+}
+
 /**
  * A class representation of the BSON RegExp type.
  * @public
@@ -295,6 +329,48 @@ export declare class BSONVersionError extends BSONError {
     constructor();
 }
 
+/**
+ * @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.
+ */
+declare 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;
+    /** Create empty space of size, use pooled memory when available */
+    allocateUnsafe: (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 lowercase hex string from bytes */
+    toHex: (buffer: Uint8Array) => string;
+    /** Create a string from utf8 code units, fatal=true will throw an error if UTF-8 bytes are invalid, fatal=false will insert replacement characters */
+    toUTF8: (buffer: Uint8Array, start: number, end: number, fatal: boolean) => 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;
+};
+
+/* Excluded declaration from this release type: ByteUtils */
+
 /**
  * Calculate the bson size for a passed in Javascript object.
  *
@@ -982,6 +1058,36 @@ export declare interface MinKeyExtended {
     $minKey: 1;
 }
 
+/**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+declare 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.
+ *
+ * @experimental
+ * @public
+ */
+declare const NumberUtils: NumberUtils;
+
 /**
  * A class representation of the BSON ObjectId type.
  * @public
@@ -1106,6 +1212,25 @@ export declare interface ObjectIdLike {
     toHexString(): string;
 }
 
+/**
+ * @experimental
+ * @public
+ *
+ * A new set of BSON APIs that are currently experimental and not intended for production use.
+ */
+export declare type OnDemand = {
+    parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+    BSONElement: BSONElement;
+    ByteUtils: ByteUtils;
+    NumberUtils: NumberUtils;
+};
+
+/**
+ * @experimental
+ * @public
+ */
+export declare const onDemand: OnDemand;
+
 /**
  * Parse an Extended JSON string, constructing the JavaScript value or object described by that
  * string.

package/lib/bson.bundle.js

@@ -127,6 +127,15 @@ class BSONRuntimeError extends BSONError {
         super(message);
     }
 }
+class BSONOffsetError extends BSONError {
+    get name() {
+        return 'BSONOffsetError';
+    }
+    constructor(message, offset, options) {
+        super(`${message}. offset: ${offset}`, options);
+        this.offset = offset;
+    }
+}
 
 const FIRST_BIT = 0x80;
 const FIRST_TWO_BITS = 0xc0;
@@ -525,16 +534,16 @@ class Binary extends BSONValue {
         return this.position;
     }
     toJSON() {
-        return ByteUtils.toBase64(this.buffer);
+        return ByteUtils.toBase64(this.buffer.subarray(0, this.position));
     }
     toString(encoding) {
         if (encoding === 'hex')
-            return ByteUtils.toHex(this.buffer);
+            return ByteUtils.toHex(this.buffer.subarray(0, this.position));
         if (encoding === 'base64')
-            return ByteUtils.toBase64(this.buffer);
+            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);
     }
     toExtendedJSON(options) {
         options = options || {};
@@ -608,6 +617,7 @@ Binary.SUBTYPE_UUID = 4;
 Binary.SUBTYPE_MD5 = 5;
 Binary.SUBTYPE_ENCRYPTED = 6;
 Binary.SUBTYPE_COLUMN = 7;
+Binary.SUBTYPE_SENSITIVE = 8;
 Binary.SUBTYPE_USER_DEFINED = 128;
 const UUID_BYTE_LENGTH = 16;
 const UUID_WITHOUT_DASHES = /^[0-9A-F]{32}$/i;
@@ -2126,7 +2136,18 @@ class MinKey extends BSONValue {
 
 const FLOAT = new Float64Array(1);
 const FLOAT_BYTES = new Uint8Array(FLOAT.buffer, 0, 8);
+FLOAT[0] = -1;
+const isBigEndian = FLOAT_BYTES[7] === 0;
 const NumberUtils = {
+    getNonnegativeInt32LE(source, offset) {
+        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));
+    },
     getInt32LE(source, offset) {
         return (source[offset] |
             (source[offset + 1] << 8) |
@@ -2150,17 +2171,29 @@ const NumberUtils = {
         const hi = NumberUtils.getUint32LE(source, offset + 4);
         return (BigInt(hi) << BigInt(32)) + BigInt(lo);
     },
-    getFloat64LE(source, offset) {
-        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, offset) => {
+            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, offset) => {
+            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];
+        },
     setInt32BE(destination, offset, value) {
         destination[offset + 3] = value;
         value >>>= 8;
@@ -2201,18 +2234,31 @@ const NumberUtils = {
         destination[offset + 7] = hi;
         return 8;
     },
-    setFloat64LE(destination, offset, value) {
-        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, offset, value) => {
+            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, offset, value) => {
+            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;
+        }
 };
 
 const checkForHexRegExp = new RegExp('^[0-9a-fA-F]{24}$');
@@ -4090,6 +4136,113 @@ EJSON.serialize = EJSONserialize;
 EJSON.deserialize = EJSONdeserialize;
 Object.freeze(EJSON);
 
+function getSize(source, offset) {
+    try {
+        return NumberUtils.getNonnegativeInt32LE(source, offset);
+    }
+    catch (cause) {
+        throw new BSONOffsetError('BSON size cannot be negative', offset, { cause });
+    }
+}
+function findNull(bytes, offset) {
+    let nullTerminatorOffset = offset;
+    for (; bytes[nullTerminatorOffset] !== 0x00; nullTerminatorOffset++)
+        ;
+    if (nullTerminatorOffset === bytes.length - 1) {
+        throw new BSONOffsetError('Null terminator not found', offset);
+    }
+    return nullTerminatorOffset;
+}
+function parseToElements(bytes, startOffset = 0) {
+    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 = [];
+    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;
+        if (type === 1 ||
+            type === 18 ||
+            type === 9 ||
+            type === 17) {
+            length = 8;
+        }
+        else if (type === 16) {
+            length = 4;
+        }
+        else if (type === 7) {
+            length = 12;
+        }
+        else if (type === 19) {
+            length = 16;
+        }
+        else if (type === 8) {
+            length = 1;
+        }
+        else if (type === 10 ||
+            type === 6 ||
+            type === 127 ||
+            type === 255) {
+            length = 0;
+        }
+        else if (type === 11) {
+            length = findNull(bytes, findNull(bytes, offset) + 1) + 1 - offset;
+        }
+        else if (type === 3 ||
+            type === 4 ||
+            type === 15) {
+            length = getSize(bytes, offset);
+        }
+        else if (type === 2 ||
+            type === 5 ||
+            type === 12 ||
+            type === 13 ||
+            type === 14) {
+            length = getSize(bytes, offset) + 4;
+            if (type === 5) {
+                length += 1;
+            }
+            if (type === 12) {
+                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;
+}
+
+const onDemand = Object.create(null);
+onDemand.parseToElements = parseToElements;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
+Object.freeze(onDemand);
+
 const MAXSIZE = 1024 * 1024 * 17;
 let buffer = ByteUtils.allocate(MAXSIZE);
 function setInternalBufferSize(size) {
@@ -4144,6 +4297,7 @@ function deserializeStream(data, startIndex, numberOfDocuments, documents, docSt
 var bson = /*#__PURE__*/Object.freeze({
 __proto__: null,
 BSONError: BSONError,
+BSONOffsetError: BSONOffsetError,
 BSONRegExp: BSONRegExp,
 BSONRuntimeError: BSONRuntimeError,
 BSONSymbol: BSONSymbol,
@@ -4166,6 +4320,7 @@ UUID: UUID,
 calculateObjectSize: calculateObjectSize,
 deserialize: deserialize,
 deserializeStream: deserializeStream,
+onDemand: onDemand,
 serialize: serialize,
 serializeWithBufferAndIndex: serializeWithBufferAndIndex,
 setInternalBufferSize: setInternalBufferSize
@@ -4173,6 +4328,7 @@ setInternalBufferSize: setInternalBufferSize
 
 exports.BSON = bson;
 exports.BSONError = BSONError;
+exports.BSONOffsetError = BSONOffsetError;
 exports.BSONRegExp = BSONRegExp;
 exports.BSONRuntimeError = BSONRuntimeError;
 exports.BSONSymbol = BSONSymbol;
@@ -4195,6 +4351,7 @@ exports.UUID = UUID;
 exports.calculateObjectSize = calculateObjectSize;
 exports.deserialize = deserialize;
 exports.deserializeStream = deserializeStream;
+exports.onDemand = onDemand;
 exports.serialize = serialize;
 exports.serializeWithBufferAndIndex = serializeWithBufferAndIndex;
 exports.setInternalBufferSize = setInternalBufferSize;