@jamesbontempo/bsonx

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 12 04 00 00 00 17 02 00 00 00 69 64 11 01 00 00 00 31 17 ... >
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 12 01 00 00 00 17 06 00 00 00 62 69 67 69 6e 74 02 17 00 ... >
const deserialized = BSONX.deserialize(serialized);
// { bigint: 99999999999999999999999n }

Serialize a solitary Map

const serialized = BSONX.serialize(new Map([[1, ["one", "uno"]], [2, ["two", "dos"]]]));
// <Buffer 0f 02 00 00 00 11 01 00 00 00 31 01 02 00 00 00 17 03 00 ... >
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.

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.

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)

Craetes 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
• RangeRrror
• ReferenceError
• RegExp
• Set
• Sring
• Symbol
• SyntaxError
• TypeError
• UInt8Array
• UInt16Array
• UInt32Array
• UInt8ClampedArray
• undefined
• URIError

Drop-in bson replacement

bsonx does not implment 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

0.2.0

• Added clone method