Cyclical-json NPM

Cyclical JSON:

JSON Sterilization for Cyclical Objects

JSON stringify will throw an error on cyclical objects. This module will sterilize and revive cyclical objects.

Files:

main => 'build/cyclical-json.js,'
min => 'build/cyclical-json.min.js'

API:

cyclicalJSON.stringify

String stringify (value[, replacer, space])

Parameters

value: The value to convert to a JSON string.

replacer | Optional: A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting/filtering the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string.

space | Optional: A String or Number object that's used to insert white space into the output JSON string for readability purposes. If this is a Number, it indicates the number of space characters to use as white space; this number is capped at 10 (if it is greater, the value is just 10). Values less than 1 indicate that no space should be used. If this is a String, the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null), no white space is used.

Return value: A JSON string representing the given value.

cyclicalJSON.parse

Object parse (text, reviver)

Parameters

text: The string to parse as JSON. See the JSON object for a description of JSON syntax.

reviver: | Optional: If a function, this prescribes how the value originally produced by parsing is transformed, before being returned.

Return value: The Object corresponding to the given JSON text.

Exceptions: Throws a SyntaxError exception if the string to parse is not valid JSON.

How it Works

cyclical-json@v2 implements a legend to minimize recycle time during parsing (as paths are looked-up instead of parsed) and minimize stringify output size (as numerous references to the same object will use the same legend entry)

Stringify

Values that are equivalent to null, or not typeof object, or are an instanceof Date, RegExp, String, Number, or Boolean, or those that include a toJSON method are passed through to the standard JSON.stringify function and then to the replacer. Other values, namely instanceof Array and regular JS Objects, will recursively step through the enumerable properties repeating the stringify algorithm for each. With each iteration the value and the absolute path is maintained in a WeakMap. When a redundant value is encountered the absolute path is stored in the legend and the legend index is used instead of the value. Absolute paths are arrays of keys, beginning with the base object, representing the path to the next value. The sterilized output will be a JSON string of an object representing the cyclical legend (legend), the object representing the input (main), and the version of cyclical-json used to produce the output (version). For example:

var a = {};

a.a = a;

cyclicalJSON.stringify(a);
// '{"legend":[[]],"main":{"a":"~0"},"version":"cyclical-json@2.0.0"}'

var b = {};
var c = {val: 123};

c.c = c;
b.c = c;

cyclicalJSON.stringify(b);
// '{"legend":[["c"]],"main":{"c":{"val":123,"c":"~0"}},"version":"cyclical-json@2.0.0"}'

var d = [];
var e = {val: true};

e.e = e;
d.push(e);

cyclicalJSON.stringify(d);
// '{"legend":[["0"]],"main":[{"val":true,"e":"~0"}],"version":"cyclical-json@2.0.0"}'

To maintain strings with a leading ~, cyclicalJSON.stringify will append a literal ~ to the begining of the string. So, for example:

var a = '~';

cyclicalJSON.stringify(a);
// '{"legend":[],"main":"~~","version":"cyclical-json@2.0.0"}'

var b = {a: '~'};

b.b = b;

cyclicalJSON.stringify(b);
// '{"legend":[[]],"main":{"a":"~~","b":"~0"},"version":"cyclical-json@2.0.0"}'

Parse

JSON.parse is used under the hood with a recycling algorithm used in a post-processing step. Regular JSON strings can be parsed by cyclicalJSON.parse, however caution should be used if the regular JSON string resembles a cyclicalJSON string (is an object with legend, main, and version properties), as cyclicalJSON might interpret this as a cyclicalJSON string instead. The reviver is applied during the JSON.parse step with the exception of special strings (those representing an object path, ie: '"~0"')and specialLiteral strings (those representing a literal string, ie: '"~~this~is~a~string~"'). The recycle algorithm then steps through the enumerable properties of the object in search for special strings and specialLiteral strings. When special strings are found the legend is used to look-up the path, which is then used to reference the appropriate location within the root object. When specialLiteral strings are encountered they are converted back to their original form and passed through the client reviver function. For example:

var a = '{"legend":[[],[0]],"main":[{"val":"~0"},"~~this~is~a~string~","~1"],"version":"cyclical-json@2.0.0"}'

cyclicalJSON.parse(a);
// [{val: [Circular]}, '~this~is~a~string~', {val: [Circular]}]