Skip to content
This repository has been archived by the owner on Feb 3, 2022. It is now read-only.

mongodb-js/mongodb-extjson

Repository files navigation

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.