• Stitch >
• Functions >
• Reference

JSON & BSON

Overview

Stitch functions include built-in global modules that allow you to process and convert between data formats. Each format supports various different data types and encodings.

Module	Description
JSON	Includes methods that convert between string and object representations of JSON data.
EJSON	Includes methods that convert between string and object representations of Extended JSON data.
BSON	Includes methods that create Binary JSON objects and convert between various BSON data types and encodings.

JSON (JavaScript Object Notation)

JSON is a standard data format that stores groups of key-value pairs and supports basic JavaScript types. For details on syntax and supported types, refer to the JSON specification.

Stitch exposes the standard JSON module in the global scope of every function. The module includes methods that convert between string and object representations of standard JSON objects.

JSON.parse(jsonString)

Parses the provided JSON string and converts it to a JavaScript object.

Parameter	Type	Description
jsonString	string	A serialized string representation of a standard JSON object.

Returns:A standard JavaScript object generated from the provided JSON string.

Example

copy

const jsonString = `{
  answer: 42,
  submittedAt: "2020-03-02T16:50:24.475Z"
}`;
const object = JSON.parse(jsonString);

JSON.stringify(object)

Serializes the provided JavaScript object to a JSON string.

Parameter	Type	Description
object	object	A standard JavaScript Object.

Returns:A string representation of the provided JavaScript object.

Example

copy

const object = {
  answer: 42,
  submittedAt: new Date("2020-03-02T16:46:47.977Z")
};
const jsonString = JSON.stringify(object);

EJSON (Extended JSON)

Extended JSON is a superset of standard JSON that adds additional support for types that are available in BSON but not included in the JSON specification.

Stitch exposes the EJSON module in the global scope of every function. This module is similar to the standard JSON module but preserves additional type information.

EJSON.parse(ejsonString)

Parses the provided EJSON string and converts it to a JavaScript object.

Parameter	Type	Description
ejsonString	string	A serialized string representation of an Extended JSON object.

Returns:A Javascript object representation of the provided EJSON string.

Example

copy

const ejsonString = `{
  answer: {
    "$numberLong": "42"
  },
  submittedAt: {
    "$date": {
      "$numberLong": "1583167607977"
    }
  }
}`;
const object = EJSON.parse(ejsonString);

EJSON.stringify(object)

Serializes the provided JavaScript object to an EJSON string.

Parameter	Type	Description
object	document	An EJSON object. The object may contain BSON types.

Returns:A string representation of the provided EJSON object.

Example

copy

const object = {
  answer: 42,
  submittedAt: new Date("2020-03-02T16:46:47.977Z")
};
const ejsonString = EJSON.stringify(object);

BSON (Binary JSON)

BSON is a data format that encodes binary representations of extended JSON objects. BSON includes additional data types beyond those in the JSON standard and provides a unified interface for converting data to and from binary representations. For more information, refer to the BSON specification.

Stitch exposes the BSON module in the global scope of every function. This module provides methods that allow you to create BSON objects and convert them to and from various data types and encodings.

MongoDB Documents are BSON

MongoDB stores all documents in BSON format, so you’ll use the BSON package most commonly when you run CRUD & Aggregation operations.

BSON.ObjectId

The BSON.ObjectId type represents a 12-byte MongoDB ObjectId identifier.

BSON.ObjectId(id)

Constructs a BSON.ObjectId object that encodes an ObjectId

Parameter	Type	Description
id	string	Optional. A 12-byte string or a string of 24 hex characters.

Returns:A BSON.ObjectId object that encodes the specified ObjectId string or a generated ObjectId string if none was specified.

Example

copy

const objectId = new BSON.ObjectId("5e58667d902d38559c802b13");
const generatedObjectId = new BSON.ObjectId();

BSON.BSONRegExp

The BSON.BSONRegExp type represents a regular expression. You can use a BSON.BSONRegExp object with the $regex query operator to perform a regular expression query on a MongoDB collection.

BSON.BSONRegExp(pattern, flags)

Constructs a BSON.BSONRegExp object from a regular expression string. You can optionally specify configuration flags.

Parameter	Type	Description
pattern	string	A regular expression pattern.
flags	string	Optional. One or more regular expression flags.

Returns:A BSON.BSONRegExp object that encodes the provided regular expression pattern and flags.

Example

copy

const regex = BSON.BSONRegExp("the great", "ig");

BSON.Binary

The BSON.Binary type represents a binary-encoded data string.

BSON.Binary.fromHex(hexString, subType)

Constructs a BSON.Binary object from data represented as a hexadecimal string.

