EJSON is an extension of JSON to support more types. It supports all JSON-safe types, as well as:
Date
)Uint8Array
or the result of EJSON.newBinary
)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:
{ "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(str)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 407) Parse a string into an EJSON value. Throws an error if the string is not valid EJSON.
str
String A string to parse into an EJSON value.
EJSON.stringify(val, [options])
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 389) 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
.
val
EJSON-able Object A value to stringify.
indent
Boolean, 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.
canonical
Boolean When true
, stringifies keys in an object in sorted order.
EJSON.fromJSONValue(val)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 366) Deserialize an EJSON value from its plain JSON representation.
val
JSON-compatible Object A value to deserialize into EJSON.
EJSON.toJSONValue(val)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 291) Serialize an EJSON-compatible value into its plain JSON representation.
val
EJSON-able Object A value to serialize to plain JSON.
EJSON.equals(a, b, [options])
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 438) 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.
keyOrderSensitive
Boolean 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
.
EJSON.clone(val)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 546) Return a deep copy of val
.
val
EJSON-able Object A value to copy.
EJSON.newBinary
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 610) Allocate a new buffer of binary data that EJSON can serialize.
size
Number The number of bytes of binary data to allocate.
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(x)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 420) Returns true if x
is a buffer of binary data, as returned from EJSON.newBinary
.
x
Object The variable to check.
EJSON.addType(name, factory)
import { EJSON } from 'meteor/ejson'
(ejson/ejson.js, line 85) Add a custom datatype to EJSON.
name
String 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.
factory
Function 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:
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.
EJSON.CustomType#typeName()
Return the tag used to identify this type. This must match the tag used to register this type with EJSON.addType
.
EJSON.CustomType#toJSONValue()
Serialize this instance into a JSON-compatible value.
For example, the toJSONValue
method for Mongo.ObjectID
could be:
function () { return this.toHexString(); }
EJSON.CustomType#clone()
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.
EJSON.CustomType#equals(other)
Return true
if other
has a value equal to this
; false
otherwise.
other
Object Another object to compare this to.
The equals
method should define an equivalence relation. It should have the following properties:
a
: a.equals(a)
must be true.a
and b
: a.equals(b)
if and only if b.equals(a)
.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.
© 2011–2017 Meteor Development Group, Inc.
Licensed under the MIT License.
https://docs.meteor.com/api/ejson.html