EJSON

Documentation of EJSON, Meteor's JSON extension.

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

• Date (JavaScript Date)
• Binary (JavaScript Uint8Array or theresult of EJSON.newBinary)
• 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 dateand a binary buffer would be serialized in EJSON as:

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

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

Anywhere

EJSON.parse(str)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 412)

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

Arguments

• strString
• A string to parse into an EJSON value.

Anywhere

EJSON.stringify

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 394)

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

• valEJSON-able Object

• A value to stringify.

• options.indentBoolean, Integer, or String

• Indents objects andarrays for easy readability. When true, indents by 2 spaces; when aninteger, indents by that number of spaces; and when a string, uses thestring as the indentation pattern.

• options.canonicalBoolean

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

Anywhere

EJSON.fromJSONValue(val)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 371)

Deserialize an EJSON value from its plain JSON representation.

Arguments

• valJSON-compatible Object
• A value to deserialize into EJSON.

Anywhere

EJSON.toJSONValue(val)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 296)

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

Arguments

• valEJSON-able Object
• A value to serialize to plain JSON.

Anywhere

EJSON.equals(a, b, [options])

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 443)

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

• aEJSON-able Object
• bEJSON-able Object

Options

• 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. Thedefault is false.

Anywhere

EJSON.clone(val)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 551)

Return a deep copy of val.

Arguments

• valEJSON-able Object
• A value to copy.

Anywhere

EJSON.newBinary

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 615)

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

Arguments

• sizeNumber
• The number of bytes of binary data to allocate.

Buffers of binary data are represented by Uint8Array instances on JavaScriptplatforms that support them. On implementations of JavaScript that do notsupport Uint8Array, binary data buffers are represented by standard arrayscontaining numbers ranging from 0 to 255, and the $Uint8ArrayPolyfill keyset to true.

Anywhere

EJSON.isBinary(x)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 425)

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

Arguments

• xObject
• The variable to check.

Anywhere

EJSON.addType(name, factory)

import { EJSON } from 'meteor/ejson' (ejson/ejson.js, line 90)

Add a custom datatype to EJSON.

Arguments

• 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.

• 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.

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:

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 tomethods.
• storing your type client-side in Minimongo.
• allowing your type in Session variables.

Instances of your type must implement typeName andtoJSONValue methods, and may implementclone and equals methods if thedefault implementations are not sufficient.

Anywhere

EJSON.CustomType#typeName()

(ejson/ejson.js, line 28)

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

Anywhere

EJSON.CustomType#toJSONValue()

(ejson/ejson.js, line 38)

Serialize this instance into a JSON-compatible value.

For example, the toJSONValue method forMongo.ObjectID could be:

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

Anywhere

EJSON.CustomType#clone()

(ejson/ejson.js, line 46)

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 usetoJSONValue and the factory instead.

Anywhere

EJSON.CustomType#equals(other)

(ejson/ejson.js, line 55)

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

Arguments

• otherObject
• Another object to compare this to.

The equals method should define an equivalencerelation. It should havethe 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 theresult of calling toJSONValue instead.