bson 7.1.0 → 7.2.0

package/package.json

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

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';

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,
@@ -452,10 +469,13 @@ function parse(text: string, options?: EJSONOptions): any {
 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)[]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    | ((this: any, key: string, value: any) => any)
+    | EJSONSerializeOptions,
   space?: string | number,
-  options?: EJSONOptions
+  options?: EJSONSerializeOptions
 ): string {
   if (space != null && typeof space === 'object') {
     options = space;
@@ -481,7 +501,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 +513,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/parser/on_demand/index.ts

@@ -1,3 +1,5 @@
+import { ByteUtils } from '../../utils/byte_utils';
+import { NumberUtils } from '../../utils/number_utils';
 import { type BSONElement, parseToElements } from './parse_to_elements';
 /**
  * @experimental
@@ -9,6 +11,10 @@ export type OnDemand = {
   parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
   // Types
   BSONElement: BSONElement;
+
+  // Utils
+  ByteUtils: ByteUtils;
+  NumberUtils: NumberUtils;
 };
 
 /**
@@ -18,6 +24,8 @@ export type OnDemand = {
 const onDemand: OnDemand = Object.create(null);
 
 onDemand.parseToElements = parseToElements;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
 
 Object.freeze(onDemand);
 

package/src/utils/byte_utils.ts

@@ -21,6 +21,14 @@ export type ByteUtils = {
   compare: (buffer1: Uint8Array, buffer2: Uint8Array) => -1 | 0 | 1;
   /** Concatenating all the Uint8Arrays in new Uint8Array. */
   concat: (list: Uint8Array[]) => Uint8Array;
+  /** Copy bytes from source Uint8Array to target Uint8Array */
+  copy: (
+    source: Uint8Array,
+    target: Uint8Array,
+    targetStart?: number,
+    sourceStart?: number,
+    sourceEnd?: number
+  ) => number;
   /** Check if two Uint8Arrays are deep equal */
   equals: (a: Uint8Array, b: Uint8Array) => boolean;
   /** Create a Uint8Array from an array of numbers */

package/src/utils/node_byte_utils.ts

@@ -104,6 +104,18 @@ export const nodeJsByteUtils = {
     return Buffer.concat(list);
   },
 
+  copy(
+    source: Uint8Array,
+    target: Uint8Array,
+    targetStart?: number,
+    sourceStart?: number,
+    sourceEnd?: number
+  ): number {
+    return nodeJsByteUtils
+      .toLocalBufferType(source)
+      .copy(target, targetStart ?? 0, sourceStart ?? 0, sourceEnd ?? source.length);
+  },
+
   equals(a: Uint8Array, b: Uint8Array): boolean {
     return nodeJsByteUtils.toLocalBufferType(a).equals(b);
   },

package/src/utils/web_byte_utils.ts

@@ -155,6 +155,49 @@ export const webByteUtils = {
     return result;
   },
 
+  copy(
+    source: Uint8Array,
+    target: Uint8Array,
+    targetStart?: number,
+    sourceStart?: number,
+    sourceEnd?: number
+  ): number {
+    // validate and standardize passed-in sourceEnd
+    if (sourceEnd !== undefined && sourceEnd < 0) {
+      throw new RangeError(
+        `The value of "sourceEnd" is out of range. It must be >= 0. Received ${sourceEnd}`
+      );
+    }
+    sourceEnd = sourceEnd ?? source.length;
+
+    // validate and standardize passed-in sourceStart
+    if (sourceStart !== undefined && (sourceStart < 0 || sourceStart > sourceEnd)) {
+      throw new RangeError(
+        `The value of "sourceStart" is out of range. It must be >= 0 and <= ${sourceEnd}. Received ${sourceStart}`
+      );
+    }
+    sourceStart = sourceStart ?? 0;
+
+    // validate and standardize passed-in targetStart
+    if (targetStart !== undefined && targetStart < 0) {
+      throw new RangeError(
+        `The value of "targetStart" is out of range. It must be >= 0. Received ${targetStart}`
+      );
+    }
+    targetStart = targetStart ?? 0;
+
+    // figure out how many bytes we can copy
+    const srcSlice = source.subarray(sourceStart, sourceEnd);
+    const maxLen = Math.min(srcSlice.length, target.length - targetStart);
+    if (maxLen <= 0) {
+      return 0;
+    }
+
+    // perform the copy
+    target.set(srcSlice.subarray(0, maxLen), targetStart);
+    return maxLen;
+  },
+
   equals(uint8Array: Uint8Array, otherUint8Array: Uint8Array): boolean {
     if (uint8Array.byteLength !== otherUint8Array.byteLength) {
       return false;