Skip to content

EJSON

EJSON is an extension of JSON to support more types. It supports all JSON-safe types, as well as:

  • Date (JavaScript Date)
  • Binary (JavaScript Uint8Array or the result of EJSON.newBinary)
  • Special numbers (JavaScript NaN, Infinity, and -Infinity)
  • Regular expressions (JavaScript RegExp)
  • User-defined types (see EJSON.addType. For example, Mongo.ObjectID is implemented this way.)

All EJSON serializations are also valid JSON. For example an object with a date and a binary buffer would be serialized in EJSON as:

json
{
  "d": { "$date": 1358205756553 },
  "b": { "$binary": "c3VyZS4=" }
}

Meteor supports all built-in EJSON data types in publishers, method arguments and results, Mongo databases, and Session variables.

EJSON.parse

Summary:

Parse a string into an EJSON value. Throws an error if the string is not valid EJSON.

Arguments:

Source code
NameTypeDescriptionRequired
strString

A string to parse into an EJSON value.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.parse();
  "str"
);

EJSON.stringify

Summary:

Serialize a value to a string. For EJSON values, the serialization fully represents the value. For non-EJSON values, serializes the same way as JSON.stringify.

Arguments:

Source code
NameTypeDescriptionRequired
valEJSON

A value to stringify.

Yes
optionsObjectNo
options.indentBoolean, Integer or String

Indents objects and arrays for easy readability. When true, indents by 2 spaces; when an integer, indents by that number of spaces; and when a string, uses the string as the indentation pattern.

No
options.canonicalBoolean

When true, stringifies keys in an object in sorted order.

No
js
import { EJSON } from "meteor/ejson";

EJSON.stringify(
  { num: 42, someProp: "foo" },
  options // this param is optional
);

EJSON.fromJSONValue

Summary:

Deserialize an EJSON value from its plain JSON representation.

Arguments:

Source code
NameTypeDescriptionRequired
valJSONCompatible

A value to deserialize into EJSON.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.fromJSONValue();
 { num:  42 , someProp:  "foo" }
);

EJSON.toJSONValue

Summary:

Serialize an EJSON-compatible value into its plain JSON representation.

Arguments:

Source code
NameTypeDescriptionRequired
valEJSON

A value to serialize to plain JSON.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.toJSONValue();
 { num:  42 , someProp:  "foo" }
);

EJSON.equals

Summary:

Return true if a and b are equal to each other. Return false otherwise. Uses the equals method on a if present, otherwise performs a deep comparison.

Arguments:

Source code
NameTypeDescriptionRequired
aEJSON----Yes
bEJSON----Yes
optionsObjectNo

Options:

NameTypeDescriptionRequired
keyOrderSensitiveBoolean

Compare in key sensitive order, if supported by the JavaScript implementation. For example, {a: 1, b: 2} is equal to {b: 2, a: 1} only when keyOrderSensitive is false. The default is false.

No
js
import { EJSON } from "meteor/ejson";


const result = EJSON.equals();
 { num:  42 , someProp:  "foo" },
{ num: 42 , someProp: "foo" },

options, // this param is optional
);

EJSON.clone

Summary:

Return a deep copy of val.

Arguments:

Source code
NameTypeDescriptionRequired
valEJSON

A value to copy.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.clone();
 { num:  42 , someProp:  "foo" }
);

EJSON.newBinary

Summary:

Allocate a new buffer of binary data that EJSON can serialize.

Arguments:

Source code
NameTypeDescriptionRequired
sizeNumber

The number of bytes of binary data to allocate.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.newBinary();
  42
);

Buffers of binary data are represented by Uint8Array instances on JavaScript platforms that support them. On implementations of JavaScript that do not support Uint8Array, binary data buffers are represented by standard arrays containing numbers ranging from 0 to 255, and the $Uint8ArrayPolyfill key set to true.

EJSON.isBinary

Summary:

Returns true if x is a buffer of binary data, as returned from EJSON.newBinary.

Arguments:

Source code
NameTypeDescriptionRequired
xObject

The variable to check.

Yes
js
import { EJSON } from "meteor/ejson";


const result = EJSON.isBinary();
  x
);

EJSON.addType

Summary:

Add a custom datatype to EJSON.

Arguments:

Source code
NameTypeDescriptionRequired
nameString

A tag for your custom type; must be unique among custom data types defined in your project, and must match the result of your type's typeName method.

Yes
factoryfunction

A function that deserializes a JSON-compatible value into an instance of your type. This should match the serialization performed by your type's toJSONValue method.

Yes

The factory function passed to the EJSON.addType method should create an instance of our custom type and initialize it with values from an object passed as the first argument of the factory function. Here is an example:

js
class Distance {
  constructor(value, unit) {
    this.value = value;
    this.unit = unit;
  }

  // Convert our type to JSON.
  toJSONValue() {
    return {
      value: this.value,
      unit: this.unit,
    };
  }

  // Unique type name.
  typeName() {
    return "Distance";
  }
}

EJSON.addType("Distance", function fromJSONValue(json) {
  return new Distance(json.value, json.unit);
});

EJSON.stringify(new Distance(10, "m"));
// Returns '{"$type":"Distance","$value":{"value":10,"unit":"m"}}'

When you add a type to EJSON, Meteor will be able to use that type in:

  • publishing objects of your type if you pass them to publish handlers.
  • allowing your type in the return values or arguments to methods.
  • storing your type client-side in Minimongo.
  • allowing your type in Session variables.

Instances of your type must implement typeName and toJSONValue methods, and may implement clone and equals methods if the default implementations are not sufficient.

CustomType.typeName

Summary:

Return the tag used to identify this type. This must match the tag used to register this type with EJSON.addType.

CustomType.toJSONValue

Summary:

Serialize this instance into a JSON-compatible value.

For example, the toJSONValue method for Mongo.ObjectID could be:

js
function () {
  return this.toHexString();
}

CustomType.clone

Summary:

Return a value r such that this.equals(r) is true, and modifications to r do not affect this and vice versa.

If your type does not have a clone method, EJSON.clone will use toJSONValue and the factory instead.

CustomType.equals

Summary:

Return true if other has a value equal to this; false otherwise.

Arguments:

Source code
NameTypeDescriptionRequired
otherObject

Another object to compare this to.

Yes

The equals method should define an equivalence relation. It should have the following properties:

  • Reflexivity - for any instance a: a.equals(a) must be true.
  • Symmetry - for any two instances a and b: a.equals(b) if and only if b.equals(a).
  • Transitivity - for any three instances a, b, and c: a.equals(b) and b.equals(c) implies a.equals(c).

If your type does not have an equals method, EJSON.equals will compare the result of calling toJSONValue instead.