bson 7.1.1 → 7.3.0

package/package.json

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

package/src/binary.ts

@@ -134,7 +134,7 @@ export class Binary extends BSONValue {
       throw new BSONError('Binary can only be constructed from Uint8Array or number[]');
     }
 
-    this.sub_type = subType ?? Binary.BSON_BINARY_SUBTYPE_DEFAULT;
+    this.sub_type = (subType ?? Binary.BSON_BINARY_SUBTYPE_DEFAULT) & 0xff;
 
     if (buffer == null) {
       // create an empty binary buffer
@@ -279,7 +279,7 @@ export class Binary extends BSONValue {
     }
 
     throw new BSONError(
-      `Binary sub_type "${this.sub_type}" is not supported for converting to UUID. Only "${Binary.SUBTYPE_UUID}" is currently supported.`
+      `Binary sub_type "${this.sub_type}" (${typeof this.sub_type}) is not supported for converting to UUID. Only 0x${Binary.SUBTYPE_UUID.toString(16).padStart(2, '0')} is currently supported.`
     );
   }
 

package/src/bson.ts

@@ -22,7 +22,12 @@ export type { CodeExtended } from './code';
 export type { DBRefLike } from './db_ref';
 export type { Decimal128Extended } from './decimal128';
 export type { DoubleExtended } from './double';
-export type { EJSONOptions } from './extended_json';
+export type {
+  EJSONOptions,
+  EJSONOptionsBase,
+  EJSONSerializeOptions,
+  EJSONParseOptions
+} from './extended_json';
 export type { Int32Extended } from './int_32';
 export type { LongExtended } from './long';
 export type { MaxKeyExtended } from './max_key';
@@ -112,7 +117,6 @@ export function serialize(object: Document, options: SerializeOptions = {}): Uin
     object,
     checkKeys,
     0,
-    0,
     serializeFunctions,
     ignoreUndefined,
     null
