Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


JSON does not handle circular references. Now it does

Subscribe to updates I use circular-json

Statistics on circular-json

Number of watchers on Github 334
Number of open issues 1
Average time to close an issue about 2 months
Main language JavaScript
Average time to merge a PR about 11 hours
Open pull requests 0+
Closed pull requests 1+
Last commit over 2 years ago
Repo Created over 7 years ago
Repo Last Updated over 2 years ago
Size 2.04 MB
Organization / Authorwebreflection
Page Updated
Do you use circular-json? Leave a review!
View circular-json activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating circular-json for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


donate Downloads Build Status Coverage Status

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

A Working Solution To A Common Problem

A usage example:

var object = {};
object.arr = [
  object, object
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 install --save circular-json
'use strict';

  CircularJSON = require('circular-json'),
  obj = { foo: 'bar' },

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

There are no dependencies.

Browser Installation & Usage

  • Global:
  • AMD:
  • CommonJS:

(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)).


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.

Similar Libraries

Why Not the @izs One

The module json-stringify-safe seems to be for console.log() but it's completely pointless for JSON.parse(), being latter one unable to retrieve back the initial structure. Here an example:

// a logged object with circular references
  "circularRef": "[Circular]",
  "list": [
// what do we do with above output ?

Just type this in your node console: var o = {}; o.a = o; console.log(o);. The output will be { a: [Circular] } ... good, but that ain't really solving the problem.

However, if that's all you need, the function used to create that kind of output is probably faster than CircularJSON and surely fits in less lines of code.

Why Not {{put random name}} Solution

So here the thing: circular references can be wrong but, if there is a need for them, any attempt to ignore them or remove them can be considered just a failure.

Not because the method is bad or it's not working, simply because the circular info, the one we needed and used in the first place, is lost!

In this case, CircularJSON does even more than just solve circular and recursions: it maps all same objects so that less memory is used as well on deserialization as less bandwidth too! It's able to redefine those references back later on so the way we store is the way we retrieve and in a reasonably performant way, also trusting the snappy and native JSON methods to iterate.

circular-json questions on Stackoverflow (View All Questions)
  • Passing circular JSON to cluster in node
  • Accessing circular JSON structure
  • JavaScript: Deep Copy Circular JSON
  • Google Realtime circular JSON error when indexReference stored in collaborative map only when contained in an object
  • How to stringify circular JSON object and save it to file?
  • Circular Json serializing
  • how to stringify circular JSON object?
  • how to clone a circular JSON in nodejs
  • Can't solve my converting circular JSON error
circular-json list of languages used
Other projects in JavaScript