bson 6.5.0 → 6.7.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.
  *
@@ -555,6 +601,20 @@ export declare class Double extends BSONValue {
      * @param value - the number we want to represent as a double.
      */
     constructor(value: number);
+    /**
+     * Attempt to create an double type from string.
+     *
+     * This method will throw a BSONError on any string input that is not representable as a IEEE-754 64-bit double.
+     * Notably, this method will also throw on the following string formats:
+     * - Strings in non-decimal and non-exponential formats (binary, hex, or octal digits)
+     * - Strings with characters other than numeric, floating point, or leading sign characters (Note: 'Infinity', '-Infinity', and 'NaN' input strings are still allowed)
+     * - Strings with leading and/or trailing whitespace
+     *
+     * Strings with leading zeros, however, are also allowed
+     *
+     * @param value - the string we want to represent as a double.
+     */
+    static fromString(value: string): Double;
     /**
      * Access the number value.
      *
@@ -631,6 +691,20 @@ export declare class Int32 extends BSONValue {
      * @param value - the number we want to represent as an int32.
      */
     constructor(value: number | string);
+    /**
+     * Attempt to create an Int32 type from string.
+     *
+     * This method will throw a BSONError on any string input that is not representable as an Int32.
+     * Notably, this method will also throw on the following string formats:
+     * - Strings in non-decimal formats (exponent notation, binary, hex, or octal digits)
+     * - Strings non-numeric and non-leading sign characters (ex: '2.0', '24,000')
+     * - Strings with leading and/or trailing whitespace
+     *
+     * Strings with leading zeros, however, are allowed.
+     *
+     * @param value - the string we want to represent as an int32.
+     */
+    static fromString(value: string): Int32;
     /**
      * Access the number value.
      *
@@ -745,8 +819,113 @@ export declare class Long extends BSONValue {
      * @returns The corresponding Long value
      */
     static fromBigInt(value: bigint, unsigned?: boolean): Long;
+    /* Excluded from this release type: _fromString */
+    /**
+     * Returns a signed Long representation of the given string, written using radix 10.
+     * Will throw an error if the given text is not exactly representable as a Long.
+     * Throws an error if any of the following conditions are true:
+     * - the string contains invalid characters for the radix 10
+     * - the string contains whitespace
+     * - the value the string represents is too large or too small to be a Long
+     * Unlike Long.fromString, this method does not coerce '+/-Infinity' and 'NaN' to Long.Zero
+     * @param str - The textual representation of the Long
+     * @returns The corresponding Long value
+     */
+    static fromStringStrict(str: string): Long;
+    /**
+     * Returns a Long representation of the given string, written using the radix 10.
+     * Will throw an error if the given parameters are not exactly representable as a Long.
+     * Throws an error if any of the following conditions are true:
+     * - the string contains invalid characters for the given radix
+     * - the string contains whitespace
+     * - the value the string represents is too large or too small to be a Long
+     * Unlike Long.fromString, this method does not coerce '+/-Infinity' and 'NaN' to Long.Zero
+     * @param str - The textual representation of the Long
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     * @returns The corresponding Long value
+     */
+    static fromStringStrict(str: string, unsigned?: boolean): Long;
+    /**
+     * Returns a signed Long representation of the given string, written using the specified radix.
+     * Will throw an error if the given parameters are not exactly representable as a Long.
+     * Throws an error if any of the following conditions are true:
+     * - the string contains invalid characters for the given radix
+     * - the string contains whitespace
+     * - the value the string represents is too large or too small to be a Long
+     * Unlike Long.fromString, this method does not coerce '+/-Infinity' and 'NaN' to Long.Zero
+     * @param str - The textual representation of the Long
+     * @param radix - The radix in which the text is written (2-36), defaults to 10
+     * @returns The corresponding Long value
+     */
+    static fromStringStrict(str: string, radix?: boolean): Long;
     /**
      * Returns a Long representation of the given string, written using the specified radix.
+     * Will throw an error if the given parameters are not exactly representable as a Long.
+     * Throws an error if any of the following conditions are true:
+     * - the string contains invalid characters for the given radix
+     * - the string contains whitespace
+     * - the value the string represents is too large or too small to be a Long
+     * Unlike Long.fromString, this method does not coerce '+/-Infinity' and 'NaN' to Long.Zero
+     * @param str - The textual representation of the Long
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     * @param radix - The radix in which the text is written (2-36), defaults to 10
+     * @returns The corresponding Long value
+     */
+    static fromStringStrict(str: string, unsigned?: boolean, radix?: number): Long;
+    /**
+     * Returns a signed Long representation of the given string, written using radix 10.
+     *
+     * If the input string is empty, this function will throw a BSONError.
+     *
+     * If input string does not have valid signed 64-bit Long representation, this method will return a coerced value:
+     * - inputs that overflow 64-bit signed long will be coerced to Long.MAX_VALUE and Long.MIN_VALUE respectively
+     * - 'NaN' or '+/-Infinity' are coerced to Long.ZERO
+     * - other invalid characters sequences have variable behavior
+     *
+     * @param str - The textual representation of the Long
+     * @returns The corresponding Long value
+     */
+    static fromString(str: string): Long;
+    /**
+     * Returns a signed Long representation of the given string, written using the provided radix.
+     *
+     * If the input string is empty or a provided radix is not within (2-36), this function will throw a BSONError.
+     *
+     * If input parameters do not have valid signed 64-bit Long representation, this method will return a coerced value:
+     * - inputs that overflow 64-bit signed long will be coerced to Long.MAX_VALUE and Long.MIN_VALUE respectively
+     * - if the radix is less than 24, 'NaN' is coerced to Long.ZERO
+     * - if the radix is less than 35, '+/-Infinity' inputs are coerced to Long.ZERO
+     * - other invalid characters sequences have variable behavior
+     * @param str - The textual representation of the Long
+     * @param radix - The radix in which the text is written (2-36), defaults to 10
+     * @returns The corresponding Long value
+     */
+    static fromString(str: string, radix?: number): Long;
+    /**
+     * Returns a Long representation of the given string, written using radix 10.
+     *
+     * If the input string is empty, this function will throw a BSONError.
+     *
+     * If input parameters do not have a valid 64-bit Long representation, this method will return a coerced value:
+     * - inputs that overflow 64-bit long will be coerced to max or min (if signed) values
+     * - if the radix is less than 24, 'NaN' is coerced to Long.ZERO
+     * - if the radix is less than 35, '+/-Infinity' inputs are coerced to Long.ZERO
+     * - other invalid characters sequences have variable behavior
+     * @param str - The textual representation of the Long
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     * @returns The corresponding Long value
+     */
+    static fromString(str: string, unsigned?: boolean): Long;
+    /**
+     * Returns a Long representation of the given string, written using the specified radix.
+     *
+     * If the input string is empty or a provided radix is not within (2-36), this function will throw a BSONError.
+     *
+     * If input parameters do not have a valid 64-bit Long representation, this method will return a coerced value:
+     * - inputs that overflow 64-bit long will be coerced to max or min (if signed) values
+     * - if the radix is less than 24, 'NaN' is coerced to Long.ZERO
+     * - if the radix is less than 35, '+/-Infinity' inputs are coerced to Long.ZERO
+     * - other invalid characters sequences have variable behavior
      * @param str - The textual representation of the Long
      * @param unsigned - Whether unsigned or not, defaults to signed
      * @param radix - The radix in which the text is written (2-36), defaults to 10
@@ -1012,6 +1191,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 +1351,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,47 +131,26 @@ 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;
     }
 }
 
-const FIRST_BIT = 0x80;
-const FIRST_TWO_BITS = 0xc0;
-const FIRST_THREE_BITS = 0xe0;
-const FIRST_FOUR_BITS = 0xf0;
-const FIRST_FIVE_BITS = 0xf8;
-const TWO_BIT_CHAR = 0xc0;
-const THREE_BIT_CHAR = 0xe0;
-const FOUR_BIT_CHAR = 0xf0;
-const CONTINUING_CHAR = 0x80;
-function validateUtf8(bytes, start, end) {
-    let continuation = 0;
-    for (let i = start; i < end; i += 1) {
-        const byte = bytes[i];
-        if (continuation) {
-            if ((byte & FIRST_TWO_BITS) !== CONTINUING_CHAR) {
-                return false;
-            }
-            continuation -= 1;
+let TextDecoderFatal;
+let TextDecoderNonFatal;
+function parseUtf8(buffer, start, end, fatal) {
+    if (fatal) {
+        TextDecoderFatal ??= new TextDecoder('utf8', { fatal: true });
+        try {
+            return TextDecoderFatal.decode(buffer.subarray(start, end));
         }
-        else if (byte & FIRST_BIT) {
-            if ((byte & FIRST_THREE_BITS) === TWO_BIT_CHAR) {
-                continuation = 1;
-            }
-            else if ((byte & FIRST_FOUR_BITS) === THREE_BIT_CHAR) {
-                continuation = 2;
-            }
-            else if ((byte & FIRST_FIVE_BITS) === FOUR_BIT_CHAR) {
-                continuation = 3;
-            }
-            else {
-                return false;
-            }
+        catch (cause) {
+            throw new BSONError('Invalid UTF-8 string in BSON document', { cause });
         }
     }
-    return !continuation;
+    TextDecoderNonFatal ??= new TextDecoder('utf8', { fatal: false });
+    return TextDecoderNonFatal.decode(buffer.subarray(start, end));
 }
 
 function tryReadBasicLatin(uint8array, start, end) {
@@ -292,9 +271,7 @@ const nodeJsByteUtils = {
         if (fatal) {
             for (let i = 0; i < string.length; i++) {
                 if (string.charCodeAt(i) === 0xfffd) {
-                    if (!validateUtf8(buffer, start, end)) {
-                        throw new BSONError('Invalid UTF-8 string in BSON document');
-                    }
+                    parseUtf8(buffer, start, end, true);
                     break;
                 }
             }
@@ -418,15 +395,7 @@ const webByteUtils = {
         if (basicLatin != null) {
             return basicLatin;
         }
-        if (fatal) {
-            try {
-                return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
-            }
-            catch (cause) {
-                throw new BSONError('Invalid UTF-8 string in BSON document', { cause });
-            }
-        }
-        return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
+        return parseUtf8(uint8array, start, end, fatal);
     },
     utf8ByteLength(input) {
         return new TextEncoder().encode(input).byteLength;
@@ -534,16 +503,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 || {};
@@ -839,6 +808,32 @@ class DBRef extends BSONValue {
     }
 }
 
+function removeLeadingZerosAndExplicitPlus(str) {
+    if (str === '') {
+        return str;
+    }
+    let startIndex = 0;
+    const isNegative = str[startIndex] === '-';
+    const isExplicitlyPositive = str[startIndex] === '+';
+    if (isExplicitlyPositive || isNegative) {
+        startIndex += 1;
+    }
+    let foundInsignificantZero = false;
+    for (; startIndex < str.length && str[startIndex] === '0'; ++startIndex) {
+        foundInsignificantZero = true;
+    }
+    if (!foundInsignificantZero) {
+        return isExplicitlyPositive ? str.slice(1) : str;
+    }
+    return `${isNegative ? '-' : ''}${str.length === startIndex ? '0' : str.slice(startIndex)}`;
+}
+function validateStringCharacters(str, radix) {
+    radix = radix ?? 10;
+    const validCharacters = '0123456789abcdefghijklmnopqrstuvwxyz'.slice(0, radix);
+    const regex = new RegExp(`[^-+${validCharacters}]`, 'i');
+    return regex.test(str) ? false : str;
+}
+
 let wasm = undefined;
 try {
     wasm = new WebAssembly.Instance(new WebAssembly.Module(new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 13, 2, 96, 0, 1, 127, 96, 4, 127, 127, 127, 127, 1, 127, 3, 7, 6, 0, 1, 1, 1, 1, 1, 6, 6, 1, 127, 1, 65, 0, 11, 7, 50, 6, 3, 109, 117, 108, 0, 1, 5, 100, 105, 118, 95, 115, 0, 2, 5, 100, 105, 118, 95, 117, 0, 3, 5, 114, 101, 109, 95, 115, 0, 4, 5, 114, 101, 109, 95, 117, 0, 5, 8, 103, 101, 116, 95, 104, 105, 103, 104, 0, 0, 10, 191, 1, 6, 4, 0, 35, 0, 11, 36, 1, 1, 126, 32, 0, 173, 32, 1, 173, 66, 32, 134, 132, 32, 2, 173, 32, 3, 173, 66, 32, 134, 132, 126, 34, 4, 66, 32, 135, 167, 36, 0, 32, 4, 167, 11, 36, 1, 1, 126, 32, 0, 173, 32, 1, 173, 66, 32, 134, 132, 32, 2, 173, 32, 3, 173, 66, 32, 134, 132, 127, 34, 4, 66, 32, 135, 167, 36, 0, 32, 4, 167, 11, 36, 1, 1, 126, 32, 0, 173, 32, 1, 173, 66, 32, 134, 132, 32, 2, 173, 32, 3, 173, 66, 32, 134, 132, 128, 34, 4, 66, 32, 135, 167, 36, 0, 32, 4, 167, 11, 36, 1, 1, 126, 32, 0, 173, 32, 1, 173, 66, 32, 134, 132, 32, 2, 173, 32, 3, 173, 66, 32, 134, 132, 129, 34, 4, 66, 32, 135, 167, 36, 0, 32, 4, 167, 11, 36, 1, 1, 126, 32, 0, 173, 32, 1, 173, 66, 32, 134, 132, 32, 2, 173, 32, 3, 173, 66, 32, 134, 132, 130, 34, 4, 66, 32, 135, 167, 36, 0, 32, 4, 167, 11])), {}).exports;
@@ -927,25 +922,16 @@ class Long extends BSONValue {
     static fromBigInt(value, unsigned) {
         return Long.fromString(value.toString(), unsigned);
     }
-    static fromString(str, unsigned, radix) {
+    static _fromString(str, unsigned, radix) {
         if (str.length === 0)
             throw new BSONError('empty string');
-        if (str === 'NaN' || str === 'Infinity' || str === '+Infinity' || str === '-Infinity')
-            return Long.ZERO;
-        if (typeof unsigned === 'number') {
-            (radix = unsigned), (unsigned = false);
-        }
-        else {
-            unsigned = !!unsigned;
-        }
-        radix = radix || 10;
         if (radix < 2 || 36 < radix)
             throw new BSONError('radix');
         let p;
         if ((p = str.indexOf('-')) > 0)
             throw new BSONError('interior hyphen');
         else if (p === 0) {
-            return Long.fromString(str.substring(1), unsigned, radix).neg();
+            return Long._fromString(str.substring(1), unsigned, radix).neg();
         }
         const radixToPower = Long.fromNumber(Math.pow(radix, 8));
         let result = Long.ZERO;
@@ -963,6 +949,45 @@ class Long extends BSONValue {
         result.unsigned = unsigned;
         return result;
     }
+    static fromStringStrict(str, unsignedOrRadix, radix) {
+        let unsigned = false;
+        if (typeof unsignedOrRadix === 'number') {
+            (radix = unsignedOrRadix), (unsignedOrRadix = false);
+        }
+        else {
+            unsigned = !!unsignedOrRadix;
+        }
+        radix ??= 10;
+        if (str.trim() !== str) {
+            throw new BSONError(`Input: '${str}' contains leading and/or trailing whitespace`);
+        }
+        if (!validateStringCharacters(str, radix)) {
+            throw new BSONError(`Input: '${str}' contains invalid characters for radix: ${radix}`);
+        }
+        const cleanedStr = removeLeadingZerosAndExplicitPlus(str);
+        const result = Long._fromString(cleanedStr, unsigned, radix);
+        if (result.toString(radix).toLowerCase() !== cleanedStr.toLowerCase()) {
+            throw new BSONError(`Input: ${str} is not representable as ${result.unsigned ? 'an unsigned' : 'a signed'} 64-bit Long ${radix != null ? `with radix: ${radix}` : ''}`);
+        }
+        return result;
+    }
+    static fromString(str, unsignedOrRadix, radix) {
+        let unsigned = false;
+        if (typeof unsignedOrRadix === 'number') {
+            (radix = unsignedOrRadix), (unsignedOrRadix = false);
+        }
+        else {
+            unsigned = !!unsignedOrRadix;
+        }
+        radix ??= 10;
+        if (str === 'NaN' && radix < 24) {
+            return Long.ZERO;
+        }
+        else if ((str === 'Infinity' || str === '+Infinity' || str === '-Infinity') && radix < 35) {
+            return Long.ZERO;
+        }
+        return Long._fromString(str, unsigned, radix);
+    }
     static fromBytes(bytes, unsigned, le) {
         return le ? Long.fromBytesLE(bytes, unsigned) : Long.fromBytesBE(bytes, unsigned);
     }
@@ -2040,6 +2065,28 @@ class Double extends BSONValue {
         }
         this.value = +value;
     }
+    static fromString(value) {
+        const coercedValue = Number(value);
+        if (value === 'NaN')
+            return new Double(NaN);
+        if (value === 'Infinity')
+            return new Double(Infinity);
+        if (value === '-Infinity')
+            return new Double(-Infinity);
+        if (!Number.isFinite(coercedValue)) {
+            throw new BSONError(`Input: ${value} is not representable as a Double`);
+        }
+        if (value.trim() !== value) {
+            throw new BSONError(`Input: '${value}' contains whitespace`);
+        }
+        if (value === '') {
+            throw new BSONError(`Input is an empty string`);
+        }
+        if (/[^-0-9.+eE]/.test(value)) {
+            throw new BSONError(`Input: '${value}' is not in decimal or exponential notation`);
+        }
+        return new Double(coercedValue);
+    }
     valueOf() {
         return this.value;
     }
@@ -2081,6 +2128,23 @@ class Int32 extends BSONValue {
         }
         this.value = +value | 0;
     }
+    static fromString(value) {
+        const cleanedValue = removeLeadingZerosAndExplicitPlus(value);
+        const coercedValue = Number(value);
+        if (BSON_INT32_MAX < coercedValue) {
+            throw new BSONError(`Input: '${value}' is larger than the maximum value for Int32`);
+        }
+        else if (BSON_INT32_MIN > coercedValue) {
+            throw new BSONError(`Input: '${value}' is smaller than the minimum value for Int32`);
+        }
+        else if (!Number.isSafeInteger(coercedValue)) {
+            throw new BSONError(`Input: '${value}' is not a safe integer`);
+        }
+        else if (coercedValue.toString() !== cleanedValue) {
+            throw new BSONError(`Input: '${value}' is not a valid Int32 string`);
+        }
+        return new Int32(coercedValue);
+    }
     valueOf() {
         return this.value;
     }
@@ -2139,6 +2203,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) |
@@ -3159,12 +3232,7 @@ function deserializeObject(buffer, index, options, isArray = false) {
                 stringSize > buffer.length - index ||
                 buffer[index + stringSize - 1] !== 0)
                 throw new BSONError('bad string length in bson');
-            if (validation != null && validation.utf8) {
-                if (!validateUtf8(buffer, index, index + stringSize - 1)) {
-                    throw new BSONError('Invalid UTF-8 string in BSON document');
-                }
-            }
-            const namespace = ByteUtils.toUTF8(buffer, index, index + stringSize - 1, false);
+            const namespace = ByteUtils.toUTF8(buffer, index, index + stringSize - 1, shouldValidateKey);
             index = index + stringSize;
             const oidBuffer = ByteUtils.allocateUnsafe(12);
             for (let i = 0; i < 12; i++)
@@ -4128,13 +4196,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 +4213,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 +4239,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 +4257,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 +4298,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 +4356,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 +4387,7 @@ setInternalBufferSize: setInternalBufferSize
 
 exports.BSON = bson;
 exports.BSONError = BSONError;
+exports.BSONOffsetError = BSONOffsetError;
 exports.BSONRegExp = BSONRegExp;
 exports.BSONRuntimeError = BSONRuntimeError;
 exports.BSONSymbol = BSONSymbol;