bson 6.6.1 → 6.7.1

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "6.6.1",
+  "version": "6.7.1",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -27,40 +27,40 @@
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
-    "@microsoft/api-extractor": "^7.40.5",
-    "@octokit/core": "^5.1.0",
+    "@microsoft/api-extractor": "^7.43.1",
+    "@octokit/core": "^6.1.2",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-typescript": "^11.1.6",
-    "@types/chai": "^4.3.11",
+    "@types/chai": "^4.3.14",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^20.11.19",
+    "@types/node": "^20.12.7",
     "@types/sinon": "^17.0.3",
     "@types/sinon-chai": "^3.2.12",
-    "@typescript-eslint/eslint-plugin": "^7.0.2",
-    "@typescript-eslint/parser": "^7.0.2",
+    "@typescript-eslint/eslint-plugin": "^7.7.0",
+    "@typescript-eslint/parser": "^7.7.0",
     "benchmark": "^2.1.4",
-    "chai": "^4.3.10",
+    "chai": "^4.4.1",
     "chalk": "^5.3.0",
     "dbx-js-tools": "github:mongodb-js/dbx-js-tools",
-    "eslint": "^8.56.0",
+    "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-no-bigint-usage": "file:etc/eslint/no-bigint-usage",
     "eslint-plugin-prettier": "^5.1.3",
     "eslint-plugin-tsdoc": "^0.2.17",
-    "magic-string": "^0.30.7",
-    "mocha": "10.3.0",
+    "magic-string": "^0.30.10",
+    "mocha": "^10.4.0",
     "node-fetch": "^3.3.2",
     "nyc": "^15.1.0",
     "prettier": "^3.2.5",
-    "rollup": "^4.12.0",
+    "rollup": "^4.14.3",
     "sinon": "^17.0.1",
     "sinon-chai": "^3.7.0",
     "source-map-support": "^0.5.21",
     "standard-version": "^9.5.0",
-    "tar": "^6.2.0",
+    "tar": "^7.0.1",
     "ts-node": "^10.9.2",
-    "tsd": "^0.30.5",
-    "typescript": "^5.0.4",
+    "tsd": "^0.31.0",
+    "typescript": "5.3",
     "typescript-cached-transpile": "0.0.6",
     "uuid": "^9.0.1"
   },

