@teakit/circular-json v0.1.0

@teakit/circular-json

Serializes and deserializes otherwise valid JSON objects containing circular references into and from a specialized JSON format.

Notice: This module is fork from circular-json which is already deprecated, we don't change anything of it but remove the deprecate message. Teakit only use it to format and display application's configurations.

The future of this module is called flatted

Smaller, faster, and able to produce on average a reduced output too, flatted is the new, bloatless, ESM and CJS compatible, circular JSON parser.

It has now reached V1 and it implements the exact same JSON API.

Please note CircularJSON is in maintenance only and flatted is its successor.

A Working Solution To A Common Problem

A usage example:

var object = {};
object.arr = [
  object, object
];
object.arr.push(object.arr);
object.obj = object;

var serialized = CircularJSON.stringify(object);
// '{"arr":["~","~","~arr"],"obj":"~"}'
// NOTE: CircularJSON DOES NOT parse JS
// it handles receiver and reviver callbacks

var unserialized = CircularJSON.parse(serialized);
// { arr: [ [Circular], [Circular] ],
// obj: [Circular] }

unserialized.obj === unserialized;
unserialized.arr[0] === unserialized;
unserialized.arr.pop() === unserialized.arr;

A quick summary:

• new in version 0.5, you can specify a JSON parser different from JSON itself. CircularJSON.parser = ABetterJSON; is all you need.
• uses ~ as a special prefix symbol to denote which parent the reference belongs to (i.e. ~root~child1~child2)
• reasonably fast in both serialization and deserialization
• compact serialization for easier and slimmer transportation across environments
• tested and covered over nasty structures too
• compatible with all JavaScript engines

Node Installation & Usage

npm i @teakit/circular-json

'use strict';

var
  CircularJSON = require('@teakit/circular-json'),
  obj = { foo: 'bar' },
  str
;

obj.self = obj;
str = CircularJSON.stringify(obj);

There are no dependencies.

Browser Installation & Usage

• Global: <build/circular-json.js>
• AMD: <build/circular-json.amd.js>
• CommonJS: <build/circular-json.node.js>

(generated via gitstrap)

<script src="build/circular-json.js"></script>

'use strict';

var CircularJSON = window.CircularJSON
  , obj = { foo: 'bar' }
  , str
  ;

obj.self = obj;
str = CircularJSON.stringify(obj);

NOTE: Platforms without native JSON (i.e. MSIE <= 8) requires json3.js or similar.

It is also a bad idea to CircularJSON.parse(JSON.stringify(object)) because of those manipulation used in CircularJSON.stringify() able to make parsing safe and secure.

As summary: CircularJSON.parse(CircularJSON.stringify(object)) is the way to go, same is for JSON.parse(JSON.stringify(object)).

API

It's the same as native JSON, except the fourth parameter placeholder, which circular references to be replaced with "[Circular]" (i.e. for logging).

• CircularJSON.stringify(object, replacer, spacer, placeholder)
• CircularJSON.parse(string, reviver)

Bear in mind JSON.parse(CircularJSON.stringify(object)) will work but not produce the expected output.