NOTE: This libray has been merged into the 4.x version of the `bson` package, and is no longer being maintained as a standalone package.

MongoDB Extended JSON Library

The MongoDB Extended JSON Library allows you to convert MongoDB documents to Extended JSON, and vice versa. See the Extended JSON specification here.

Documentation

Functions

parse(text, [options]) ⇒ object: Parse an Extended JSON string, constructing the JavaScript value or object described by that string.
stringify(value, [replacer], [space], [options]) ⇒ string: Converts a BSON document to an Extended JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.
serialize(bson, [options]) ⇒ object: Serializes an object to an Extended JSON string, and reparse it as a JavaScript object.
deserialize(ejson, [options]) ⇒ object: Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types

parse(text, [options])

Param	Type	Default	Description
text	`string`
[options]	`object`		Optional settings
[options.relaxed]	`boolean`	`true`	Attempt to return native JS types where possible, rather than BSON types (if true)

Parse an Extended JSON string, constructing the JavaScript value or object described by that string.

Example

const EJSON = require('mongodb-extjson');
const text = '{ "int32": { "$numberInt": "10" } }';

// prints { int32: { [String: '10'] _bsontype: 'Int32', value: '10' } }
console.log(EJSON.parse(text, { relaxed: false }));

// prints { int32: 10 }
console.log(EJSON.parse(text));

stringify(value, [replacer], [space], [options])

Param	Type	Default	Description
value	`object`		The value to convert to extended JSON
[replacer]	`function` \| `array`		A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting/filtering the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string
[space]	`string` \| `number`		A String or Number object that's used to insert white space into the output JSON string for readability purposes.
[options]	`object`		Optional settings
[options.relaxed]	`boolean`	`true`	Enabled Extended JSON's `relaxed` mode

Converts a BSON document to an Extended JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.

Example

const EJSON = require('mongodb-extjson');
const Int32 = require('mongodb').Int32;
const doc = { int32: new Int32(10) };

// prints '{"int32":{"$numberInt":"10"}}'
console.log(EJSON.stringify(doc, { relaxed: false }));

// prints '{"int32":10}'
console.log(EJSON.stringify(doc));

serialize(bson, [options])

Param	Type	Description
bson	`object`	The object to serialize
[options]	`object`	Optional settings passed to the `stringify` function

Serializes an object to an Extended JSON string, and reparse it as a JavaScript object.

deserialize(ejson, [options])

Param	Type	Description
ejson	`object`	The Extended JSON object to deserialize
[options]	`object`	Optional settings passed to the parse method

Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types

Usage With Other BSON Parsers

Although we include the pure Javascript BSON parser by default, you can also use a different BSON parser with this library, such as bson-ext. For example:

let EJSON = require('mongodb-extjson'),
	BSON = require('bson-ext'),
    Int32 = BSON.Int32;

// set BSON module to be bson-ext
EJSON.setBSONModule(BSON);

var doc = { int32: new Int32(10) };
// prints '{"int32":{"$numberInt":"10"}}'
console.log(EJSON.stringify(doc));

var text = '{"int32":{"$numberInt":"10"}}';
// prints { int32: { [String: '10'] _bsontype: 'Int32', value: '10' } }
console.log(EJSON.parse(text));

FAQ

What are the various files in dist?

mongodb-extjson.bundle.js is a bundled up version of the library that is suitable for inclusion in an HTML page via a <script> tag.
mongodb-extjson.esm.js is a rolled up version of the library that is suitable for interoperation with bundlers that work better with ES modules.
mongodb-extjson.browser.esm.js is similar to mongodb-extjson.esm.js but is ultimately intened for consumers producing browser bundles. It also pulls in any browser specific dependencies/code that may be needed.
mongodb-extjson.browser.umd.js is similar to the source code of this library but is ultimately intened for consumers producing browser bundlers expecting a UMD format. It also pulls in any browser specific dependencies/code that may be needed.