typeorm 0.3.29-dev.cc07c90 → 1.0.0-beta.1

package/driver/mongodb/bson.typings.d.ts

@@ -4,14 +4,17 @@
  * @category BSONType
  */
 export declare class Binary extends BSONValue {
-    get _bsontype(): "Binary";
+    get _bsontype(): 'Binary';
     /** Initial buffer default size */
     static readonly BUFFER_SIZE = 256;
     /** Default BSON type */
     static readonly SUBTYPE_DEFAULT = 0;
     /** Function BSON type */
     static readonly SUBTYPE_FUNCTION = 1;
-    /** Byte Array BSON type */
+    /**
+     * Legacy default BSON Binary type
+     * @deprecated BSON Binary subtype 2 is deprecated in the BSON specification
+     */
     static readonly SUBTYPE_BYTE_ARRAY = 2;
     /** Deprecated UUID BSON type @deprecated Please use SUBTYPE_UUID */
     static readonly SUBTYPE_UUID_OLD = 3;
@@ -23,23 +26,66 @@ export declare class Binary extends BSONValue {
     static readonly SUBTYPE_ENCRYPTED = 6;
     /** Column BSON type */
     static readonly SUBTYPE_COLUMN = 7;
+    /** Sensitive BSON type */
+    static readonly SUBTYPE_SENSITIVE = 8;
+    /** Vector BSON type */
+    static readonly SUBTYPE_VECTOR = 9;
     /** User BSON type */
     static readonly SUBTYPE_USER_DEFINED = 128;
+    /** datatype of a Binary Vector (subtype: 9) */
+    static readonly VECTOR_TYPE: Readonly<{
+        readonly Int8: 3;
+        readonly Float32: 39;
+        readonly PackedBit: 16;
+    }>;
+    /**
+     * The bytes of the Binary value.
+     *
+     * The format of a Binary value in BSON is defined as:
+     * ```txt
+     * binary	::= int32 subtype (byte*)
+     * ```
+     *
+     * This `buffer` is the "(byte*)" segment.
+     *
+     * Unless the value is subtype 2, then deserialize will read the first 4 bytes as an int32 and set this to the remaining bytes.
+     *
+     * ```txt
+     * binary	::= int32 unsigned_byte(2) int32 (byte*)
+     * ```
+     *
+     * @see https://bsonspec.org/spec.html
+     */
     buffer: Uint8Array;
+    /**
+     * The binary subtype.
+     *
+     * Current defined values are:
+     *
+     * - `unsigned_byte(0)` Generic binary subtype
+     * - `unsigned_byte(1)` Function
+     * - `unsigned_byte(2)` Binary (Deprecated)
+     * - `unsigned_byte(3)` UUID (Deprecated)
+     * - `unsigned_byte(4)` UUID
+     * - `unsigned_byte(5)` MD5
+     * - `unsigned_byte(6)` Encrypted BSON value
+     * - `unsigned_byte(7)` Compressed BSON column
+     * - `unsigned_byte(8)` Sensitive
+     * - `unsigned_byte(9)` Vector
+     * - `unsigned_byte(128)` - `unsigned_byte(255)` User defined
+     */
     sub_type: number;
+    /**
+     * The Binary's `buffer` can be larger than the Binary's content.
+     * This property is used to determine where the content ends in the buffer.
+     */
     position: number;
     /**
      * Create a new Binary instance.
-     *
-     * This constructor can accept a string as its first argument. In this case,
-     * this string will be encoded using ISO-8859-1, **not** using UTF-8.
-     * This is almost certainly not what you want. Use `new Binary(Buffer.from(string))`
-     * instead to convert the string to a Buffer using UTF-8 first.
-     *
      * @param buffer - a buffer object containing the binary data.
      * @param subType - the option binary type.
      */
-    constructor(buffer?: string | BinarySequence, subType?: number);
+    constructor(buffer?: BinarySequence, subType?: number);
     /**
      * Updates this binary with byte_value.
      *
@@ -47,36 +93,81 @@ export declare class Binary extends BSONValue {
      */
     put(byteValue: string | number | Uint8Array | number[]): void;
     /**
-     * Writes a buffer or string to the binary.
+     * Writes a buffer to the binary.
      *
      * @param sequence - a string or buffer to be written to the Binary BSON object.
      * @param offset - specify the binary of where to write the content.
      */
-    write(sequence: string | BinarySequence, offset: number): void;
+    write(sequence: BinarySequence, offset: number): void;
     /**
-     * Reads **length** bytes starting at **position**.
+     * Returns a view of **length** bytes starting at **position**.
      *
      * @param position - read from the given position in the Binary.
      * @param length - the number of bytes to read.
      */
-    read(position: number, length: number): BinarySequence;
-    /**
-     * Returns the value of this binary as a string.
-     * @param asRaw - Will skip converting to a string
-     * @remarks
-     * This is handy when calling this function conditionally for some key value pairs and not others
-     */
-    value(asRaw?: boolean): string | BinarySequence;
+    read(position: number, length: number): Uint8Array;
+    /** returns a view of the binary value as a Uint8Array */
+    value(): Uint8Array;
     /** the length of the binary sequence */
     length(): number;
     toJSON(): string;
-    toString(encoding?: "hex" | "base64" | "utf8" | "utf-8"): string;
+    toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string;
     toUUID(): UUID;
     /** Creates an Binary instance from a hex digit string */
     static createFromHexString(hex: string, subType?: number): Binary;
     /** Creates an Binary instance from a base64 string */
     static createFromBase64(base64: string, subType?: number): Binary;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
+    /**
+     * If this Binary represents a Int8 Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.Int8`),
+     * returns a copy of the bytes in a new Int8Array.
+     *
+     * If the Binary is not a Vector, or the datatype is not Int8, an error is thrown.
+     */
+    toInt8Array(): Int8Array;
+    /**
+     * If this Binary represents a Float32 Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.Float32`),
+     * returns a copy of the bytes in a new Float32Array.
+     *
+     * If the Binary is not a Vector, or the datatype is not Float32, an error is thrown.
+     */
+    toFloat32Array(): Float32Array;
+    /**
+     * If this Binary represents packed bit Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.PackedBit`),
+     * returns a copy of the bytes that are packed bits.
+     *
+     * Use `toBits` to get the unpacked bits.
+     *
+     * If the Binary is not a Vector, or the datatype is not PackedBit, an error is thrown.
+     */
+    toPackedBits(): Uint8Array;
+    /**
+     * If this Binary represents a Packed bit Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.PackedBit`),
+     * returns a copy of the bit unpacked into a new Int8Array.
+     *
+     * Use `toPackedBits` to get the bits still in packed form.
+     *
+     * If the Binary is not a Vector, or the datatype is not PackedBit, an error is thrown.
+     */
+    toBits(): Int8Array;
+    /**
+     * Constructs a Binary representing an Int8 Vector.
+     * @param array - The array to store as a view on the Binary class
+     */
+    static fromInt8Array(array: Int8Array): Binary;
+    /** Constructs a Binary representing an Float32 Vector. */
+    static fromFloat32Array(array: Float32Array): Binary;
+    /**
+     * Constructs a Binary representing a packed bit Vector.
+     *
+     * Use `fromBits` to pack an array of 1s and 0s.
+     */
+    static fromPackedBits(array: Uint8Array, padding?: number): Binary;
+    /**
+     * Constructs a Binary representing an Packed Bit Vector.
+     * @param array - The array of 1s and 0s to pack into the Binary instance
+     */
+    static fromBits(bits: ArrayLike<number>): Binary;
 }
 /** @public */
 export declare interface BinaryExtended {
@@ -92,17 +183,34 @@ export declare interface BinaryExtendedLegacy {
 }
 /** @public */
 export declare type BinarySequence = Uint8Array | number[];
+declare namespace BSON {
+    export { setInternalBufferSize, serialize, serializeWithBufferAndIndex, deserialize, calculateObjectSize, deserializeStream, UUIDExtended, BinaryExtended, BinaryExtendedLegacy, BinarySequence, CodeExtended, DBRefLike, Decimal128Extended, DoubleExtended, EJSONOptions, EJSONOptionsBase, EJSONSerializeOptions, EJSONParseOptions, Int32Extended, LongExtended, MaxKeyExtended, MinKeyExtended, ObjectIdExtended, ObjectIdLike, BSONRegExpExtended, BSONRegExpExtendedLegacy, BSONSymbolExtended, LongWithoutOverrides, TimestampExtended, TimestampOverrides, LongWithoutOverridesClass, SerializeOptions, DeserializeOptions, Code, BSONSymbol, DBRef, Binary, ObjectId, UUID, Long, Timestamp, Double, Int32, MinKey, MaxKey, BSONRegExp, Decimal128, NumberUtils, ByteUtils, BSONValue, bsonType, BSONTypeTag, BSONError, BSONVersionError, BSONRuntimeError, BSONOffsetError, BSONType, EJSON, onDemand, OnDemand, Document, CalculateObjectSizeOptions };
+}
+export { BSON };
+/**
+ * @public
+ * @experimental
+ */
+declare type BSONElement = [
+    type: number,
+    nameOffset: number,
+    nameLength: number,
+    offset: number,
+    length: number
+];
 /**
  * @public
  * @category Error
  *
- * `BSONError` objects are thrown when BSON ecounters an error.
+ * `BSONError` objects are thrown when BSON encounters an error.
  *
  * This is the parent class for all the other errors thrown by this library.
  */
 export declare class BSONError extends Error {
     get name(): string;
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
     /**
      * @public
      *
@@ -114,13 +222,29 @@ export declare class BSONError extends Error {
      */
     static isBSONError(value: unknown): value is BSONError;
 }
+/**
+ * @public
+ * @category Error
+ *
+ * @experimental
+ *
+ * An error generated when BSON bytes are invalid.
+ * Reports the offset the parser was able to reach before encountering the error.
+ */
+export declare class BSONOffsetError extends BSONError {
+    get name(): 'BSONOffsetError';
+    offset: number;
+    constructor(message: string, offset: number, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * A class representation of the BSON RegExp type.
  * @public
  * @category BSONType
  */
 export declare class BSONRegExp extends BSONValue {
-    get _bsontype(): "BSONRegExp";
+    get _bsontype(): 'BSONRegExp';
     pattern: string;
     options: string;
     /**
@@ -129,7 +253,7 @@ export declare class BSONRegExp extends BSONValue {
      */
     constructor(pattern: string, options?: string);
     static parseOptions(options?: string): string;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface BSONRegExpExtended {
@@ -152,7 +276,7 @@ export declare interface BSONRegExpExtendedLegacy {
  *
  */
 export declare class BSONRuntimeError extends BSONError {
-    get name(): "BSONRuntimeError";
+    get name(): 'BSONRuntimeError';
     constructor(message: string);
 }
 /**
@@ -161,7 +285,7 @@ export declare class BSONRuntimeError extends BSONError {
  * @category BSONType
  */
 export declare class BSONSymbol extends BSONValue {
-    get _bsontype(): "BSONSymbol";
+    get _bsontype(): 'BSONSymbol';
     value: string;
     /**
      * @param value - the string representing the symbol.
@@ -170,8 +294,8 @@ export declare class BSONSymbol extends BSONValue {
     /** Access the wrapped string value. */
     valueOf(): string;
     toString(): string;
-    inspect(): string;
     toJSON(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface BSONSymbolExtended {
@@ -204,20 +328,89 @@ export declare const BSONType: Readonly<{
 /** @public */
 export declare type BSONType = (typeof BSONType)[keyof typeof BSONType];
 /** @public */
+export declare const bsonType: unique symbol;
+/** @public */
+export declare type BSONTypeTag = 'BSONRegExp' | 'BSONSymbol' | 'ObjectId' | 'Binary' | 'Decimal128' | 'Double' | 'Int32' | 'Long' | 'MaxKey' | 'MinKey' | 'Timestamp' | 'Code' | 'DBRef';
+/** @public */
 export declare abstract class BSONValue {
     /** @public */
-    abstract get _bsontype(): string;
-    /** @public */
-    abstract inspect(): string;
+    abstract get _bsontype(): BSONTypeTag;
+    /**
+     * @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
+     */
+    abstract inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /**
  * @public
  * @category Error
  */
 export declare class BSONVersionError extends BSONError {
-    get name(): "BSONVersionError";
+    get name(): 'BSONVersionError';
     constructor();
 }
+/**
+ * @public
+ * @experimental
+ *
+ * A collection of functions that help work with data in a Uint8Array.
+ * ByteUtils is configured at load time to use Node.js or Web based APIs for the internal implementations.
+ */
+export declare type ByteUtils = {
+    /** Checks if the given value is a Uint8Array. */
+    isUint8Array: (value: unknown) => value is Uint8Array;
+    /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
+    toLocalBufferType: (buffer: Uint8Array | ArrayBufferView | ArrayBuffer) => Uint8Array;
+    /** Create empty space of size */
+    allocate: (size: number) => Uint8Array;
+    /** Create empty space of size, use pooled memory when available */
+    allocateUnsafe: (size: number) => Uint8Array;
+    /** Compare 2 Uint8Arrays lexicographically */
+    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 */
+    fromNumberArray: (array: number[]) => Uint8Array;
+    /** Create a Uint8Array from a base64 string */
+    fromBase64: (base64: string) => Uint8Array;
+    /** Create a Uint8Array from a UTF8 string */
+    fromUTF8: (utf8: string) => Uint8Array;
+    /** Create a base64 string from bytes */
+    toBase64: (buffer: Uint8Array) => string;
+    /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+    fromISO88591: (codePoints: string) => Uint8Array;
+    /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+    toISO88591: (buffer: Uint8Array) => string;
+    /** Create a Uint8Array from a hex string */
+    fromHex: (hex: string) => Uint8Array;
+    /** Create a lowercase hex string from bytes */
+    toHex: (buffer: Uint8Array) => string;
+    /** Create a string from utf8 code units, fatal=true will throw an error if UTF-8 bytes are invalid, fatal=false will insert replacement characters */
+    toUTF8: (buffer: Uint8Array, start: number, end: number, fatal: boolean) => string;
+    /** Get the utf8 code unit count from a string if it were to be transformed to utf8 */
+    utf8ByteLength: (input: string) => number;
+    /** Encode UTF8 bytes generated from `source` string into `destination` at byteOffset. Returns the number of bytes encoded. */
+    encodeUTF8Into: (destination: Uint8Array, source: string, byteOffset: number) => number;
+    /** Generate a Uint8Array filled with random bytes with byteLength */
+    randomBytes: (byteLength: number) => Uint8Array;
+    /** Interprets `buffer` as an array of 32-bit values and swaps the byte order in-place. */
+    swap32: (buffer: Uint8Array) => Uint8Array;
+};
+/**
+ * This is the only ByteUtils that should be used across the rest of the BSON library.
+ *
+ * The type annotation is important here, it asserts that each of the platform specific
+ * utils implementations are compatible with the common one.
+ *
+ * @public
+ * @experimental
+ */
+export declare const ByteUtils: ByteUtils;
 /**
  * Calculate the bson size for a passed in Javascript object.
  *
@@ -227,14 +420,14 @@ export declare class BSONVersionError extends BSONError {
  */
 export declare function calculateObjectSize(object: Document, options?: CalculateObjectSizeOptions): number;
 /** @public */
-export declare type CalculateObjectSizeOptions = Pick<SerializeOptions, "serializeFunctions" | "ignoreUndefined">;
+export declare type CalculateObjectSizeOptions = Pick<SerializeOptions, 'serializeFunctions' | 'ignoreUndefined'>;
 /**
  * A class representation of the BSON Code type.
  * @public
  * @category BSONType
  */
 export declare class Code extends BSONValue {
-    get _bsontype(): "Code";
+    get _bsontype(): 'Code';
     code: string;
     scope: Document | null;
     /**
@@ -246,7 +439,7 @@ export declare class Code extends BSONValue {
         code: string;
         scope?: Document;
     };
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface CodeExtended {
@@ -259,7 +452,7 @@ export declare interface CodeExtended {
  * @category BSONType
  */
 export declare class DBRef extends BSONValue {
-    get _bsontype(): "DBRef";
+    get _bsontype(): 'DBRef';
     collection: string;
     oid: ObjectId;
     db?: string;
@@ -271,7 +464,7 @@ export declare class DBRef extends BSONValue {
      */
     constructor(collection: string, oid: ObjectId, db?: string, fields?: Document);
     toJSON(): DBRefLike & Document;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface DBRefLike {
@@ -285,7 +478,7 @@ export declare interface DBRefLike {
  * @category BSONType
  */
 export declare class Decimal128 extends BSONValue {
-    get _bsontype(): "Decimal128";
+    get _bsontype(): 'Decimal128';
     readonly bytes: Uint8Array;
     /**
      * @param bytes - a buffer containing the raw Decimal128 bytes in little endian order,
@@ -298,10 +491,30 @@ export declare class Decimal128 extends BSONValue {
      * @param representation - a numeric string representation.
      */
     static fromString(representation: string): Decimal128;
+    /**
+     * 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;
+    private static _fromString;
     /** Create a string representation of the raw Decimal128 value */
     toString(): string;
     toJSON(): Decimal128Extended;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface Decimal128Extended {
@@ -317,21 +530,45 @@ export declare interface Decimal128Extended {
 export declare function deserialize(buffer: Uint8Array, options?: DeserializeOptions): Document;
 /** @public */
 export declare interface DeserializeOptions {
-    /** when deserializing a Long will return as a BigInt. */
+    /**
+     * when deserializing a Long return as a BigInt.
+     * @defaultValue `false`
+     */
     useBigInt64?: boolean;
-    /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
+    /**
+     * when deserializing a Long will fit it into a Number if it's smaller than 53 bits.
+     * @defaultValue `true`
+     */
     promoteLongs?: boolean;
-    /** when deserializing a Binary will return it as a node.js Buffer instance. */
+    /**
+     * when deserializing a Binary will return it as a node.js Buffer instance.
+     * @defaultValue `false`
+     */
     promoteBuffers?: boolean;
-    /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
+    /**
+     * when deserializing will promote BSON values to their Node.js closest equivalent types.
+     * @defaultValue `true`
+     */
     promoteValues?: boolean;
-    /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
+    /**
+     * allow to specify if there what fields we wish to return as unserialized raw buffer.
+     * @defaultValue `null`
+     */
     fieldsAsRaw?: Document;
-    /** return BSON regular expressions as BSONRegExp instances. */
+    /**
+     * return BSON regular expressions as BSONRegExp instances.
+     * @defaultValue `false`
+     */
     bsonRegExp?: boolean;
-    /** allows the buffer to be larger than the parsed BSON object. */
+    /**
+     * allows the buffer to be larger than the parsed BSON object.
+     * @defaultValue `false`
+     */
     allowObjectSmallerThanBufferSize?: boolean;
-    /** Offset into buffer to begin reading document from */
+    /**
+     * Offset into buffer to begin reading document from
+     * @defaultValue `0`
+     */
     index?: number;
     raw?: boolean;
     /** Allows for opt-out utf-8 validation for all keys or
@@ -376,7 +613,7 @@ export declare interface Document {
  * @category BSONType
  */
 export declare class Double extends BSONValue {
-    get _bsontype(): "Double";
+    get _bsontype(): 'Double';
     value: number;
     /**
      * Create a Double type
@@ -384,6 +621,20 @@ export declare class Double extends BSONValue {
      * @param value - the number we want to represent as a double.
      */
     constructor(value: number);
+    /**
+     * 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;
     /**
      * Access the number value.
      *
@@ -392,7 +643,7 @@ export declare class Double extends BSONValue {
     valueOf(): number;
     toJSON(): number;
     toString(radix?: number): string;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface DoubleExtended {
@@ -411,14 +662,28 @@ 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 = EJSONSerializeOptions & EJSONParseOptions;
 /** @public */
-export declare type EJSONOptions = {
-    /** Output using the Extended JSON v1 spec */
+export declare type EJSONOptionsBase = {
+    /**
+     * Output using the Extended JSON v1 spec
+     * @defaultValue `false`
+     */
     legacy?: boolean;
-    /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
+    /**
+     * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
+     * @defaultValue `false`
+     */
     relaxed?: boolean;
-    /** Enable native bigint support */
+};
+/** @public */
+export declare type EJSONParseOptions = EJSONOptionsBase & {
+    /**
+     * Enable native bigint support
+     * @defaultValue `false`
+     */
     useBigInt64?: boolean;
 };
 /**
@@ -427,14 +692,23 @@ 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;
 /**
  * A class representation of a BSON Int32 type.
  * @public
  * @category BSONType
  */
 export declare class Int32 extends BSONValue {
-    get _bsontype(): "Int32";
+    get _bsontype(): 'Int32';
     value: number;
     /**
      * Create an Int32 type
@@ -442,6 +716,20 @@ export declare class Int32 extends BSONValue {
      * @param value - the number we want to represent as an int32.
      */
     constructor(value: number | string);
+    /**
+     * 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;
     /**
      * Access the number value.
      *
@@ -450,7 +738,7 @@ export declare class Int32 extends BSONValue {
     valueOf(): number;
     toString(radix?: number): string;
     toJSON(): number;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface Int32Extended {
@@ -476,7 +764,7 @@ export declare interface Int32Extended {
  * Common constant values ZERO, ONE, NEG_ONE, etc. are found as static properties on this class.
  */
 export declare class Long extends BSONValue {
-    get _bsontype(): "Long";
+    get _bsontype(): 'Long';
     /** An indicator used to reliably determine if an object is a Long or not. */
     get __isLong__(): boolean;
     /**
@@ -493,18 +781,26 @@ export declare class Long extends BSONValue {
     unsigned: boolean;
     /**
      * Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers.
-     *  See the from* functions below for more convenient ways of constructing Longs.
-     *
-     * Acceptable signatures are:
-     * - Long(low, high, unsigned?)
-     * - Long(bigint, unsigned?)
-     * - Long(string, unsigned?)
      *
      * @param low - The low (signed) 32 bits of the long
      * @param high - The high (signed) 32 bits of the long
      * @param unsigned - Whether unsigned or not, defaults to signed
      */
-    constructor(low?: number | bigint | string, high?: number | boolean, unsigned?: boolean);
+    constructor(low: number, high?: number, unsigned?: boolean);
+    /**
+     * Constructs a 64 bit two's-complement integer, given a bigint representation.
+     *
+     * @param value - BigInt representation of the long value
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     */
+    constructor(value: bigint, unsigned?: boolean);
+    /**
+     * Constructs a 64 bit two's-complement integer, given a string representation.
+     *
+     * @param value - String representation of the long value
+     * @param unsigned - Whether unsigned or not, defaults to signed
+     */
+    constructor(value: string, unsigned?: boolean);
     static TWO_PWR_24: Long;
     /** Maximum unsigned value. */
     static MAX_UNSIGNED_VALUE: Long;
@@ -552,8 +848,112 @@ export declare class Long extends BSONValue {
      * @returns The corresponding Long value
      */
     static fromBigInt(value: bigint, unsigned?: boolean): Long;
+    /**
+     * 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;
+    /**
+     * 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
@@ -769,7 +1169,7 @@ export declare class Long extends BSONValue {
     static fromExtendedJSON(doc: {
         $numberLong: string;
     }, options?: EJSONOptions): number | Long | bigint;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface LongExtended {
@@ -787,7 +1187,7 @@ export declare const LongWithoutOverridesClass: LongWithoutOverrides;
  * @category BSONType
  */
 export declare class MaxKey extends BSONValue {
-    get _bsontype(): "MaxKey";
+    get _bsontype(): 'MaxKey';
     inspect(): string;
 }
 /** @public */
@@ -800,34 +1200,90 @@ export declare interface MaxKeyExtended {
  * @category BSONType
  */
 export declare class MinKey extends BSONValue {
-    get _bsontype(): "MinKey";
+    get _bsontype(): 'MinKey';
     inspect(): string;
 }
 /** @public */
 export declare interface MinKeyExtended {
     $minKey: 1;
 }
+/**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+export declare type NumberUtils = {
+    /** Is true if the current system is big endian. */
+    isBigEndian: boolean;
+    /**
+     * Parses a signed int32 at offset. Throws a `RangeError` if value is negative.
+     */
+    getNonnegativeInt32LE: (source: Uint8Array, offset: number) => number;
+    getInt32LE: (source: Uint8Array, offset: number) => number;
+    getUint32LE: (source: Uint8Array, offset: number) => number;
+    getUint32BE: (source: Uint8Array, offset: number) => number;
+    getBigInt64LE: (source: Uint8Array, offset: number) => bigint;
+    getFloat64LE: (source: Uint8Array, offset: number) => number;
+    setInt32BE: (destination: Uint8Array, offset: number, value: number) => 4;
+    setInt32LE: (destination: Uint8Array, offset: number, value: number) => 4;
+    setBigInt64LE: (destination: Uint8Array, offset: number, value: bigint) => 8;
+    setFloat64LE: (destination: Uint8Array, offset: number, value: number) => 8;
+};
+/**
+ * Number parsing and serializing utilities.
+ *
+ * @experimental
+ * @public
+ */
+export declare const NumberUtils: NumberUtils;
 /**
  * A class representation of the BSON ObjectId type.
  * @public
  * @category BSONType
  */
 export declare class ObjectId extends BSONValue {
-    get _bsontype(): "ObjectId";
+    get _bsontype(): 'ObjectId';
     static cacheHexString: boolean;
+    /** To generate a new ObjectId, use ObjectId() with no argument. */
+    constructor();
+    /**
+     * Create ObjectId from a 24 character hex string.
+     *
+     * @param inputId - A 24 character hex string.
+     */
+    constructor(inputId: string);
     /**
-     * Create an ObjectId type
+     * Create ObjectId from the BSON ObjectId type.
      *
-     * @param inputId - Can be a 24 character hex string, 12 byte binary Buffer, or a number.
+     * @param inputId - The BSON ObjectId type.
      */
-    constructor(inputId?: string | number | ObjectId | ObjectIdLike | Uint8Array);
+    constructor(inputId: ObjectId);
+    /**
+     * Create ObjectId from the object type that has the toHexString method.
+     *
+     * @param inputId - The ObjectIdLike type.
+     */
+    constructor(inputId: ObjectIdLike);
+    /**
+     * Create ObjectId from a 12 byte binary Buffer.
+     *
+     * @param inputId - A 12 byte binary Buffer.
+     */
+    constructor(inputId: Uint8Array);
+    /**
+     * Implementation overload.
+     *
+     * @param inputId - All input types that are used in the constructor implementation.
+     */
+    constructor(inputId?: string | ObjectId | ObjectIdLike | Uint8Array);
     /**
      * The ObjectId bytes
      * @readonly
      */
     get id(): Uint8Array;
     set id(value: Uint8Array);
-    /** Returns the ObjectId id as a 24 character hex string representation */
+    /** Returns the ObjectId id as a 24 lowercase character hex string representation */
     toHexString(): string;
     /**
      * Generate a 12 byte id buffer used in ObjectId's
@@ -839,7 +1295,7 @@ export declare class ObjectId extends BSONValue {
      * Converts the id into a 24 character hex string for printing, unless encoding is provided.
      * @param encoding - hex or base64
      */
-    toString(encoding?: "hex" | "base64"): string;
+    toString(encoding?: 'hex' | 'base64'): string;
     /** Converts to its JSON the 24 character hex string representation. */
     toJSON(): string;
     /**
@@ -847,7 +1303,7 @@ export declare class ObjectId extends BSONValue {
      *
      * @param otherId - ObjectId instance to compare against.
      */
-    equals(otherId: string | ObjectId | ObjectIdLike): boolean;
+    equals(otherId: string | ObjectId | ObjectIdLike | undefined | null): boolean;
     /** Returns the generation date (accurate up to the second) that this ID was generated. */
     getTimestamp(): Date;
     /**
@@ -865,12 +1321,16 @@ export declare class ObjectId extends BSONValue {
     /** Creates an ObjectId instance from a base64 string */
     static createFromBase64(base64: string): ObjectId;
     /**
-     * Checks if a value is a valid bson ObjectId
+     * Checks if a value can be used to create a valid bson ObjectId
+     * @param id - any JS value
+     */
+    static isValid(id: string | ObjectId | ObjectIdLike | Uint8Array): boolean;
+    /**
+     * Converts to a string representation of this Id.
      *
-     * @param id - ObjectId instance to validate.
+     * @returns return the 24 character hex string representation.
      */
-    static isValid(id: string | number | ObjectId | ObjectIdLike | Uint8Array): boolean;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface ObjectIdExtended {
@@ -882,6 +1342,23 @@ export declare interface ObjectIdLike {
     __id?: string;
     toHexString(): string;
 }
+/**
+ * @experimental
+ * @public
+ *
+ * A new set of BSON APIs that are currently experimental and not intended for production use.
+ */
+export declare type OnDemand = {
+    parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+    BSONElement: BSONElement;
+    ByteUtils: ByteUtils;
+    NumberUtils: NumberUtils;
+};
+/**
+ * @experimental
+ * @public
+ */
+export declare const onDemand: OnDemand;
 /**
  * Parse an Extended JSON string, constructing the JavaScript value or object described by that
  * string.
@@ -898,7 +1375,7 @@ export declare interface ObjectIdLike {
  * 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.
  *
@@ -909,13 +1386,26 @@ declare function parse(text: string, options?: EJSONOptions): any;
 export declare function serialize(object: Document, options?: SerializeOptions): Uint8Array;
 /** @public */
 export declare interface SerializeOptions {
-    /** the serializer will check if keys are valid. */
+    /**
+     * the serializer will check if keys are valid.
+     * @defaultValue `false`
+     */
     checkKeys?: boolean;
-    /** serialize the javascript functions **(default:false)**. */
+    /**
+     * serialize the javascript functions
+     * @defaultValue `false`
+     */
     serializeFunctions?: boolean;
-    /** serialize will not emit undefined fields **(default:true)** */
+    /**
+     * serialize will not emit undefined fields
+     * note that the driver sets this to `false`
+     * @defaultValue `true`
+     */
     ignoreUndefined?: boolean;
-    /** the index in the buffer where we wish to start serializing into */
+    /**
+     * the index in the buffer where we wish to start serializing into
+     * @defaultValue `0`
+     */
     index?: number;
 }
 /**
@@ -931,7 +1421,7 @@ export declare function serializeWithBufferAndIndex(object: Document, finalBuffe
 /**
  * Sets the size of the internal serialization buffer.
  *
- * @param size - The desired size for the internal serialization buffer
+ * @param size - The desired size for the internal serialization buffer in bytes
  * @public
  */
 export declare function setInternalBufferSize(size: number): void;
@@ -958,14 +1448,24 @@ export declare function setInternalBufferSize(size: number): void;
  * console.log(EJSON.stringify(doc));
  * ```
  */
-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) | EJSONSerializeOptions, space?: string | number, options?: EJSONSerializeOptions): string;
 /**
  * @public
  * @category BSONType
- * */
+ *
+ * A special type for _internal_ MongoDB use and is **not** associated with the regular Date type.
+ */
 export declare class Timestamp extends LongWithoutOverridesClass {
-    get _bsontype(): "Timestamp";
+    get _bsontype(): 'Timestamp';
     static readonly MAX_VALUE: Long;
+    /**
+     * An incrementing ordinal for operations within a given second.
+     */
+    get i(): number;
+    /**
+     * A `time_t` value measuring seconds since the Unix epoch
+     */
+    get t(): number;
     /**
      * @param int - A 64-bit bigint representing the Timestamp.
      */
@@ -1002,7 +1502,7 @@ export declare class Timestamp extends LongWithoutOverridesClass {
      * @param optRadix - the radix in which the text is written.
      */
     static fromString(str: string, optRadix: number): Timestamp;
-    inspect(): string;
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare interface TimestampExtended {
@@ -1012,15 +1512,16 @@ export declare interface TimestampExtended {
     };
 }
 /** @public */
-export declare type TimestampOverrides = "_bsontype" | "toExtendedJSON" | "fromExtendedJSON" | "inspect";
+export declare type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromExtendedJSON' | 'inspect' | typeof bsonType;
 /**
  * A class representation of the BSON UUID type.
  * @public
  */
 export declare class UUID extends Binary {
-    static cacheHexString: boolean;
     /**
-     * Create an UUID type
+     * Create a UUID type
+     *
+     * When the argument to the constructor is omitted a random v4 UUID will be generated.
      *
      * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
      */
@@ -1034,12 +1535,12 @@ export declare class UUID extends Binary {
     /**
      * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
      * @param includeDashes - should the string exclude dash-separators.
-     * */
+     */
     toHexString(includeDashes?: boolean): string;
     /**
      * Converts the id into a 36 character (dashes included) hex string, unless a encoding is specified.
      */
-    toString(encoding?: "hex" | "base64"): string;
+    toString(encoding?: 'hex' | 'base64'): string;
     /**
      * Converts the id into its JSON string representation.
      * A 36 character (dashes included) hex string in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
@@ -1063,7 +1564,7 @@ export declare class UUID extends Binary {
      * Checks if a value is a valid bson UUID
      * @param input - UUID, string or Buffer to validate.
      */
-    static isValid(input: string | Uint8Array | UUID): boolean;
+    static isValid(input: string | Uint8Array | UUID | Binary): boolean;
     /**
      * Creates an UUID from a hex string representation of an UUID.
      * @param hexString - 32 or 36 character hex string (dashes excluded/included).
@@ -1071,7 +1572,13 @@ export declare class UUID extends Binary {
     static createFromHexString(hexString: string): UUID;
     /** Creates an UUID from a base64 string representation of an UUID. */
     static createFromBase64(base64: string): UUID;
-    inspect(): string;
+    /**
+     * Converts to a string representation of this Id.
+     *
+     * @returns return the 36 character hex string representation.
+     *
+     */
+    inspect(depth?: number, options?: unknown, inspect?: InspectFn): string;
 }
 /** @public */
 export declare type UUIDExtended = {