Parameter	Type	Description
hexString	string	A byte aligned string of hexadecimal characters (0-9 and A-F).
subType	integer	Optional. The type of data encoded in the hexadecimal string. The value must be in the range 0-255 where 0, the default value, represents a generic binary. For a full list of supported subtypes, refer to the BSON specification.

Returns:A BSON.Binary object that encodes the provided hexadecimal string.

Example

copy

const binary = BSON.Binary.fromHex("54657374206d65737361676520706c656173652069676e6f7265=");

BSON.Binary.toHex()

Converts the BSON.Binary object into a hexadecimal string.

Returns:A hexadecimal string representation of the provided BSON.Binary object.

Example

copy

const binary = BSON.Binary.fromHex("54657374206d65737361676520706c656173652069676e6f7265=");
const hexString = binary.toHex();

BSON.Binary.fromBase64(base64String, subType)

Constructs a BSON.Binary object from data represented as a base64 string.

Parameter	Type	Description
base64String	string	A string of base64-encoded characters. String Padding The base64-encoded string must include either one or two equals signs (=), referred to as “padding”, at the end of the string. BSON.Binary.fromBase64() does not support unpadded strings.
subType	integer	Optional. The type of data encoded in the hexadecimal string. The value must be in the range 0-255 where 0, the default value, represents a generic binary. For a full list of supported subtypes, refer to the BSON specification.

Returns:A BSON.Binary object that encodes the provided base64 string.

Example

copy

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");

BSON.Binary.toBase64()

Converts the BSON.Binary object into a base64 string.

Returns:A base64 string representation of the BSON.Binary object.

Example

copy

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const base64String = binary.toBase64();

BSON.Binary.text()

Converts the BSON.Binary object into a UTF-8 string.

Returns:A UTF-8 string representation of the provided BSON.Binary object.

Example

copy

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const decodedString = binary.text();

BSON.MaxKey

The BSON.MaxKey type represents a value that compares higher than all other BSON values.

Example

copy

await collection.findOne({ date: { $lt: BSON.MaxKey } });

BSON.MinKey

The BSON.MinKey type represents a value that compares lower than all other BSON values.

Example

copy

await collection.findOne({ date: { $gt: BSON.MinKey } });

BSON.Int32

The BSON.Int32 type represents a 32-bit signed integer.

BSON.Int32(integer)

Constructs a BSON.Int32 object from a 32-bit number.

Parameter	Type	Description
low32	number	A 32-bit number.

Returns:A BSON.Int32 object that encodes the specified integer. Returns 0 if no arguments are supplied.

Example

copy

const int32 = BSON.Int32(42);

BSON.Long

The BSON.Long type represents a 64-bit signed integer.

BSON.Long(low32, high32)

Constructs a BSON.Long object from two 32-bit integers that represent the low 32 bits and the high 32 bits in the 64-bit Long integer.

Parameter	Type	Description
low32	integer	Optional. The long integer’s 32 low bits. These bits represent the least significant digits of the number.
high32	integer	Optional. The long integer’s 32 high bits. These bits represent the most significant digits of the number.

Returns:A BSON.Long object that encodes the specified integer. Returns 0 if no arguments are supplied.

BSON.Long encodes using the following formula:

(high32 * (2**32)) + low32

Example

copy

const long = BSON.Long(600206158, 342);

BSON.Double

The BSON.Double type represents a 64-bit (8-byte) floating point number.

Use Decimal128 for Money

BSON.Double is subject to floating point rounding errors, so it is not recommended for use cases where decimal values must round exactly, e.g. financial data. For these cases, use BSON.Decimal128 instead.

BSON.Double(double)

Constructs a BSON.Double object from a 64-bit decimal value.

Parameter	Type	Description
double	number	A 64-bit decimal value.

Returns:A BSON.Double object that encodes the specified double. Returns 0 if no argument is supplied.

Example

copy

const double = BSON.Double(1234.5678);

BSON.Decimal128

The BSON.Decimal128 type represents a 128-bit (16-byte) floating point number. This type is intended for use cases where decimal values must round exactly, e.g. financial data.

BSON.Decimal128.fromString(decimalString)

Constructs a BSON.Decimal128 from a string representation of a decimal number.

Parameter	Type	Description
decimalString	string	A string representing a decimal number, e.g. "1234.5678910123456".

Returns:A BSON.Decimal128 that encodes the provided decimal value.

Example

copy

const double = BSON.Decimal128.fromString("1234.5678910123456");

←   Context Modules Utility Packages  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.