bson 7.1.1 → 7.3.0

package/README.md

@@ -14,7 +14,7 @@ You can learn more about it in [the specification](http://bsonspec.org).
 
 ### 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:
+Releases are created automatically and signed using the [Node team's GPG key](https://pgp.mongodb.com/node-driver.asc). All release packages provided as part of a GitHub release are signed. To verify the provided packages, download the key and import it using gpg:
 
 ```shell
 gpg --import node-driver.asc
@@ -36,7 +36,13 @@ 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.
+No GPG verification is done when using npm to install the package. The contents of the GitHub tarball and npm's tarball are identical.
+
+Releases published to the npm registry also include a [provenance attestation](https://docs.npmjs.com/generating-provenance-statements), which cryptographically links the package to its source repository and build workflow. To verify provenance:
+
+```shell
+npm audit signatures
+```
 
 ## Bugs / Feature Requests
 

package/bson.d.ts

@@ -207,6 +207,9 @@ declare namespace BSON {
         Decimal128Extended,
         DoubleExtended,
         EJSONOptions,
+        EJSONOptionsBase,
+        EJSONSerializeOptions,
+        EJSONParseOptions,
         Int32Extended,
         LongExtended,
         MaxKeyExtended,
@@ -465,6 +468,8 @@ export declare 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 */
@@ -782,10 +787,13 @@ export declare const EJSON: {
  * @param ejson - The Extended JSON object to deserialize
  * @param options - Optional settings passed to the parse method
  */
-declare function EJSONdeserialize(ejson: Document, options?: EJSONOptions): any;
+declare function EJSONdeserialize(ejson: Document, options?: EJSONParseOptions): any;
 
 /** @public */
-export declare type EJSONOptions = {
+export declare type EJSONOptions = EJSONSerializeOptions & EJSONParseOptions;
+
+/** @public */
+export declare type EJSONOptionsBase = {
     /**
      * Output using the Extended JSON v1 spec
      * @defaultValue `false`
@@ -793,8 +801,13 @@ export declare 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 declare type EJSONParseOptions = EJSONOptionsBase & {
     /**
      * Enable native bigint support
      * @defaultValue `false`
@@ -808,7 +821,16 @@ export declare type EJSONOptions = {
  * @param value - The object to serialize
  * @param options - Optional settings passed to the `stringify` function
  */
-declare function EJSONserialize(value: any, options?: EJSONOptions): Document;
+declare function EJSONserialize(value: any, options?: EJSONSerializeOptions): Document;
+
+/** @public */
+export declare type EJSONSerializeOptions = EJSONOptionsBase & {
+    /**
+     * Omits undefined values from the output instead of converting them to null
+     * @defaultValue `false`
+     */
+    ignoreUndefined?: boolean;
+};
 
 declare type InspectFn = (x: unknown, options?: unknown) => string;
 
@@ -1294,7 +1316,7 @@ export declare interface LongExtended {
 
 /** @public */
 export declare type LongWithoutOverrides = new (low: unknown, high?: number | boolean, unsigned?: boolean) => {
-    [P in Exclude<keyof Long, TimestampOverrides>]: Long[P];
+    [P in TimestampKept]: Long[P];
 };
 
 /** @public */
@@ -1374,6 +1396,8 @@ export declare const NumberUtils: NumberUtils;
 export declare class ObjectId extends BSONValue {
     get _bsontype(): 'ObjectId';
     /* Excluded from this release type: index */
+    /* Excluded from this release type: PROCESS_UNIQUE */
+    /* Excluded from this release type: resetState */
     static cacheHexString: boolean;
     /* Excluded from this release type: buffer */
     /** To generate a new ObjectId, use ObjectId() with no argument. */
@@ -1519,7 +1543,7 @@ export declare const onDemand: OnDemand;
  * console.log(EJSON.parse(text));
  * ```
  */
-declare function parse(text: string, options?: EJSONOptions): any;
+declare function parse(text: string, options?: EJSONParseOptions): any;
 
 /**
  * Serialize a Javascript object.
@@ -1596,9 +1620,16 @@ export declare function setInternalBufferSize(size: number): void;
  *
  * // prints '{"int32":10}'
  * console.log(EJSON.stringify(doc));
+ *
+ * // prints '{"int32":{"$numberInt":"10"}}' with 2 space indentation
+ * console.log(EJSON.stringify(doc, { relaxed: false }, 2));
  * ```
  */
-declare function stringify(value: any, replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | EJSONOptions, space?: string | number, options?: EJSONOptions): string;
+declare function stringify(value: any, replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | null, space?: string | number, options?: EJSONSerializeOptions): string;
+
+declare function stringify(value: any, replacer?: (number | string)[] | ((this: any, key: string, value: any) => any) | null, options?: EJSONSerializeOptions): string;
+
+declare function stringify(value: any, options?: EJSONSerializeOptions, space?: string | number): string;
 
 /**
  * @public
@@ -1609,6 +1640,9 @@ declare function stringify(value: any, replacer?: (number | string)[] | ((this:
 export declare class Timestamp extends LongWithoutOverridesClass {
     get _bsontype(): 'Timestamp';
     get [bsonType](): 'Timestamp';
+    /**
+     * @deprecated Use `Long.MAX_UNSIGNED_VALUE` instead.
+     */
     static readonly MAX_VALUE: Long;
     /**
      * An incrementing ordinal for operations within a given second.
@@ -1636,9 +1670,15 @@ export declare class Timestamp extends LongWithoutOverridesClass {
     toJSON(): {
         $timestamp: string;
     };
-    /** Returns a Timestamp represented by the given (32-bit) integer value. */
+    /**
+     * Returns a Timestamp represented by the given (32-bit) integer value.
+     * @deprecated Stores `value` in the low 32 bits (increment), leaving t = 0. Use `new Timestamp({ t, i })` or `Timestamp.fromBits(lowBits, highBits)` for explicit construction.
+     */
     static fromInt(value: number): Timestamp;
-    /** Returns a Timestamp representing the given number value, provided that it is a finite number. Otherwise, zero is returned. */
+    /**
+     * Returns a Timestamp representing the given number value, provided that it is a finite number. Otherwise, zero is returned.
+     * @deprecated Splits `value` across (t, i) as a uint64; the result rarely matches user intent. Use `new Timestamp({ t, i })` or `Timestamp.fromBits(lowBits, highBits)` for explicit construction.
+     */
     static fromNumber(value: number): Timestamp;
     /**
      * Returns a Timestamp for the given high and low bits. Each is assumed to use 32 bits.
@@ -1657,6 +1697,98 @@ export declare class Timestamp extends LongWithoutOverridesClass {
     /* Excluded from this release type: toExtendedJSON */
     /* Excluded from this release type: fromExtendedJSON */
     inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    add: Long['add'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    subtract: Long['subtract'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    sub: Long['sub'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    multiply: Long['multiply'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    mul: Long['mul'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    divide: Long['divide'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    div: Long['div'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    modulo: Long['modulo'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    mod: Long['mod'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    rem: Long['rem'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
+    negate: Long['negate'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
+    neg: Long['neg'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    and: Long['and'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    or: Long['or'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    xor: Long['xor'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    not: Long['not'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shiftLeft: Long['shiftLeft'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shl: Long['shl'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shiftRight: Long['shiftRight'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shr: Long['shr'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shiftRightUnsigned: Long['shiftRightUnsigned'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shr_u: Long['shr_u'];
+    /** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
+    shru: Long['shru'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
+    toSigned: Long['toSigned'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (this is a no-op). */
+    toUnsigned: Long['toUnsigned'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always false). */
+    isNegative: Long['isNegative'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always true). */
+    isPositive: Long['isPositive'];
+    /** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always true). */
+    unsigned: Long['unsigned'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
+    toInt: Long['toInt'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
+    toNumber: Long['toNumber'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
+    toBytes: Long['toBytes'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
+    toBytesLE: Long['toBytesLE'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
+    toBytesBE: Long['toBytesBE'];
+    /** @deprecated Incompatible with Timestamp: returns a signed integer, but Timestamp is always unsigned. Use `.t` for seconds since the Unix epoch. */
+    getHighBits: Long['getHighBits'];
+    /** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch. */
+    getHighBitsUnsigned: Long['getHighBitsUnsigned'];
+    /** @deprecated Incompatible with Timestamp: returns a signed integer, but Timestamp is always unsigned. Use `.i` for the increment ordinal. */
+    getLowBits: Long['getLowBits'];
+    /** @deprecated Not applicable to Timestamp; use `.i` for the increment ordinal. */
+    getLowBitsUnsigned: Long['getLowBitsUnsigned'];
+    /** @deprecated Not applicable to Timestamp; use `.i` instead. */
+    low: Long['low'];
+    /** @deprecated Not applicable to Timestamp; use `.t` instead. */
+    high: Long['high'];
+    /** @deprecated Use .compare() for general comparison, or .equals(), .lessThan(), .greaterThan() for specific cases. */
+    comp: Long['comp'];
+    /** @deprecated Compare `.t` and `.i` against `0` explicitly. */
+    isZero: Long['isZero'];
+    /** @deprecated Compare `.t` and `.i` against `0` explicitly. */
+    eqz: Long['eqz'];
+    /** @deprecated Not applicable to Timestamp. Use the bsonType symbol or _bsontype === 'Timestamp' to identify a Timestamp. */
+    __isLong__: Long['__isLong__'];
+    /** @deprecated Not applicable to Timestamp. */
+    getNumBitsAbs: Long['getNumBitsAbs'];
+    /** @deprecated Not applicable to Timestamp; tests parity of the increment only. */
+    isEven: Long['isEven'];
+    /** @deprecated Not applicable to Timestamp; tests parity of the increment only. */
+    isOdd: Long['isOdd'];
 }
 
 /** @public */
@@ -1667,7 +1799,21 @@ export declare interface TimestampExtended {
     };
 }
 
-/** @public */
+/**
+ * @public
+ *
+ * Inherited `Long` members surfaced on `Timestamp`.
+ * When `Long` gains a new member: add it here if it should pass through, or
+ * add a `@deprecated declare` line on the `Timestamp` class if it should be
+ * surfaced as deprecated. Anything left unclassified is silently dropped from
+ * the public type — preventing accidental behavioral bleed-through.
+ */
+declare type TimestampKept = 'toBigInt' | 'toString' | 'compare' | 'equals' | 'eq' | 'notEquals' | 'neq' | 'ne' | 'lessThan' | 'lt' | 'lessThanOrEqual' | 'lte' | 'le' | 'greaterThan' | 'gt' | 'greaterThanOrEqual' | 'gte' | 'ge';
+
+/**
+ * @public
+ * @deprecated This type is no longer used internally and will be removed in a future version.
+ */
 export declare type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromExtendedJSON' | 'inspect' | typeof bsonType;
 
 /**