bson 6.6.0 → 6.8.0

package/README.md

@@ -11,6 +11,33 @@ You can learn more about it in [the specification](http://bsonspec.org).
 - [Documentation](#documentation)
 - [FAQ](#faq)
 
+
+### Release Integrity
+
+Releases are created automatically and signed using the [Node team's GPG key](https://pgp.mongodb.com/node-driver.asc). This applies to the git tag as well as all release packages provided as part of a GitHub release. To verify the provided packages, download the key and import it using gpg:
+
+```shell
+gpg --import node-driver.asc
+```
+
+The GitHub release contains a detached signature file for the NPM package (named
+`bson-X.Y.Z.tgz.sig`).
+
+The following command returns the link npm package. 
+```shell
+npm view bson@vX.Y.Z dist.tarball 
+```
+
+Using the result of the above command, a `curl` command can return the official npm package for the release.
+
+To verify the integrity of the downloaded package, run the following command:
+```shell
+gpg --verify bson-X.Y.Z.tgz.sig bson-X.Y.Z.tgz
+```
+
+>[!Note]
+No verification is done when using npm to install the package. The contents of the Github tarball and npm's tarball are identical.
+
 ## Bugs / Feature Requests
 
 Think you've found a bug? Want to see a new feature in `bson`? Please open a case in our issue management tool, JIRA:

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.
      *
@@ -732,18 +760,26 @@ export declare class Long extends BSONValue {
     unsigned: boolean;
     /**
      * Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers.
-     *  See the from* functions below for more convenient ways of constructing Longs.
-     *
-     * Acceptable signatures are:
-     * - Long(low, high, unsigned?)
-     * - Long(bigint, unsigned?)
-     * - Long(string, unsigned?)
      *
      * @param low - The low (signed) 32 bits of the long
      * @param high - The high (signed) 32 bits of the long
      * @param unsigned - Whether unsigned or not, defaults to signed
      */
-    constructor(low?: number | bigint | string, high?: number | boolean, unsigned?: boolean);
+    constructor(low: number, high?: number, unsigned?: boolean);
+    /**
+     * Constructs a 64 bit two's-complement integer, given a bigint representation.
+     *
+     * @param value - BigInt representation of the long value
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     */
+    constructor(value: bigint, unsigned?: boolean);
+    /**
+     * Constructs a 64 bit two's-complement integer, given a string representation.
+     *
+     * @param value - String representation of the long value
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     */
+    constructor(value: string, unsigned?: boolean);
     static TWO_PWR_24: Long;
     /** Maximum unsigned value. */
     static MAX_UNSIGNED_VALUE: Long;
@@ -791,8 +827,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;
@@ -861,19 +856,18 @@ class Long extends BSONValue {
     get __isLong__() {
         return true;
     }
-    constructor(low = 0, high, unsigned) {
+    constructor(lowOrValue = 0, highOrUnsigned, unsigned) {
         super();
-        if (typeof low === 'bigint') {
-            Object.assign(this, Long.fromBigInt(low, !!high));
-        }
-        else if (typeof low === 'string') {
-            Object.assign(this, Long.fromString(low, !!high));
-        }
-        else {
-            this.low = low | 0;
-            this.high = high | 0;
-            this.unsigned = !!unsigned;
-        }
+        const unsignedBool = typeof highOrUnsigned === 'boolean' ? highOrUnsigned : Boolean(unsigned);
+        const high = typeof highOrUnsigned === 'number' ? highOrUnsigned : 0;
+        const res = typeof lowOrValue === 'string'
+            ? Long.fromString(lowOrValue, unsignedBool)
+            : typeof lowOrValue === 'bigint'
+                ? Long.fromBigInt(lowOrValue, unsignedBool)
+                : { low: lowOrValue | 0, high: high | 0, unsigned: unsignedBool };
+        this.low = res.low;
+        this.high = res.high;
+        this.unsigned = res.unsigned;
     }
     static fromBits(lowBits, highBits, unsigned) {
         return new Long(lowBits, highBits, unsigned);
@@ -925,27 +919,20 @@ class Long extends BSONValue {
         return Long.fromBits(value % TWO_PWR_32_DBL | 0, (value / TWO_PWR_32_DBL) | 0, unsigned);
     }
     static fromBigInt(value, unsigned) {
-        return Long.fromString(value.toString(), unsigned);
+        const FROM_BIGINT_BIT_MASK = BigInt(0xffffffff);
+        const FROM_BIGINT_BIT_SHIFT = BigInt(32);
+        return new Long(Number(value & FROM_BIGINT_BIT_MASK), Number((value >> FROM_BIGINT_BIT_SHIFT) & FROM_BIGINT_BIT_MASK), 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 +950,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 +2066,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 +2129,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 +3233,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++)