This library that provides a way to handle circular references when serializing and deserializing JSON objects. When serializing an object that has circular references, the default JSON.stringify() method will throw an error. CircularJSON provides a way to avoid this error by converting circular references to a stringified version of "[Circular]".

Installation

You can install using NPM or Yarn:

  npm i circular-to-json

  yarn add circular-to-json

Simple Usage

This package exports a CircularJSON object with two methods: stringify, parse and stringifyAndParse. Here's how you can use them:

Stringify

import CircularJSON from "circular-to-json";

const obj = { a: 1 };
obj.b = obj; // adding circular reference

const jsonString = CircularJSON.stringify(obj);

console.log(jsonString);

Output

'{"a":1,"b":{"[Circular]":true}}';

Parse

const jsonString = CircularJSON.stringify(obj);
const parsedObj = CircularJSON.parse(jsonString);
console.log(parsedObj);

Output

{ a: 1, b: [Circular] }

stringifyAndParse

stringifyAndParse method that combines the stringify and parse methods into a single operation.

const obj = { a: 1 };
obj.b = obj;

const parsedObj = CircularJSON.stringifyAndParse(obj);

Output

{ a: 1, b: [Circular] }

Other Usage

The stringify method takes an optional replacer function and an optional space parameter, which work the same way as the corresponding parameters in JSON.stringify.

stringify - space

const obj = {
  name: "John",
  age: 30,
  hobbies: ["reading", "running", "cooking"],
  address: {
    street: "123 Main St",
    city: "Anytown",
    state: "CA",
    zip: "12345"
  }
};

// Set the space parameter to '\t' to use a tab for indentation
const jsonStrWithTab = CircularJSON.stringify(obj, undefined, '\t');
console.log(jsonStrWithTab);

Output

{
	"name": "John",
	"age": 30,
	"hobbies": [
		"reading",
		"running",
		"cooking"
	],
	"address": {
		"street": "123 Main St",
		"city": "Anytown",
		"state": "CA",
		"zip": "12345"
	}
}

stringify - replacer

const obj = {
  name: "Alice",
  age: 30,
  children: [
    { name: "Bob", age: 5 },
    { name: "Charlie", age: 3 },
  ],
};

// Define a replacer function that converts all numbers to strings
const replacer = (key, value) => {
  if (typeof value === "number") {
    return value.toString();
  }
  return value;
};

const jsonString = CircularJSON.stringify(obj, replacer);

console.log(jsonString);

Output

{
  "name": "Alice",
  "age": "30",
  "children": [
    {
      "name": "Bob",
      "age": "5"
    },
    {
      "name": "Charlie",
      "age": "3"
    }
  ]
}

parse - reviver

The parse method takes an optional reviver function, which works the same way as the corresponding parameter in JSON.parse.

const jsonString =
  '{"name":"John Smith","age":30,"car":{"model":"Tesla","year":2022}}';

const reviver = (key, value) => {
  if (typeof value === "string" && key !== "") {
    return value.toUpperCase(); // convert all string values (except the root object) to uppercase
  }
  return value; // otherwise return the original value
};

const obj = JSON.parse(jsonString, reviver);

console.log(obj);

Output

{
  "name": "JOHN SMITH",
  "age": 30,
  "car": {
    "model": "TESLA",
    "year": 2022
  }
}

Contributing

circular-to-json is an open-source project, and we welcome contributions from the community.

Licence

CircularJSON is licensed under the MIT License.