bson 6.5.0 → 6.6.0

package/bson.d.ts

@@ -140,9 +140,11 @@ declare namespace BSON {
         BSONError,
         BSONVersionError,
         BSONRuntimeError,
+        BSONOffsetError,
         BSONType,
         EJSON,
         onDemand,
+        OnDemand,
         Document,
         CalculateObjectSizeOptions
     }
@@ -196,10 +198,12 @@ export declare class BSONError extends Error {
  * An error generated when BSON bytes are invalid.
  * Reports the offset the parser was able to reach before encountering the error.
  */
-declare class BSONOffsetError extends BSONError {
+export declare class BSONOffsetError extends BSONError {
     get name(): 'BSONOffsetError';
     offset: number;
-    constructor(message: string, offset: number);
+    constructor(message: string, offset: number, options?: {
+        cause?: unknown;
+    });
 }
 
 /**
@@ -325,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.
  *
@@ -1012,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
@@ -1142,12 +1218,11 @@ export declare interface ObjectIdLike {
  *
  * A new set of BSON APIs that are currently experimental and not intended for production use.
  */
-declare type OnDemand = {
-    BSONOffsetError: {
-        new (message: string, offset: number): BSONOffsetError;
-        isBSONError(value: unknown): value is BSONError;
-    };
+export declare type OnDemand = {
     parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+    BSONElement: BSONElement;
+    ByteUtils: ByteUtils;
+    NumberUtils: NumberUtils;
 };
 
 /**

package/lib/bson.bundle.js

@@ -131,8 +131,8 @@ class BSONOffsetError extends BSONError {
     get name() {
         return 'BSONOffsetError';
     }
-    constructor(message, offset) {
-        super(`${message}. offset: ${offset}`);
+    constructor(message, offset, options) {
+        super(`${message}. offset: ${offset}`, options);
         this.offset = offset;
     }
 }
@@ -534,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 || {};
@@ -2139,6 +2139,15 @@ 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) |
@@ -4128,13 +4137,12 @@ EJSON.deserialize = EJSONdeserialize;
 Object.freeze(EJSON);
 
 function getSize(source, offset) {
-    if (source[offset + 3] > 127) {
-        throw new BSONOffsetError('BSON size cannot be negative', offset);
+    try {
+        return NumberUtils.getNonnegativeInt32LE(source, offset);
+    }
+    catch (cause) {
+        throw new BSONOffsetError('BSON size cannot be negative', offset, { cause });
     }
-    return (source[offset] |
-        (source[offset + 1] << 8) |
-        (source[offset + 2] << 16) |
-        (source[offset + 3] << 24));
 }
 function findNull(bytes, offset) {
     let nullTerminatorOffset = offset;
@@ -4146,6 +4154,7 @@ function findNull(bytes, 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);
     }
@@ -4171,7 +4180,10 @@ function parseToElements(bytes, startOffset = 0) {
         const nameLength = findNull(bytes, offset) - nameOffset;
         offset += nameLength + 1;
         let length;
-        if (type === 1 || type === 18 || type === 9 || type === 17) {
+        if (type === 1 ||
+            type === 18 ||
+            type === 9 ||
+            type === 17) {
             length = 8;
         }
         else if (type === 16) {
@@ -4186,13 +4198,18 @@ function parseToElements(bytes, startOffset = 0) {
         else if (type === 8) {
             length = 1;
         }
-        else if (type === 10 || type === 6 || type === 127 || type === 255) {
+        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) {
+        else if (type === 3 ||
+            type === 4 ||
+            type === 15) {
             length = getSize(bytes, offset);
         }
         else if (type === 2 ||
@@ -4222,7 +4239,8 @@ function parseToElements(bytes, startOffset = 0) {
 
 const onDemand = Object.create(null);
 onDemand.parseToElements = parseToElements;
-onDemand.BSONOffsetError = BSONOffsetError;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
 Object.freeze(onDemand);
 
 const MAXSIZE = 1024 * 1024 * 17;
@@ -4279,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,
@@ -4309,6 +4328,7 @@ setInternalBufferSize: setInternalBufferSize
 
 exports.BSON = bson;
 exports.BSONError = BSONError;
+exports.BSONOffsetError = BSONOffsetError;
 exports.BSONRegExp = BSONRegExp;
 exports.BSONRuntimeError = BSONRuntimeError;
 exports.BSONSymbol = BSONSymbol;