bson 5.2.0 → 5.4.0

package/README.md

@@ -69,35 +69,9 @@ npm install bson
 
 ## Documentation
 
-### Objects
-
-<dl>
-<dt><a href="#EJSON">EJSON</a> : <code>object</code></dt>
-<dd></dd>
-</dl>
-
-### Functions
-
-<dl>
-<dt><a href="#setInternalBufferSize">setInternalBufferSize(size)</a></dt>
-<dd><p>Sets the size of the internal serialization buffer.</p>
-</dd>
-<dt><a href="#serialize">serialize(object)</a> ⇒ <code>Buffer</code></dt>
-<dd><p>Serialize a Javascript object.</p>
-</dd>
-<dt><a href="#serializeWithBufferAndIndex">serializeWithBufferAndIndex(object, buffer)</a> ⇒ <code>Number</code></dt>
-<dd><p>Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.</p>
-</dd>
-<dt><a href="#deserialize">deserialize(buffer)</a> ⇒ <code>Object</code></dt>
-<dd><p>Deserialize data as BSON.</p>
-</dd>
-<dt><a href="#calculateObjectSize">calculateObjectSize(object)</a> ⇒ <code>Number</code></dt>
-<dd><p>Calculate the bson size for a passed in Javascript object.</p>
-</dd>
-<dt><a href="#deserializeStream">deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])</a> ⇒ <code>Number</code></dt>
-<dd><p>Deserialize stream data as BSON documents.</p>
-</dd>
-</dl>
+### BSON 
+
+[API documentation](https://mongodb.github.io/node-mongodb-native/Next/modules/BSON.html)
 
 <a name="EJSON"></a>
 
@@ -189,103 +163,6 @@ Serializes an object to an Extended JSON string, and reparse it as a JavaScript
 
 Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types
 
-<a name="setInternalBufferSize"></a>
-
-### setInternalBufferSize(size)
-
-| Param | Type | Description |
-| --- | --- | --- |
-| size | <code>number</code> | The desired size for the internal serialization buffer |
-
-Sets the size of the internal serialization buffer.
-
-<a name="serialize"></a>
-
-### serialize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to serialize. |
-| [options.checkKeys] | <code>Boolean</code> |  | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-
-Serialize a Javascript object.
-
-**Returns**: <code>Buffer</code> - returns the Buffer object containing the serialized object.
-<a name="serializeWithBufferAndIndex"></a>
-
-### serializeWithBufferAndIndex(object, buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to serialize. |
-| buffer | <code>Buffer</code> |  | the Buffer you pre-allocated to store the serialized BSON object. |
-| [options.checkKeys] | <code>Boolean</code> |  | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-| [options.index] | <code>Number</code> |  | the index in the buffer where we wish to start serializing into. |
-
-Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.
-
-**Returns**: <code>Number</code> - returns the index pointing to the last written byte in the buffer.
-<a name="deserialize"></a>
-
-### deserialize(buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| buffer | <code>Buffer</code> |  | the buffer containing the serialized set of BSON documents. |
-| [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
-| [options.useBigInt64] | <code>Object</code> | <code>false</code> | when deserializing a Long will return a BigInt. |
-| [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
-| [options.allowObjectSmallerThanBufferSize] | <code>boolean</code> | <code>false</code> | allows the buffer to be larger than the parsed BSON object. |
-
-Deserialize data as BSON.
-
-**Returns**: <code>Object</code> - returns the deserialized Javascript Object.
-<a name="calculateObjectSize"></a>
-
-### calculateObjectSize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to calculate the BSON byte size for. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-
-Calculate the bson size for a passed in Javascript object.
-
-**Returns**: <code>Number</code> - returns the number of bytes the BSON object will take up.
-<a name="deserializeStream"></a>
-
-### deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| data | <code>Buffer</code> |  | the buffer containing the serialized set of BSON documents. |
-| startIndex | <code>Number</code> |  | the start index in the data Buffer where the deserialization is to start. |
-| numberOfDocuments | <code>Number</code> |  | number of documents to deserialize. |
-| documents | <code>Array</code> |  | an array where to store the deserialized documents. |
-| docStartIndex | <code>Number</code> |  | the index in the documents array from where to start inserting documents. |
-| [options] | <code>Object</code> |  | additional options used for the deserialization. |
-| [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
-| [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
-
-Deserialize stream data as BSON documents.
-
-**Returns**: <code>Number</code> - returns the next index in the buffer after deserialization **x** numbers of documents.
-
 ## Error Handling
 
 It is our recommendation to use `BSONError.isBSONError()` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `BSONError.isBSONError()` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.
@@ -311,23 +188,16 @@ try {
 
 ## React Native
 
-BSON requires that `TextEncoder`, `TextDecoder`, `atob`, `btoa`, and `crypto.getRandomValues` are available globally.  These are present in most Javascript runtimes but require polyfilling in React Native.  Polyfills for the missing functionality can be installed with the following command:
+BSON vendors the required polyfills for `TextEncoder`, `TextDecoder`, `atob`, `btoa` imported from React Native and therefore doesn't expect users to polyfill these. One additional polyfill, `crypto.getRandomValues` is recommended and can be installed with the following command:
+
 ```sh
-npm install --save react-native-get-random-values text-encoding-polyfill base-64
+npm install --save react-native-get-random-values
 ```
 
 The following snippet should be placed at the top of the entrypoint (by default this is the root `index.js` file) for React Native projects using the BSON library.  These lines must be placed for any code that imports `BSON`.
 
 ```typescript
 // Required Polyfills For ReactNative
-import {encode, decode} from 'base-64';
-if (global.btoa == null) {
-  global.btoa = encode;
-}
-if (global.atob == null) {
-  global.atob = decode;
-}
-import 'text-encoding-polyfill';
 import 'react-native-get-random-values';
 ```
 
@@ -337,7 +207,7 @@ Finally, import the `BSON` library like so:
 import { BSON, EJSON } from 'bson';
 ```
 
-This will cause React Native to import the `node_modules/bson/lib/bson.cjs` bundle (see the `"react-native"` setting we have in the `"exports"` section of our [package.json](./package.json).)
+This will cause React Native to import the `node_modules/bson/lib/bson.rn.cjs` bundle (see the `"react-native"` setting we have in the `"exports"` section of our [package.json](./package.json).)
 
 ### Technical Note about React Native module import
 

package/bson.d.ts

@@ -280,7 +280,7 @@ export declare const BSONType: Readonly<{
 }>;
 
 /** @public */
-export declare type BSONType = typeof BSONType[keyof typeof BSONType];
+export declare type BSONType = (typeof BSONType)[keyof typeof BSONType];
 
 /** @public */
 export declare abstract class BSONValue {
@@ -416,21 +416,45 @@ export declare function deserialize(buffer: Uint8Array, options?: DeserializeOpt
 
 /** @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
@@ -522,11 +546,19 @@ declare function EJSONdeserialize(ejson: Document, options?: EJSONOptions): any;
 
 /** @public */
 export declare type EJSONOptions = {
-    /** Output using the Extended JSON v1 spec */
+    /**
+     * 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 */
+    /**
+     * Enable native bigint support
+     * @defaultValue `false`
+     */
     useBigInt64?: boolean;
 };
 
@@ -1049,14 +1081,27 @@ export declare function serialize(object: Document, options?: SerializeOptions):
 
 /** @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;
     /* Excluded from this release type: minInternalBufferSize */
-    /** 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;
 }
 
@@ -1074,7 +1119,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;
@@ -1107,7 +1152,7 @@ declare function stringify(value: any, replacer?: (number | string)[] | ((this:
 /**
  * @public
  * @category BSONType
- * */
+ */
 export declare class Timestamp extends LongWithoutOverridesClass {
     get _bsontype(): 'Timestamp';
     static readonly MAX_VALUE: Long;
@@ -1168,10 +1213,12 @@ export declare type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromE
  * @public
  */
 export declare class UUID extends Binary {
+    /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
     static cacheHexString: boolean;
-    /* Excluded from this release type: __id */
     /**
-     * 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.
      */
@@ -1185,7 +1232,7 @@ 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.
@@ -1214,7 +1261,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).
@@ -1222,6 +1269,8 @@ 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;
+    /* Excluded from this release type: bytesFromString */
+    /* Excluded from this release type: isValidUUIDString */
     inspect(): string;
 }