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)

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.

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]"}}