bson 6.0.0 → 6.2.0

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"

package/src/binary.ts

@@ -1,4 +1,4 @@
-import { isAnyArrayBuffer, isUint8Array } from './parser/utils';
+import { type InspectFn, defaultInspect, isAnyArrayBuffer, isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
 import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW } from './constants';
@@ -263,14 +263,12 @@ export class Binary extends BSONValue {
     return type === BSON_BINARY_SUBTYPE_UUID_NEW ? new UUID(data) : new Binary(data, type);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
     const base64 = ByteUtils.toBase64(this.buffer.subarray(0, this.position));
-    return `Binary.createFromBase64("${base64}", ${this.sub_type})`;
+    const base64Arg = inspect(base64, options);
+    const subTypeArg = inspect(this.sub_type, options);
+    return `Binary.createFromBase64(${base64Arg}, ${subTypeArg})`;
   }
 }
 
@@ -463,13 +461,10 @@ export class UUID extends Binary {
    * Converts to a string representation of this Id.
    *
    * @returns return the 36 character hex string representation.
-   * @internal
+   *
    */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new UUID("${this.toHexString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new UUID(${inspect(this.toHexString(), options)})`;
   }
 }

package/src/bson_value.ts

@@ -1,4 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
+import { type InspectFn } from './parser/utils';
 
 /** @public */
 export abstract class BSONValue {
@@ -10,8 +11,20 @@ export abstract class BSONValue {
     return BSON_MAJOR_VERSION;
   }
 
-  /** @public */
-  public abstract inspect(): string;
+  [Symbol.for('nodejs.util.inspect.custom')](
+    depth?: number,
+    options?: unknown,
+    inspect?: InspectFn
+  ): string {
+    return this.inspect(depth, options, inspect);
+  }
+
+  /**
+   * @public
+   * Prints a human-readable string of BSON value information
+   * If invoked manually without node.js.inspect function, this will default to a modified JSON.stringify
+   */
+  public abstract inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 
   /** @internal */
   abstract toExtendedJSON(): unknown;

package/src/code.ts

@@ -1,5 +1,6 @@
 import type { Document } from './bson';
 import { BSONValue } from './bson_value';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface CodeExtended {
@@ -55,15 +56,14 @@ export class Code extends BSONValue {
     return new Code(doc.$code, doc.$scope);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    const codeJson = this.toJSON();
-    return `new Code(${JSON.stringify(String(codeJson.code))}${
-      codeJson.scope != null ? `, ${JSON.stringify(codeJson.scope)}` : ''
-    })`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    let parametersString = inspect(this.code, options);
+    const multiLineFn = parametersString.includes('\n');
+    if (this.scope != null) {
+      parametersString += `,${multiLineFn ? '\n' : ' '}${inspect(this.scope, options)}`;
+    }
+    const endingNewline = multiLineFn && this.scope === null;
+    return `new Code(${multiLineFn ? '\n' : ''}${parametersString}${endingNewline ? '\n' : ''})`;
   }
 }

package/src/db_ref.ts

@@ -2,6 +2,7 @@ import type { Document } from './bson';
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 import type { ObjectId } from './objectid';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface DBRefLike {
@@ -111,17 +112,18 @@ export class DBRef extends BSONValue {
     return new DBRef(doc.$ref, doc.$id, doc.$db, copy);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+
+    const args = [
+      inspect(this.namespace, options),
+      inspect(this.oid, options),
+      ...(this.db ? [inspect(this.db, options)] : []),
+      ...(Object.keys(this.fields).length > 0 ? [inspect(this.fields, options)] : [])
+    ];
+
+    args[1] = inspect === defaultInspect ? `new ObjectId(${args[1]})` : args[1];
 
-  inspect(): string {
-    // NOTE: if OID is an ObjectId class it will just print the oid string.
-    const oid =
-      this.oid === undefined || this.oid.toString === undefined ? this.oid : this.oid.toString();
-    return `new DBRef("${this.namespace}", new ObjectId("${String(oid)}")${
-      this.db ? `, "${this.db}"` : ''
-    })`;
+    return `new DBRef(${args.join(', ')})`;
   }
 }

package/src/decimal128.ts

@@ -1,7 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import { Long } from './long';
-import { isUint8Array } from './parser/utils';
+import { type InspectFn, defaultInspect, isUint8Array } from './parser/utils';
 import { ByteUtils } from './utils/byte_utils';
 
 const PARSE_STRING_REGEXP = /^(\+|-)?(\d+|(\d*\.\d*))?(E|e)?([-+])?(\d+)?$/;
@@ -158,6 +158,32 @@ export class Decimal128 extends BSONValue {
    * @param representation - a numeric string representation.
    */
   static fromString(representation: string): Decimal128 {
+    return Decimal128._fromString(representation, { allowRounding: false });
+  }
+
+  /**
+   * Create a Decimal128 instance from a string representation, allowing for rounding to 34
+   * significant digits
+   *
+   * @example Example of a number that will be rounded
+   * ```ts
+   * > let d = Decimal128.fromString('37.499999999999999196428571428571375')
+   * Uncaught:
+   * BSONError: "37.499999999999999196428571428571375" is not a valid Decimal128 string - inexact rounding
+   * at invalidErr (/home/wajames/js-bson/lib/bson.cjs:1402:11)
+   * at Decimal128.fromStringInternal (/home/wajames/js-bson/lib/bson.cjs:1633:25)
+   * at Decimal128.fromString (/home/wajames/js-bson/lib/bson.cjs:1424:27)
+   *
+   * > d = Decimal128.fromStringWithRounding('37.499999999999999196428571428571375')
+   * new Decimal128("37.49999999999999919642857142857138")
+   * ```
+   * @param representation - a numeric string representation.
+   */
+  static fromStringWithRounding(representation: string): Decimal128 {
+    return Decimal128._fromString(representation, { allowRounding: true });
+  }
+
+  private static _fromString(representation: string, options: { allowRounding: boolean }) {
     // Parse state tracking
     let isNegative = false;
     let sawSign = false;
@@ -351,59 +377,147 @@ export class Decimal128 extends BSONValue {
       exponent = exponent - 1;
     }
 
-    while (exponent < EXPONENT_MIN || nDigitsStored < nDigits) {
-      // Shift last digit. can only do this if < significant digits than # stored.
-      if (lastDigit === 0) {
-        if (significantDigits === 0) {
+    if (options.allowRounding) {
+      while (exponent < EXPONENT_MIN || nDigitsStored < nDigits) {
+        // Shift last digit. can only do this if < significant digits than # stored.
+        if (lastDigit === 0 && significantDigits < nDigitsStored) {
           exponent = EXPONENT_MIN;
+          significantDigits = 0;
           break;
         }
 
-        invalidErr(representation, 'exponent underflow');
+        if (nDigitsStored < nDigits) {
+          // adjust to match digits not stored
+          nDigits = nDigits - 1;
+        } else {
+          // adjust to round
+          lastDigit = lastDigit - 1;
+        }
+
+        if (exponent < EXPONENT_MAX) {
+          exponent = exponent + 1;
+        } else {
+          // Check if we have a zero then just hard clamp, otherwise fail
+          const digitsString = digits.join('');
+          if (digitsString.match(/^0+$/)) {
+            exponent = EXPONENT_MAX;
+            break;
+          }
+          invalidErr(representation, 'overflow');
+        }
       }
 
-      if (nDigitsStored < nDigits) {
-        if (
-          representation[nDigits - 1 + Number(sawSign) + Number(sawRadix)] !== '0' &&
-          significantDigits !== 0
-        ) {
-          invalidErr(representation, 'inexact rounding');
+      // Round
+      // We've normalized the exponent, but might still need to round.
+      if (lastDigit + 1 < significantDigits) {
+        let endOfString = nDigitsRead;
+
+        // If we have seen a radix point, 'string' is 1 longer than we have
+        // documented with ndigits_read, so inc the position of the first nonzero
+        // digit and the position that digits are read to.
+        if (sawRadix) {
+          firstNonZero = firstNonZero + 1;
+          endOfString = endOfString + 1;
         }
-        // adjust to match digits not stored
-        nDigits = nDigits - 1;
-      } else {
-        if (digits[lastDigit] !== 0) {
-          invalidErr(representation, 'inexact rounding');
+        // if negative, we need to increment again to account for - sign at start.
+        if (sawSign) {
+          firstNonZero = firstNonZero + 1;
+          endOfString = endOfString + 1;
         }
-        // adjust to round
-        lastDigit = lastDigit - 1;
-      }
 
-      if (exponent < EXPONENT_MAX) {
-        exponent = exponent + 1;
-      } else {
-        invalidErr(representation, 'overflow');
-      }
-    }
+        const roundDigit = parseInt(representation[firstNonZero + lastDigit + 1], 10);
+        let roundBit = 0;
+
+        if (roundDigit >= 5) {
+          roundBit = 1;
+          if (roundDigit === 5) {
+            roundBit = digits[lastDigit] % 2 === 1 ? 1 : 0;
+            for (let i = firstNonZero + lastDigit + 2; i < endOfString; i++) {
+              if (parseInt(representation[i], 10)) {
+                roundBit = 1;
+                break;
+              }
+            }
+          }
+        }
 
-    // Round
-    // We've normalized the exponent, but might still need to round.
-    if (lastDigit + 1 < significantDigits) {
-      // If we have seen a radix point, 'string' is 1 longer than we have
-      // documented with ndigits_read, so inc the position of the first nonzero
-      // digit and the position that digits are read to.
-      if (sawRadix) {
-        firstNonZero = firstNonZero + 1;
+        if (roundBit) {
+          let dIdx = lastDigit;
+
+          for (; dIdx >= 0; dIdx--) {
+            if (++digits[dIdx] > 9) {
+              digits[dIdx] = 0;
+
+              // overflowed most significant digit
+              if (dIdx === 0) {
+                if (exponent < EXPONENT_MAX) {
+                  exponent = exponent + 1;
+                  digits[dIdx] = 1;
+                } else {
+                  return new Decimal128(isNegative ? INF_NEGATIVE_BUFFER : INF_POSITIVE_BUFFER);
+                }
+              }
+            } else {
+              break;
+            }
+          }
+        }
       }
-      // if saw sign, we need to increment again to account for - or + sign at start.
-      if (sawSign) {
-        firstNonZero = firstNonZero + 1;
+    } else {
+      while (exponent < EXPONENT_MIN || nDigitsStored < nDigits) {
+        // Shift last digit. can only do this if < significant digits than # stored.
+        if (lastDigit === 0) {
+          if (significantDigits === 0) {
+            exponent = EXPONENT_MIN;
+            break;
+          }
+
+          invalidErr(representation, 'exponent underflow');
+        }
+
+        if (nDigitsStored < nDigits) {
+          if (
+            representation[nDigits - 1 + Number(sawSign) + Number(sawRadix)] !== '0' &&
+            significantDigits !== 0
+          ) {
+            invalidErr(representation, 'inexact rounding');
+          }
+          // adjust to match digits not stored
+          nDigits = nDigits - 1;
+        } else {
+          if (digits[lastDigit] !== 0) {
+            invalidErr(representation, 'inexact rounding');
+          }
+          // adjust to round
+          lastDigit = lastDigit - 1;
+        }
+
+        if (exponent < EXPONENT_MAX) {
+          exponent = exponent + 1;
+        } else {
+          invalidErr(representation, 'overflow');
+        }
       }
 
-      const roundDigit = parseInt(representation[firstNonZero + lastDigit + 1], 10);
+      // Round
+      // We've normalized the exponent, but might still need to round.
+      if (lastDigit + 1 < significantDigits) {
+        // If we have seen a radix point, 'string' is 1 longer than we have
+        // documented with ndigits_read, so inc the position of the first nonzero
+        // digit and the position that digits are read to.
+        if (sawRadix) {
+          firstNonZero = firstNonZero + 1;
+        }
+        // if saw sign, we need to increment again to account for - or + sign at start.
+        if (sawSign) {
+          firstNonZero = firstNonZero + 1;
+        }
+
+        const roundDigit = parseInt(representation[firstNonZero + lastDigit + 1], 10);
 
-      if (roundDigit !== 0) {
-        invalidErr(representation, 'inexact rounding');
+        if (roundDigit !== 0) {
+          invalidErr(representation, 'inexact rounding');
+        }
       }
     }
 
@@ -507,7 +621,6 @@ export class Decimal128 extends BSONValue {
     // Return the new Decimal128
     return new Decimal128(buffer);
   }
-
   /** Create a string representation of the raw Decimal128 value */
   toString(): string {
     // Note: bits in this routine are referred to starting at 0,
@@ -734,12 +847,9 @@ export class Decimal128 extends BSONValue {
     return Decimal128.fromString(doc.$numberDecimal);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Decimal128("${this.toString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    const d128string = inspect(this.toString(), options);
+    return `new Decimal128(${d128string})`;
   }
 }

package/src/double.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface DoubleExtended {
@@ -71,13 +72,8 @@ export class Double extends BSONValue {
     return options && options.relaxed ? doubleValue : new Double(doubleValue);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    const eJSON = this.toExtendedJSON() as DoubleExtended;
-    return `new Double(${eJSON.$numberDouble})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new Double(${inspect(this.value, options)})`;
   }
 }

package/src/error.ts

@@ -60,9 +60,7 @@ export class BSONVersionError extends BSONError {
   }
 
   constructor() {
-    super(
-      `Unsupported BSON version, bson types must be from bson ${BSON_MAJOR_VERSION}.0 or later`
-    );
+    super(`Unsupported BSON version, bson types must be from bson ${BSON_MAJOR_VERSION}.x.x`);
   }
 }
 

package/src/int_32.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface Int32Extended {
@@ -59,12 +60,8 @@ export class Int32 extends BSONValue {
     return options && options.relaxed ? parseInt(doc.$numberInt, 10) : new Int32(doc.$numberInt);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Int32(${this.valueOf()})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new Int32(${inspect(this.value, options)})`;
   }
 }

package/src/long.ts

@@ -1,6 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
+import { type InspectFn, defaultInspect } from './parser/utils';
 import type { Timestamp } from './timestamp';
 
 interface LongWASMHelpers {
@@ -1056,12 +1057,10 @@ export class Long extends BSONValue {
     return longResult;
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Long("${this.toString()}"${this.unsigned ? ', true' : ''})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    const longVal = inspect(this.toString(), options);
+    const unsignedVal = this.unsigned ? `, ${inspect(this.unsigned, options)}` : '';
+    return `new Long(${longVal}${unsignedVal})`;
   }
 }

package/src/max_key.ts

@@ -25,11 +25,6 @@ export class MaxKey extends BSONValue {
     return new MaxKey();
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
   inspect(): string {
     return 'new MaxKey()';
   }

package/src/min_key.ts

@@ -25,11 +25,6 @@ export class MinKey extends BSONValue {
     return new MinKey();
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
   inspect(): string {
     return 'new MinKey()';
   }

package/src/objectid.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
+import { type InspectFn, defaultInspect } from './parser/utils';
 import { BSONDataView, ByteUtils } from './utils/byte_utils';
 
 // Regular expression that checks for hex value
@@ -294,13 +295,9 @@ export class ObjectId extends BSONValue {
    * Converts to a string representation of this Id.
    *
    * @returns return the 24 character hex string representation.
-   * @internal
    */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new ObjectId("${this.toHexString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new ObjectId(${inspect(this.toHexString(), options)})`;
   }
 }

package/src/parser/serializer.ts

@@ -257,14 +257,18 @@ function serializeObjectId(buffer: Uint8Array, key: string, value: ObjectId, ind
   buffer[index++] = 0;
 
   // Write the objectId into the shared buffer
-  if (isUint8Array(value.id)) {
-    buffer.set(value.id.subarray(0, 12), index);
+  const idValue = value.id;
+
+  if (isUint8Array(idValue)) {
+    for (let i = 0; i < 12; i++) {
+      buffer[index++] = idValue[i];
+    }
   } else {
     throw new BSONError('object [' + JSON.stringify(value) + '] is not a valid ObjectId');
   }
 
   // Adjust index
-  return index + 12;
+  return index;
 }
 
 function serializeBuffer(buffer: Uint8Array, key: string, value: Uint8Array, index: number) {

package/src/parser/utils.ts

@@ -27,3 +27,30 @@ export function isMap(d: unknown): d is Map<unknown, unknown> {
 export function isDate(d: unknown): d is Date {
   return Object.prototype.toString.call(d) === '[object Date]';
 }
+
+export type InspectFn = (x: unknown, options?: unknown) => string;
+export function defaultInspect(x: unknown, _options?: unknown): string {
+  return JSON.stringify(x, (k: string, v: unknown) => {
+    if (typeof v === 'bigint') {
+      return { $numberLong: `${v}` };
+    } else if (isMap(v)) {
+      return Object.fromEntries(v);
+    }
+    return v;
+  });
+}
+
+/** @internal */
+type StylizeFunction = (x: string, style: string) => string;
+/** @internal */
+export function getStylizeFunction(options?: unknown): StylizeFunction | undefined {
+  const stylizeExists =
+    options != null &&
+    typeof options === 'object' &&
+    'stylize' in options &&
+    typeof options.stylize === 'function';
+
+  if (stylizeExists) {
+    return options.stylize as StylizeFunction;
+  }
+}

package/src/regexp.ts

@@ -1,6 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
+import { type InspectFn, defaultInspect, getStylizeFunction } from './parser/utils';
 
 function alphabetize(str: string): string {
   return str.split('').sort().join('');
@@ -103,12 +104,11 @@ export class BSONRegExp extends BSONValue {
     throw new BSONError(`Unexpected BSONRegExp EJSON object form: ${JSON.stringify(doc)}`);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new BSONRegExp(${JSON.stringify(this.pattern)}, ${JSON.stringify(this.options)})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    const stylize = getStylizeFunction(options) ?? (v => v);
+    inspect ??= defaultInspect;
+    const pattern = stylize(inspect(this.pattern), 'regexp');
+    const flags = stylize(inspect(this.options), 'regexp');
+    return `new BSONRegExp(${pattern}, ${flags})`;
   }
 }

package/src/symbol.ts

@@ -1,4 +1,5 @@
 import { BSONValue } from './bson_value';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface BSONSymbolExtended {
@@ -33,10 +34,6 @@ export class BSONSymbol extends BSONValue {
     return this.value;
   }
 
-  inspect(): string {
-    return `new BSONSymbol(${JSON.stringify(this.value)})`;
-  }
-
   toJSON(): string {
     return this.value;
   }
@@ -51,8 +48,8 @@ export class BSONSymbol extends BSONValue {
     return new BSONSymbol(doc.$symbol);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new BSONSymbol(${inspect(this.value, options)})`;
   }
 }