package/src/constants.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export const BSON_MAJOR_VERSION = 6 as const;
+export const BSON_MAJOR_VERSION = 6;
 
 /** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;

package/src/double.ts

@@ -1,4 +1,5 @@
 import { BSONValue } from './bson_value';
+import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import { type InspectFn, defaultInspect } from './parser/utils';
 
@@ -32,6 +33,41 @@ export class Double extends BSONValue {
     this.value = +value;
   }
 
+  /**
+   * 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 {
+    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);
+  }
+
   /**
    * Access the number value.
    *

package/src/int_32.ts

@@ -1,6 +1,9 @@
 import { BSONValue } from './bson_value';
+import { BSON_INT32_MAX, BSON_INT32_MIN } from './constants';
+import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import { type InspectFn, defaultInspect } from './parser/utils';
+import { removeLeadingZerosAndExplicitPlus } from './utils/string_utils';
 
 /** @public */
 export interface Int32Extended {
@@ -32,6 +35,37 @@ export class Int32 extends BSONValue {
     this.value = +value | 0;
   }
 
+  /**
+   * 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 {
+    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) {
+      // catch all case
+      throw new BSONError(`Input: '${value}' is not a valid Int32 string`);
+    }
+    return new Int32(coercedValue);
+  }
+
   /**
    * Access the number value.
    *

package/src/long.ts

@@ -3,6 +3,7 @@ import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import { type InspectFn, defaultInspect } from './parser/utils';
 import type { Timestamp } from './timestamp';
+import * as StringUtils from './utils/string_utils';
 
 interface LongWASMHelpers {
   /** Gets the high bits of the last operation performed */
@@ -246,29 +247,24 @@ export class Long extends BSONValue {
   }
 
   /**
+   * @internal
    * Returns a Long representation of the given string, written using the specified radix.
+   * Throws an error if `throwsError` is set to true and any of the following conditions are true:
+   *  - the string contains invalid characters for the given radix
+   *  - the string contains whitespace
    * @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 fromString(str: string, unsigned?: boolean, radix?: number): Long {
+  private static _fromString(str: string, unsigned: boolean, radix: number): Long {
     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') {
-      // For goog.math.long compatibility
-      (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();
     }
 
     // Do several (8) digits each time through the loop, so as to
@@ -291,6 +287,167 @@ export class Long extends BSONValue {
     return result;
   }
 
+  /**
+   * 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;
+  static fromStringStrict(str: string, unsignedOrRadix?: boolean | number, radix?: number): Long {
+    let unsigned = false;
+    if (typeof unsignedOrRadix === 'number') {
+      // For goog.math.long compatibility
+      (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 (!StringUtils.validateStringCharacters(str, radix)) {
+      throw new BSONError(`Input: '${str}' contains invalid characters for radix: ${radix}`);
+    }
+
+    // remove leading zeros (for later string comparison and to make math faster)
+    const cleanedStr = StringUtils.removeLeadingZerosAndExplicitPlus(str);
+
+    // check roundtrip result
+    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;
+  }
+
+  /**
+   * 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
+   * @returns The corresponding Long value
+   */
+  static fromString(str: string, unsigned?: boolean, radix?: number): Long;
+  static fromString(str: string, unsignedOrRadix?: boolean | number, radix?: number): Long {
+    let unsigned = false;
+    if (typeof unsignedOrRadix === 'number') {
+      // For goog.math.long compatibility
+      (radix = unsignedOrRadix), (unsignedOrRadix = false);
+    } else {
+      unsigned = !!unsignedOrRadix;
+    }
+    radix ??= 10;
+    if (str === 'NaN' && radix < 24) {
+      // radix does not support n, so coerce to zero
+      return Long.ZERO;
+    } else if ((str === 'Infinity' || str === '+Infinity' || str === '-Infinity') && radix < 35) {
+      // radix does not support y, so coerce to zero
+      return Long.ZERO;
+    }
+    return Long._fromString(str, unsigned, radix);
+  }
+
   /**
    * Creates a Long from its byte representation.
    * @param bytes - Byte representation

package/src/parse_utf8.ts

@@ -0,0 +1,35 @@
+import { BSONError } from './error';
+
+type TextDecoder = {
+  readonly encoding: string;
+  readonly fatal: boolean;
+  readonly ignoreBOM: boolean;
+  decode(input?: Uint8Array): string;
+};
+type TextDecoderConstructor = {
+  new (label: 'utf8', options: { fatal: boolean; ignoreBOM?: boolean }): TextDecoder;
+};
+
+// parse utf8 globals
+declare const TextDecoder: TextDecoderConstructor;
+let TextDecoderFatal: TextDecoder;
+let TextDecoderNonFatal: TextDecoder;
+
+/**
+ * Determines if the passed in bytes are valid utf8
+ * @param bytes - An array of 8-bit bytes. Must be indexable and have length property
+ * @param start - The index to start validating
+ * @param end - The index to end validating
+ */
+export function parseUtf8(buffer: Uint8Array, start: number, end: number, fatal: boolean): string {
+  if (fatal) {
+    TextDecoderFatal ??= new TextDecoder('utf8', { fatal: true });
+    try {
+      return TextDecoderFatal.decode(buffer.subarray(start, end));
+    } catch (cause) {
+      throw new BSONError('Invalid UTF-8 string in BSON document', { cause });
+    }
+  }
+  TextDecoderNonFatal ??= new TextDecoder('utf8', { fatal: false });
+  return TextDecoderNonFatal.decode(buffer.subarray(start, end));
+}

package/src/parser/deserializer.ts

@@ -16,7 +16,6 @@ import { BSONSymbol } from '../symbol';
 import { Timestamp } from '../timestamp';
 import { ByteUtils } from '../utils/byte_utils';
 import { NumberUtils } from '../utils/number_utils';
-import { validateUtf8 } from '../validate_utf8';
 
 /** @public */
 export interface DeserializeOptions {
@@ -604,12 +603,7 @@ function deserializeObject(
       )
         throw new BSONError('bad string length in bson');
       // Namespace
-      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);
       // Update parse index position
       index = index + stringSize;
 

package/src/utils/node_byte_utils.ts

@@ -1,5 +1,5 @@
 import { BSONError } from '../error';
-import { validateUtf8 } from '../validate_utf8';
+import { parseUtf8 } from '../parse_utf8';
 import { tryReadBasicLatin, tryWriteBasicLatin } from './latin';
 
 type NodeJsEncoding = 'base64' | 'hex' | 'utf8' | 'binary';
@@ -136,12 +136,9 @@ export const nodeJsByteUtils = {
 
     const string = nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
     if (fatal) {
-      // TODO(NODE-4930): Insufficiently strict BSON UTF8 validation
       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;
         }
       }

package/src/utils/string_utils.ts

@@ -0,0 +1,44 @@
+/**
+ * @internal
+ * Removes leading zeros and explicit plus from textual representation of a number.
+ */
+export function removeLeadingZerosAndExplicitPlus(str: string): string {
+  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)}`;
+}
+
+/**
+ * @internal
+ * Returns false for an string that contains invalid characters for its radix, else returns the original string.
+ * @param str - The textual representation of the Long
+ * @param radix - The radix in which the text is written (2-36), defaults to 10
+ */
+export function validateStringCharacters(str: string, radix?: number): false | string {
+  radix = radix ?? 10;
+  const validCharacters = '0123456789abcdefghijklmnopqrstuvwxyz'.slice(0, radix);
+  // regex is case insensitive and checks that each character within the string is one of the validCharacters
+  const regex = new RegExp(`[^-+${validCharacters}]`, 'i');
+  return regex.test(str) ? false : str;
+}

package/src/utils/web_byte_utils.ts

@@ -1,5 +1,6 @@
 import { BSONError } from '../error';
 import { tryReadBasicLatin } from './latin';
+import { parseUtf8 } from '../parse_utf8';
 
 type TextDecoder = {
   readonly encoding: string;
@@ -179,14 +180,7 @@ export const webByteUtils = {
       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: string): number {

package/src/validate_utf8.ts

@@ -1,47 +0,0 @@
-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;
-
-/**
- * Determines if the passed in bytes are valid utf8
- * @param bytes - An array of 8-bit bytes. Must be indexable and have length property
- * @param start - The index to start validating
- * @param end - The index to end validating
- */
-export function validateUtf8(
-  bytes: { [index: number]: number },
-  start: number,
-  end: number
-): boolean {
-  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;
-    } 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;
-      }
-    }
-  }
-
-  return !continuation;
-}