diff --git a/README.md b/README.md index ec06359f..a3e40511 100644 --- a/README.md +++ b/README.md @@ -69,35 +69,9 @@ npm install bson ## Documentation -### Objects - -
object
Sets the size of the internal serialization buffer.
-Buffer
Serialize a Javascript object.
-Number
Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.
-Object
Deserialize data as BSON.
-Number
Calculate the bson size for a passed in Javascript object.
-Number
Deserialize stream data as BSON documents.
-number
| The desired size for the internal serialization buffer |
-
-Sets the size of the internal serialization buffer.
-
-
-
-### serialize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | Object
| | the Javascript object to serialize. |
-| [options.checkKeys] | Boolean
| | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | Boolean
| false
| serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | Boolean
| true
| ignore undefined fields **(default:true)**. |
-
-Serialize a Javascript object.
-
-**Returns**: Buffer
- returns the Buffer object containing the serialized object.
-
-
-### serializeWithBufferAndIndex(object, buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | Object
| | the Javascript object to serialize. |
-| buffer | Buffer
| | the Buffer you pre-allocated to store the serialized BSON object. |
-| [options.checkKeys] | Boolean
| | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | Boolean
| false
| serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | Boolean
| true
| ignore undefined fields **(default:true)**. |
-| [options.index] | Number
| | 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**: Number
- returns the index pointing to the last written byte in the buffer.
-
-
-### deserialize(buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| buffer | Buffer
| | the buffer containing the serialized set of BSON documents. |
-| [options.evalFunctions] | Object
| false
| evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | Object
| false
| cache evaluated functions for reuse. |
-| [options.useBigInt64] | Object
| false
| when deserializing a Long will return a BigInt. |
-| [options.promoteLongs] | Object
| true
| when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | Object
| false
| when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | Object
| true
| when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | Object
|
| allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | Object
| false
| return BSON regular expressions as BSONRegExp instances. |
-| [options.allowObjectSmallerThanBufferSize] | boolean
| false
| allows the buffer to be larger than the parsed BSON object. |
-
-Deserialize data as BSON.
-
-**Returns**: Object
- returns the deserialized Javascript Object.
-
-
-### calculateObjectSize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | Object
| | the Javascript object to calculate the BSON byte size for. |
-| [options.serializeFunctions] | Boolean
| false
| serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | Boolean
| true
| ignore undefined fields **(default:true)**. |
-
-Calculate the bson size for a passed in Javascript object.
-
-**Returns**: Number
- returns the number of bytes the BSON object will take up.
-
-
-### deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| data | Buffer
| | the buffer containing the serialized set of BSON documents. |
-| startIndex | Number
| | the start index in the data Buffer where the deserialization is to start. |
-| numberOfDocuments | Number
| | number of documents to deserialize. |
-| documents | Array
| | an array where to store the deserialized documents. |
-| docStartIndex | Number
| | the index in the documents array from where to start inserting documents. |
-| [options] | Object
| | additional options used for the deserialization. |
-| [options.evalFunctions] | Object
| false
| evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | Object
| false
| cache evaluated functions for reuse. |
-| [options.promoteLongs] | Object
| true
| when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | Object
| false
| when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | Object
| false
| when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | Object
|
| allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | Object
| false
| return BSON regular expressions as BSONRegExp instances. |
-
-Deserialize stream data as BSON documents.
-
-**Returns**: Number
- 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.
diff --git a/src/binary.ts b/src/binary.ts
index b975663f..f69f62bf 100644
--- a/src/binary.ts
+++ b/src/binary.ts
@@ -362,7 +362,7 @@ export 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 = true): string {
if (includeDashes) {
return [
diff --git a/src/bson.ts b/src/bson.ts
index 962e69e0..7c7c089d 100644
--- a/src/bson.ts
+++ b/src/bson.ts
@@ -70,7 +70,7 @@ let buffer = ByteUtils.allocate(MAXSIZE);
/**
* 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 function setInternalBufferSize(size: number): void {
diff --git a/src/extended_json.ts b/src/extended_json.ts
index ba05db75..eb08b3c1 100644
--- a/src/extended_json.ts
+++ b/src/extended_json.ts
@@ -24,11 +24,19 @@ import { Timestamp } from './timestamp';
/** @public */
export 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;
};
diff --git a/src/parser/deserializer.ts b/src/parser/deserializer.ts
index 0389b0d9..379c7752 100644
--- a/src/parser/deserializer.ts
+++ b/src/parser/deserializer.ts
@@ -19,21 +19,45 @@ import { validateUtf8 } from '../validate_utf8';
/** @public */
export 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;
diff --git a/src/parser/serializer.ts b/src/parser/serializer.ts
index b59a1b77..6f75cb0a 100644
--- a/src/parser/serializer.ts
+++ b/src/parser/serializer.ts
@@ -16,15 +16,28 @@ import { isAnyArrayBuffer, isDate, isMap, isRegExp, isUint8Array } from './utils
/** @public */
export 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;
/** @internal Resize internal buffer */
minInternalBufferSize?: number;
- /** 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;
}
diff --git a/src/timestamp.ts b/src/timestamp.ts
index 78d7fc4c..2bda19dc 100644
--- a/src/timestamp.ts
+++ b/src/timestamp.ts
@@ -27,7 +27,7 @@ export interface TimestampExtended {
/**
* @public
* @category BSONType
- * */
+ */
export class Timestamp extends LongWithoutOverridesClass {
get _bsontype(): 'Timestamp' {
return 'Timestamp';