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
Uint8Arrayor the result ofEJSON.newBinary) - Special numbers (JavaScript
NaN,Infinity, and-Infinity) - Regular expressions (JavaScript
RegExp) - User-defined types (see
EJSON.addType. For example,Mongo.ObjectIDis 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.
Parse a string into an EJSON value. Throws an error if the string is not valid EJSON.
Arguments
- str String
-
A string to parse into an EJSON value.
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
- val EJSON-able Object
-
A value to stringify.
- options.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. - options.canonical Boolean
-
When
true, stringifies keys in an object in sorted order.
Deserialize an EJSON value from its plain JSON representation.
Arguments
- val JSON-compatible Object
-
A value to deserialize into EJSON.
Serialize an EJSON-compatible value into its plain JSON representation.
Arguments
- val EJSON-able Object
-
A value to serialize to plain JSON.
EJSON.equals(a, b, [options])
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
Options
- 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 whenkeyOrderSensitiveisfalse. The default isfalse.
Allocate a new buffer of binary data that EJSON can serialize.
Arguments
- 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.
Returns true if x is a buffer of binary data, as returned from
EJSON.newBinary.
Arguments
- x Object
-
The variable to check.
EJSON.addType(name, factory)
Add a custom datatype to EJSON.
Arguments
- 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
typeNamemethod. - 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
toJSONValuemethod.
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 to methods.
- storing your type client-side in Minimongo.
- allowing your type in
Sessionvariables.
Instances of your type must implement typeName and
toJSONValue methods, and may implement
clone and equals methods if the
default implementations are not sufficient.
Return the tag used to identify this type. This must match the
tag used to register this type with
EJSON.addType.
Serialize this instance into a JSON-compatible value.
For example, the toJSONValue method for
Mongo.ObjectID could be:
function () {
return this.toHexString();
}
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.
Return true if other has a value equal to this; false
otherwise.
Arguments
- other Object
-
Another object to compare this to.
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
aandb:a.equals(b)if and only ifb.equals(a). - Transitivity - for any three instances
a,b, andc:a.equals(b)andb.equals(c)impliesa.equals(c).
If your type does not have an equals method, EJSON.equals will compare the
result of calling toJSONValue instead.