bsonx

bsonx is a serialization library, inspired by bson, that handles a wider range of native JavaScript object types, including BigInts, Sets, and Maps — even undefined and Errors. In addition, bsonx does not require input to be a JSON object: it can just as easily serialize solitary items, like primitive values and Arrays. And it can be used to create deep clones, too.

The "x" equals "extra"!

Examples

Import bsonx

import { BSONX } from "@jamesbontempo/bsonx";

... or ...

const { BSONX } = require("@jamesbontempo/bsonx");

Serialize a standard JSON object

const serialized = BSONX.serialize({ id: 1, string: "test", number: 123, array: [3, 4, 5] });
// <Buffer 42 58 02 17 04 00 00 00 06 02 00 00 00 69 64 ... >
const deserialized = BSONX.deserialize(serialized);
// { id: 1, string: 'test', number: 123, array: [ 3, 4, 5 ] }

Serialize a JSON object that contains a BigInt

const serialized = BSONX.serialize({ bigint: 99999999999999999999999n });
// <Buffer 42 58 02 17 01 00 00 00 06 06 00 00 00 62 69 ... >
const deserialized = BSONX.deserialize(serialized);
// { bigint: 99999999999999999999999n }

Serialize a solitary Map

const serialized = BSONX.serialize(new Map([[1, ["one", "uno"]], [2, ["two", "dos"]]]));
// <Buffer 42 58 02 19 02 00 00 00 04 01 00 00 00 31 0b ... >
const deserialized = BSONX.deserialize(serialized);
// Map(2) { 1 => [ 'one', 'uno' ], 2 => [ 'two', 'dos' ] }

Create a deep clone of a Map

const map = new Map([[1, ["one", "uno"]], [2, ["two", "dos"]]]);
const clone = BSONX.clone(map);
// Map(2) { 1 => [ 'one', 'uno' ], 2 => [ 'two', 'dos' ] }

Methods

serialize

serialize(item)

Serializes an item. The resulting buffer includes a 3-byte header containing the bsonx magic bytes (0x42 0x58) and a version byte, allowing future versions to deserialize buffers produced by earlier versions.

Parameters:

| Name | Type | Description | |------|------|-------------| | item | any | Any item of an allowable type (see Allowable types) |

Returns a Buffer containing the serialized version of the item.

deserialize

deserialize(buffer)

Deserializes an item previously serialized with serialize. Automatically detects the format version from the buffer header. Buffers produced by pre-1.0.0 versions of bsonx (which lack a header) are handled gracefully and deserialized as version 1.

Parameters:

| Name | Type | Description | |------|------|-------------| | buffer | Buffer | The buffer produced by a previous call to serialize |

Returns the original item as a native JavaScript object.

clone

clone(item)

Creates a deep clone of an item.

Parameters:

| Name | Type | Description | |------|------|-------------| | item | any | Any item of an allowable type (see Allowable types) |

Returns a deep clone of the item.

Allowable types

bsonx can serialize the following types:

• Array
• BigInt
• BigInt64Array
• BigUint64Array
• Boolean
• Date
• Error
• EvalError
• Float32Array
• Float64Array
• Function
• Int8Array
• Int16Array
• Int32Array
• Map
• null
• Number
• Object
• RangeError
• ReferenceError
• RegExp
• Set
• String
• Symbol
• SyntaxError
• TypeError
• Uint8Array
• Uint8ClampedArray
• Uint16Array
• Uint32Array
• undefined
• URIError

Drop-in bson replacement

bsonx does not implement the entire bson interface, only the serialize and deserialize methods. However, if that's all you're using bson for, you can use bsonx as a drop-in replacement and start serializing a wider range of objects:

import { BSONX as BSON } from "@jamesbontempo/bsonx";

... or ...

const { BSONX: BSON } = require("@jamesbontempo/bsonx");

Change log

1.0.0

• Versioned binary format with magic bytes header (0x42 0x58) for forward compatibility
• Automatic detection and handling of pre-1.0.0 (unversioned) buffers
• Type codes reordered to encode natural sort order
• "typedarray" category introduced to distinguish typed arrays from plain arrays
• Removed stateful Serializer/Deserializer classes in favor of exported functions
• Fixed buffer allocation to use single-pass copying instead of repeated concatenation

0.2.0

• Added clone method