JSPON - JavaScript Persistent Object Notation

If you have seen the following error "TypeError: Converting circular structure to JSON" or similar, you are in the right place. JSON by default can't process circular structures in objects. This code puts a wrapper around your JSON framework of choice and helps the JSON framework process cyclic objects. It will work with non-cyclic objects as well. It will use the standard JSON.parse and JSON.stringify by default unless you set it to use a different JSON framework.

This code offers a lot of flexibility while maintaining excellent speed (see Performance Results below). It supports id referencing and JSONPath referencing, increasing compatibility with other jspon frameworks in other programming languages including JSON.NET preserve reference options. In most cases, JSPON's output is smaller than regular JSON, helping you push smaller payloads over the network. This code will work in Firefox, >= IE8, Chrome, and Nodejs.

Performance Results (using Benchmark.js)

Node.js	1 Mock Object	jspon (Id Referencing) x 17,916 ops/sec ±1.49% (87 runs sampled) jspon (JsonPath Referencing) x 22,587 ops/sec ±0.57% (96 runs sampled) Douglas Crockford's cycle#js (JsonPath Referencing) x 15,737 ops/sec ±1.75% (86 runs sampled) npm circular-json x 9,556 ops/sec ±0.90% (87 runs sampled) Fastest is jspon (JsonPath Referencing)
	20 Mock Objects	jspon (Id Referencing) x 1,089 ops/sec ±1.27% (91 runs sampled) jspon (JsonPath Referencing) x 1,290 ops/sec ±0.77% (94 runs sampled) Douglas Crockford's cycle#js (JsonPath Referencing) x 933 ops/sec ±1.25% (88 runs sampled) npm circular-json x 475 ops/sec ±1.16% (85 runs sampled) Fastest is jspon (JsonPath Referencing)

Installation

Using NPM

``
npm i --save jspon
`

Browser
`
Download browser/jspon.js or es_modules/jspon.js from https://github.com/mdavisJr/JSPON-For-JavaScript or use browserify.
`

Setting the JSPON Settings

Only call the setSettings method if you need settings different than the defaults below.


JSPON.setSettings(object); Available settings below.

Field	Data Type	Description	Default Value
idFieldName	string	This option turns on id referencing and allows you to specify the id property name that will be used to track unique objects. The id property name will only show up in the JSON string and will not show up in the object. If this option is set, jsonPathRoot setting will be ignored. It can not be a property name that exist in your objects.
preserveArrays	boolean	Decides whether or not to preserve references to arrays.	true
jsonPathRoot	string	Allows you to choose what the JSONPath root is.	$
jsonPathFormat	string	Valid values are DotNotation or BracketNotation. jsonPath Dot-Notation: $.children[0].name jsonPath Bracket-Notation: $['children'][0]['name']	DotNotation
jsonParser	function(str)	Allows you to set your JSON parser of choice Examples: JSPON.setSettings({jsonParser: CustomJSON.parse}); --or-- JSPON.setSettings({jsonParser: function(str) {      return JSON.parse(str, function(){           ...      }); });	JSON.parse
jsonStringifier	function(obj)	Allows you to set your JSON stringifier of choice Examples: JSPON.setSettings({jsonStringifier: CustomJSON.stringify }); --or-- JSPON.setSettings({jsonStringifier: function(obj) {      return JSON.stringify(obj, null, 5); });	JSON.stringify

Examples (Node.js)

Default Settings jsonPath reference with preserveArrays = true
`
const JSPON = require('jspon');

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"name":"parent","children":[{"name":"John","parent":{"$ref":"$"}},{"name":"Jane","parent":{"$ref":"$"}}],"childrenCopy":{"$ref":"$.children"},"child1":{"$ref":"$.children[0]"},"child2":{"$ref":"$.children[1]"}}
`
jsonPath reference with preserveArrays = false
`
const JSPON = require('jspon');
JSPON.setSettings({ preserveArrays: false });

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"name":"parent","children":[{"name":"John","parent":{"$ref":"$"}},{"name":"Jane","parent":{"$ref":"$"}}],"childrenCopy":[{"$ref":"$.children[0]"},{"$ref":"$.children[1]"}],"child1":{"$ref":"$.children[0]"},"child2":{"$ref":"$.children[1]"}}
`
Id reference with preserveArrays = true
`
const JSPON = require('jspon');
JSPON.setSettings({ idFieldName: '$id' });

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"$id":1,"name":"parent","children":{"$values":[{"$id":3,"name":"John","parent":{"$ref":1}},{"$id":4,"name":"Jane","parent":{"$ref":1}}],"$id":2},"childrenCopy":{"$ref":2},"child1":{"$ref":3},"child2":{"$ref":4}}
`
Id reference with preserveArrays = false
`
const JSPON = require('jspon');
JSPON.setSettings({ idFieldName: '$id', preserveArrays: false });

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"$id":1,"name":"parent","children":[{"$id":2,"name":"John","parent":{"$ref":1}},{"$id":3,"name":"Jane","parent":{"$ref":1}}],"childrenCopy":[{"$ref":2},{"$ref":3}],"child1":{"$ref":2},"child2":{"$ref":3}}
`
jsonPath reference with preserveArrays = true and jsonPathFormat = Bracket-Notation
`
const JSPON = require('jspon');
JSPON.setSettings({ jsonPathFormat: 'BracketNotation' });

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"name":"parent","children":[{"name":"John","parent":{"$ref":"$"}},{"name":"Jane","parent":{"$ref":"$"}}],"childrenCopy":{"$ref":"$['children']"},"child1":{"$ref":"$['children'][0]"},"child2":{"$ref":"$['children'][1]"}}
`
jsonPath reference with preserveArrays = false and jsonPathFormat = Bracket-Notation
`
const JSPON = require('jspon');
JSPON.setSettings({ preserveArrays: false, jsonPathFormat: 'BracketNotation' });

var json = JSPON.stringify(getObjWithCircularRef());

var obj = JSPON.parse(json);

//Value of json variable
//{"name":"parent","children":[{"name":"John","parent":{"$ref":"$"}},{"name":"Jane","parent":{"$ref":"$"}}],"childrenCopy":[{"$ref":"$['children'][0]"},{"$ref":"$['children'][1]"}],"child1":{"$ref":"$['children'][0]"},"child2":{"$ref":"$['children'][1]"}}
``