A BSON parser Node.JS native addon.
BSON is short for Binary JSON and is the binary-encoded serialization of JSON-like documents. You can learn more about it in the specification.
While this library is compatible with the mongodb driver version 4+, bson-ext will soon be deprecated and no longer supported. It is strongly recommended that js-bson be used instead.
Only the following version combinations with the MongoDB Node.js Driver are considered stable.
bson-ext@1.x |
bson-ext@2.x |
bson-ext@4.x |
|
|---|---|---|---|
mongodb@6.x |
N/A | N/A | N/A |
mongodb@5.x |
N/A | N/A | N/A |
mongodb@4.x |
N/A | N/A | ✓ |
mongodb@3.x |
✓ | ✓ | N/A |
npm install bson-extA simple example of how to use BSON in Node.js:
// Get BSON parser class
const BSON = require('bson-ext')
// Get the Long type
const Long = BSON.Long;
// Serialize document
const doc = { long: Long.fromNumber(100) }
// Serialize a document
const data = BSON.serialize(doc)
console.log('data:', data)
// Deserialize the resulting Buffer
var docRoundTrip = bson.deserialize(data)
console.log('docRoundTrip:', docRoundTrip)To build a new version perform the following operation.
npm install
npm run buildFor all BSON types documentation, please refer to the documentation for the MongoDB Node.js driver.
The BSON serialize method takes a JavaScript object and an optional options object and returns a Node.js Buffer.
/**
* The BSON library accepts plain javascript objects.
* It serializes to BSON by iterating the keys
*/
interface Document {
[key: string]: any;
}
interface SerializeOptions {
/** the serializer will check if keys are valid. */
checkKeys?: boolean;
/** serialize the javascript functions **(default:false)**. */
serializeFunctions?: boolean;
/** serialize will not emit undefined fields **(default:true)** */
ignoreUndefined?: boolean;
}
/**
* Serialize a Javascript object.
*
* @param object - the Javascript object to serialize.
* @returns Buffer object containing the serialized object.
*/
function serialize(object: Document, options?: SerializeOptions): Buffer;The BSON serializeWithBufferAndIndex method takes an object, a target buffer instance and an optional options object and returns the end serialization index in the final buffer.
/**
* Serialize a Javascript object using a predefined Buffer and index into the buffer,
* useful when pre-allocating the space for serialization.
*
* @param object - the Javascript object to serialize.
* @param finalBuffer - the Buffer you pre-allocated to store the serialized BSON object.
* @returns the index pointing to the last written byte in the buffer.
*/
function serializeWithBufferAndIndex(object: Document, finalBuffer: Buffer, options?: SerializeOptions): number;The BSON calculateObjectSize method takes a JavaScript object and an optional options object and returns the size of the BSON object.
interface CalculateObjectSizeOptions {
/** serialize the javascript functions **(default:false)**. */
serializeFunctions?: boolean;
/** serialize will not emit undefined fields **(default:true)** */
ignoreUndefined?: boolean;
}
/**
* Calculate the bson size for a passed in Javascript object.
*
* @param object - the Javascript object to calculate the BSON byte size for
* @returns size of BSON object in bytes
* @public
*/
function calculateObjectSize(object: Document, options?: CalculateObjectSizeOptions): number;The BSON deserialize method takes a Node.js Buffer and an optional options object and returns a deserialized JavaScript object.
interface DeserializeOptions {
/** evaluate functions in the BSON document scoped to the object deserialized. */
evalFunctions?: boolean;
/** cache evaluated functions for reuse. */
cacheFunctions?: boolean;
/** when deserializing a Long will fit it into a Number if it's smaller than 53 bits */
promoteLongs?: boolean;
/** when deserializing a Binary will return it as a node.js Buffer instance. */
promoteBuffers?: boolean;
/** when deserializing will promote BSON values to their Node.js closest equivalent types. */
promoteValues?: boolean;
/** allow to specify if there what fields we wish to return as unserialized raw buffer. */
fieldsAsRaw?: Document;
/** return BSON regular expressions as BSONRegExp instances. */
bsonRegExp?: boolean;
/** allows the buffer to be larger than the parsed BSON object */
allowObjectSmallerThanBufferSize?: boolean;
/** Offset into buffer to begin reading document from */
index?: number;
}
/**
* Deserialize data as BSON.
*
* @param buffer - the buffer containing the serialized set of BSON documents.
* @returns returns the deserialized Javascript Object.
* @public
*/
function deserialize(buffer: Buffer | ArrayBufferView | ArrayBuffer, options?: DeserializeOptions): Document;The BSON deserializeStream method takes a Node.js Buffer, startIndex and allow more control over deserialization of a Buffer containing concatenated BSON documents.
/**
* Deserialize stream data as BSON documents.
*
* @param data - the buffer containing the serialized set of BSON documents.
* @param startIndex - the start index in the data Buffer where the deserialization is to start.
* @param numberOfDocuments - number of documents to deserialize.
* @param documents - an array where to store the deserialized documents.
* @param docStartIndex - the index in the documents array from where to start inserting documents.
* @param options - additional options used for the deserialization.
* @returns next index in the buffer after deserialization **x** numbers of documents.
* @public
*/
function deserializeStream(data: Buffer | ArrayBufferView | ArrayBuffer, startIndex: number, numberOfDocuments: number, documents: Document[], docStartIndex: number, options: DeserializeOptions): number;