@@ -156,7 +160,6 @@ export function serializeWithBufferAndIndex(
     object,
     checkKeys,
     0,
-    0,
     serializeFunctions,
     ignoreUndefined,
     null

package/src/extended_json.ts

@@ -24,7 +24,7 @@ import { BSONSymbol } from './symbol';
 import { Timestamp } from './timestamp';
 
 /** @public */
-export type EJSONOptions = {
+export type EJSONOptionsBase = {
   /**
    * Output using the Extended JSON v1 spec
    * @defaultValue `false`
@@ -32,8 +32,22 @@ export type EJSONOptions = {
   legacy?: boolean;
   /**
    * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
-   * @defaultValue `false` */
+   * @defaultValue `false`
+   */
   relaxed?: boolean;
+};
+
+/** @public */
+export type EJSONSerializeOptions = EJSONOptionsBase & {
+  /**
+   * Omits undefined values from the output instead of converting them to null
+   * @defaultValue `false`
+   */
+  ignoreUndefined?: boolean;
+};
+
+/** @public */
+export type EJSONParseOptions = EJSONOptionsBase & {
   /**
    * Enable native bigint support
    * @defaultValue `false`
@@ -41,6 +55,9 @@ export type EJSONOptions = {
   useBigInt64?: boolean;
 };
 
+/** @public */
+export type EJSONOptions = EJSONSerializeOptions & EJSONParseOptions;
+
 /** @internal */
 type BSONType =
   | Binary
@@ -174,12 +191,12 @@ function deserializeValue(value: any, options: EJSONOptions = {}) {
   return value;
 }
 
-type EJSONSerializeOptions = EJSONOptions & {
+type EJSONSerializeInternalOptions = EJSONSerializeOptions & {
   seenObjects: { obj: unknown; propertyName: string }[];
 };
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function serializeArray(array: any[], options: EJSONSerializeOptions): any[] {
+function serializeArray(array: any[], options: EJSONSerializeInternalOptions): any[] {
   return array.map((v: unknown, index: number) => {
     options.seenObjects.push({ propertyName: `index ${index}`, obj: null });
     try {
@@ -197,7 +214,7 @@ function getISOString(date: Date) {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function serializeValue(value: any, options: EJSONSerializeOptions): any {
+function serializeValue(value: any, options: EJSONSerializeInternalOptions): any {
   if (value instanceof Map || isMap(value)) {
     const obj: Record<string, unknown> = Object.create(null);
     for (const [k, v] of value) {
@@ -242,7 +259,7 @@ function serializeValue(value: any, options: EJSONSerializeOptions): any {
 
   if (Array.isArray(value)) return serializeArray(value, options);
 
-  if (value === undefined) return null;
+  if (value === undefined) return options.ignoreUndefined ? undefined : null;
 
   if (value instanceof Date || isDate(value)) {
     const dateNum = value.getTime(),
@@ -326,7 +343,7 @@ const BSON_TYPE_MAPPINGS = {
 } as const;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function serializeDocument(doc: any, options: EJSONSerializeOptions) {
+function serializeDocument(doc: any, options: EJSONSerializeInternalOptions) {
   if (doc == null || typeof doc !== 'object') throw new BSONError('not an object instance');
 
   const bsontype: BSONType['_bsontype'] = doc._bsontype;
@@ -410,7 +427,7 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function parse(text: string, options?: EJSONOptions): any {
+function parse(text: string, options?: EJSONParseOptions): any {
   const ejsonOptions = {
     useBigInt64: options?.useBigInt64 ?? false,
     relaxed: options?.relaxed ?? true,
@@ -426,6 +443,7 @@ function parse(text: string, options?: EJSONOptions): any {
   });
 }
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Converts a BSON document to an Extended JSON string, optionally replacing values if a replacer
  * function is specified or optionally including only the specified properties if a replacer array
@@ -447,31 +465,54 @@ function parse(text: string, options?: EJSONOptions): any {
  *
  * // prints '{"int32":10}'
  * console.log(EJSON.stringify(doc));
+ *
+ * // prints '{"int32":{"$numberInt":"10"}}' with 2 space indentation
+ * console.log(EJSON.stringify(doc, { relaxed: false }, 2));
  * ```
  */
 function stringify(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   value: any,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | EJSONOptions,
+  replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | null,
   space?: string | number,
-  options?: EJSONOptions
+  options?: EJSONSerializeOptions
+): string;
+function stringify(
+  value: any,
+  replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | null,
+  options?: EJSONSerializeOptions
+): string;
+function stringify(value: any, options?: EJSONSerializeOptions, space?: string | number): string;
+function stringify(
+  value: any,
+  replacerOrOptions?:
+    | (number | string)[]
+    | ((this: any, key: string, value: any) => any)
+    | null
+    | EJSONSerializeOptions,
+  spaceOrOptions?: string | number | EJSONSerializeOptions,
+  options?: EJSONSerializeOptions
 ): string {
-  if (space != null && typeof space === 'object') {
-    options = space;
-    space = 0;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+
+  if (spaceOrOptions != null && typeof spaceOrOptions === 'object') {
+    options = spaceOrOptions;
+    spaceOrOptions = undefined;
   }
-  if (replacer != null && typeof replacer === 'object' && !Array.isArray(replacer)) {
-    options = replacer;
-    replacer = undefined;
-    space = 0;
+  if (
+    replacerOrOptions != null &&
+    typeof replacerOrOptions === 'object' &&
+    !Array.isArray(replacerOrOptions)
+  ) {
+    options = replacerOrOptions;
+    replacerOrOptions = undefined;
   }
+
   const serializeOptions = Object.assign({ relaxed: true, legacy: false }, options, {
     seenObjects: [{ propertyName: '(root)', obj: null }]
   });
 
   const doc = serializeValue(value, serializeOptions);
-  return JSON.stringify(doc, replacer as Parameters<JSON['stringify']>[1], space);
+  return JSON.stringify(doc, replacerOrOptions as Parameters<JSON['stringify']>[1], spaceOrOptions);
 }
 
 /**
@@ -481,7 +522,7 @@ function stringify(
  * @param options - Optional settings passed to the `stringify` function
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function EJSONserialize(value: any, options?: EJSONOptions): Document {
+function EJSONserialize(value: any, options?: EJSONSerializeOptions): Document {
   options = options || {};
   return JSON.parse(stringify(value, options));
 }
@@ -493,7 +534,7 @@ function EJSONserialize(value: any, options?: EJSONOptions): Document {
  * @param options - Optional settings passed to the parse method
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function EJSONdeserialize(ejson: Document, options?: EJSONOptions): any {
+function EJSONdeserialize(ejson: Document, options?: EJSONParseOptions): any {
   options = options || {};
   return parse(JSON.stringify(ejson), options);
 }

package/src/objectid.ts

@@ -4,9 +4,6 @@ import { type InspectFn, defaultInspect } from './parser/utils';
 import { ByteUtils } from './utils/byte_utils';
 import { NumberUtils } from './utils/number_utils';
 
-// Unique sequence for the current process (initialized on first use)
-let PROCESS_UNIQUE: Uint8Array | null = null;
-
 /** ObjectId hexString cache @internal */
 const __idCache = new WeakMap(); // TODO(NODE-6549): convert this to #__id private field when target updated to ES2022
 
@@ -33,7 +30,28 @@ export class ObjectId extends BSONValue {
   }
 
   /** @internal */
-  private static index = Math.floor(Math.random() * 0xffffff);
+  private static index = 0;
+
+  /** Unique sequence for the current process (initialized on first use)
+   * @internal
+   */
+  private static PROCESS_UNIQUE: Uint8Array | null = null;
+
+  /** @internal */
+  private static resetState = (): void => {
+    this.index = Math.floor(Math.random() * 0x1000000);
+    this.PROCESS_UNIQUE = ByteUtils.randomBytes(5);
+  };
+
+  static {
+    this.resetState();
+    // https://nodejs.org/api/v8.html#startup-snapshot-api
+    // @ts-expect-error Node.js types not present since this is an optional API
+    const { startupSnapshot } = globalThis?.process?.getBuiltinModule('v8') ?? {};
+    if (startupSnapshot?.isBuildingSnapshot()) {
+      startupSnapshot?.addDeserializeCallback(this.resetState);
+    }
+  }
 
   static cacheHexString: boolean;
 
@@ -178,7 +196,7 @@ export class ObjectId extends BSONValue {
    * @internal
    */
   private static getInc(): number {
-    return (ObjectId.index = (ObjectId.index + 1) % 0xffffff);
+    return (ObjectId.index = (ObjectId.index + 1) % 0x1000000);
   }
 
   /**
@@ -197,12 +215,8 @@ export class ObjectId extends BSONValue {
     // 4-byte timestamp
     NumberUtils.setInt32BE(buffer, 0, time);
 
-    // set PROCESS_UNIQUE if yet not initialized
-    if (PROCESS_UNIQUE === null) {
-      PROCESS_UNIQUE = ByteUtils.randomBytes(5);
-    }
-
     // 5-byte process unique
+    const PROCESS_UNIQUE = this.PROCESS_UNIQUE!;
     buffer[4] = PROCESS_UNIQUE[0];
     buffer[5] = PROCESS_UNIQUE[1];
     buffer[6] = PROCESS_UNIQUE[2];

package/src/parser/calculate_size.ts

@@ -10,43 +10,64 @@ export function internalCalculateObjectSize(
   serializeFunctions?: boolean,
   ignoreUndefined?: boolean
 ): number {
-  let totalLength = 4 + 1;
+  // Each stack entry carries its own ignoreUndefined so DBRef fields can force ignoreUndefined=true
+  // regardless of the caller's setting, matching the behavior of serializeInto.
+  const objectStack: Array<{ obj: Document; ignoreUndefined: boolean }> = [
+    { obj: object, ignoreUndefined: ignoreUndefined ?? false }
+  ];
+  let total = 0;
 
-  if (Array.isArray(object)) {
-    for (let i = 0; i < object.length; i++) {
-      totalLength += calculateElement(
-        i.toString(),
-        object[i],
-        serializeFunctions,
-        true,
-        ignoreUndefined
-      );
-    }
-  } else {
-    // If we have toBSON defined, override the current object
+  while (objectStack.length > 0) {
+    const { obj, ignoreUndefined: frameIgnoreUndefined } = objectStack.pop()!;
+    total += 5; // 4-byte size field + null terminator
 
-    if (typeof object?.toBSON === 'function') {
-      object = object.toBSON();
+    const isObjArray = Array.isArray(obj);
+    let target = obj;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (!isObjArray && typeof (obj as any)?.toBSON === 'function') {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      target = (obj as any).toBSON();
     }
 
-    // Calculate size
-    for (const key of Object.keys(object)) {
-      totalLength += calculateElement(key, object[key], serializeFunctions, false, ignoreUndefined);
+    if (isObjArray) {
+      const array = target as unknown[];
+      for (let i = 0; i < array.length; i++) {
+        total += calculateElementSize(
+          i.toString(),
+          array[i],
+          serializeFunctions,
+          true,
+          frameIgnoreUndefined,
+          objectStack
+        );
+      }
+    } else {
+      for (const key of Object.keys(target)) {
+        total += calculateElementSize(
+          key,
+          target[key],
+          serializeFunctions,
+          false,
+          frameIgnoreUndefined,
+          objectStack
+        );
+      }
     }
   }
 
-  return totalLength;
+  return total;
 }
 
 /** @internal */
-function calculateElement(
+function calculateElementSize(
   name: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   value: any,
   serializeFunctions = false,
   isArray = false,
-  ignoreUndefined = false
-) {
+  ignoreUndefined = false,
+  objectStack: Array<{ obj: Document; ignoreUndefined: boolean }>
+): number {
   // If we have toBSON defined, override the current object
   if (typeof value?.toBSON === 'function') {
     value = value.toBSON();
@@ -63,20 +84,19 @@ function calculateElement(
       ) {
         if (value >= constants.BSON_INT32_MIN && value <= constants.BSON_INT32_MAX) {
           // 32 bit
-          return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (4 + 1);
+          return ByteUtils.utf8ByteLength(name) + 1 + (4 + 1);
         } else {
-          return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (8 + 1);
+          return ByteUtils.utf8ByteLength(name) + 1 + (8 + 1);
         }
       } else {
         // 64 bit
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (8 + 1);
+        return ByteUtils.utf8ByteLength(name) + 1 + (8 + 1);
       }
     case 'undefined':
-      if (isArray || !ignoreUndefined)
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + 1;
+      if (isArray || !ignoreUndefined) return ByteUtils.utf8ByteLength(name) + 1 + 1;
       return 0;
     case 'boolean':
-      return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (1 + 1);
+      return ByteUtils.utf8ByteLength(name) + 1 + (1 + 1);
     case 'object':
       if (
         value != null &&
@@ -85,42 +105,42 @@ function calculateElement(
       ) {
         throw new BSONVersionError();
       } else if (value == null || value._bsontype === 'MinKey' || value._bsontype === 'MaxKey') {
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + 1;
+        return ByteUtils.utf8ByteLength(name) + 1 + 1;
       } else if (value._bsontype === 'ObjectId') {
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (12 + 1);
+        return ByteUtils.utf8ByteLength(name) + 1 + (12 + 1);
       } else if (value instanceof Date || isDate(value)) {
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (8 + 1);
+        return ByteUtils.utf8ByteLength(name) + 1 + (8 + 1);
       } else if (
         ArrayBuffer.isView(value) ||
         value instanceof ArrayBuffer ||
         isAnyArrayBuffer(value)
       ) {
-        return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (1 + 4 + 1) + value.byteLength
-        );
+        return ByteUtils.utf8ByteLength(name) + 1 + (1 + 4 + 1) + value.byteLength;
       } else if (
         value._bsontype === 'Long' ||
         value._bsontype === 'Double' ||
         value._bsontype === 'Timestamp'
       ) {
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (8 + 1);
+        return ByteUtils.utf8ByteLength(name) + 1 + (8 + 1);
       } else if (value._bsontype === 'Decimal128') {
-        return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (16 + 1);
+        return ByteUtils.utf8ByteLength(name) + 1 + (16 + 1);
       } else if (value._bsontype === 'Code') {
         // Calculate size depending on the availability of a scope
         if (value.scope != null && Object.keys(value.scope).length > 0) {
+          objectStack.push({ obj: value.scope, ignoreUndefined });
           return (
-            (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
+            ByteUtils.utf8ByteLength(name) +
+            1 +
             1 +
             4 +
             4 +
             ByteUtils.utf8ByteLength(value.code.toString()) +
-            1 +
-            internalCalculateObjectSize(value.scope, serializeFunctions, ignoreUndefined)
+            1
           );
         } else {
           return (
-            (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
+            ByteUtils.utf8ByteLength(name) +
+            1 +
             1 +
             4 +
             ByteUtils.utf8ByteLength(value.code.toString()) +
@@ -131,22 +151,13 @@ function calculateElement(
         const binary: Binary = value;
         // Check what kind of subtype we have
         if (binary.sub_type === Binary.SUBTYPE_BYTE_ARRAY) {
-          return (
-            (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
-            (binary.position + 1 + 4 + 1 + 4)
-          );
+          return ByteUtils.utf8ByteLength(name) + 1 + (binary.position + 1 + 4 + 1 + 4);
         } else {
-          return (
-            (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (binary.position + 1 + 4 + 1)
-          );
+          return ByteUtils.utf8ByteLength(name) + 1 + (binary.position + 1 + 4 + 1);
         }
       } else if (value._bsontype === 'Symbol') {
         return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
-          ByteUtils.utf8ByteLength(value.value) +
-          4 +
-          1 +
-          1
+          ByteUtils.utf8ByteLength(name) + 1 + ByteUtils.utf8ByteLength(value.value) + 4 + 1 + 1
         );
       } else if (value._bsontype === 'DBRef') {
         // Set up correct object for serialization
@@ -163,14 +174,13 @@ function calculateElement(
           ordered_values['$db'] = value.db;
         }
 
-        return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
-          1 +
-          internalCalculateObjectSize(ordered_values, serializeFunctions, ignoreUndefined)
-        );
+        // DBRef fields always use ignoreUndefined=true to match serializeInto behavior.
+        objectStack.push({ obj: ordered_values, ignoreUndefined: true });
+        return ByteUtils.utf8ByteLength(name) + 1 + 1;
       } else if (value instanceof RegExp || isRegExp(value)) {
         return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
+          ByteUtils.utf8ByteLength(name) +
+          1 +
           1 +
           ByteUtils.utf8ByteLength(value.source) +
           1 +
@@ -181,7 +191,8 @@ function calculateElement(
         );
       } else if (value._bsontype === 'BSONRegExp') {
         return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
+          ByteUtils.utf8ByteLength(name) +
+          1 +
           1 +
           ByteUtils.utf8ByteLength(value.pattern) +
           1 +
@@ -189,16 +200,14 @@ function calculateElement(
           1
         );
       } else {
-        return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
-          internalCalculateObjectSize(value, serializeFunctions, ignoreUndefined) +
-          1
-        );
+        objectStack.push({ obj: value, ignoreUndefined });
+        return ByteUtils.utf8ByteLength(name) + 1 + 1;
       }
     case 'function':
       if (serializeFunctions) {
         return (
-          (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) +
+          ByteUtils.utf8ByteLength(name) +
+          1 +
           1 +
           4 +
           ByteUtils.utf8ByteLength(value.toString()) +
@@ -207,12 +216,10 @@ function calculateElement(
       }
       return 0;
     case 'bigint':
-      return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (8 + 1);
+      return ByteUtils.utf8ByteLength(name) + 1 + (8 + 1);
     case 'symbol':
       return 0;
     default:
       throw new BSONError(`Unrecognized JS type: ${typeof value}`);
   }
-
-  return 0;
 }