bson 6.6.0 → 6.7.0

package/bson.d.ts

@@ -601,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.
      *
@@ -677,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.
      *
@@ -791,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

package/lib/bson.bundle.js

@@ -137,41 +137,20 @@ class BSONOffsetError extends BSONError {
     }
 }
 
-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;
@@ -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;
     }
@@ -3168,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++)