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