json-stringify-safe

What is json-stringify-safe?

The json-stringify-safe package is a JSON serialization library that can stringify objects with circular references without throwing an error. It is particularly useful when dealing with complex objects where standard JSON.stringify() would fail due to circularity.

What are json-stringify-safe's main functionalities?

Stringify with circular references

This feature allows you to serialize objects that contain circular references by replacing the circular reference with a placeholder string that indicates the path of the circularity.

{"str": "Circular reference example", "obj": {"a": "b", "c": {"d": "[Circular ~.obj]"}}}

Custom replacer function

json-stringify-safe allows you to specify a custom replacer function to selectively serialize object properties, similar to the second argument of JSON.stringify().

{"str": "Custom replacer example", "obj": {"a": "b", "c": "[Filtered]"}}

Custom indentation

The package also supports custom indentation for the output string, allowing for more readable serialized JSON if needed.

{
  "str": "Indented output example",
  "obj": {
    "a": "b",
    "c": "d"
  }
}

Other packages similar to json-stringify-safe

flatted

Flatted is a package that uses a similar approach to json-stringify-safe, but instead of replacing circular references with a placeholder, it flattens the structure into an array. This can be useful for certain serialization and deserialization needs.

json-cycle

json-cycle is another package that deals with circular references by encoding them using the Douglas Crockford's cycle.js algorithm. It can stringify and then restore objects with circular references to their original state.

safe-stable-stringify

safe-stable-stringify is a package that ensures deterministic serialization of objects, including those with circular references. It is similar to json-stringify-safe but also guarantees the order of keys, which can be important for hashing and caching.

README

json-stringify-safe

Like JSON.stringify, but doesn't throw on circular references.

Usage

Takes the same arguments as JSON.stringify.

var stringify = require('json-stringify-safe');
var circularObj = {};
circularObj.circularRef = circularObj;
circularObj.list = [ circularObj, circularObj ];
console.log(stringify(circularObj, null, 2));

Output:

{
  "circularRef": "[Circular]",
  "list": [
    "[Circular]",
    "[Circular]"
  ]
}

Details

stringify(obj, serializer, indent, decycler)

The first three arguments are the same as to JSON.stringify. The last is an argument that's only used when the object has been seen already.

The default decycler function returns the string '[Circular]'. If, for example, you pass in function(k,v){} (return nothing) then it will prune cycles. If you pass in function(k,v){ return {foo: 'bar'}}, then cyclical objects will always be represented as {"foo":"bar"} in the result.

stringify.getSerialize(serializer, decycler)

Returns a serializer that can be used elsewhere. This is the actual function that's passed to JSON.stringify.

Note that the function returned from getSerialize is stateful for now, so do not use it more than once.

Changelog

5.0.1 (May 19, 2015)

• Fixes stringify to only take ancestors into account when checking circularity.
  It previously assumed every visited object was circular which led to [false positives][issue9].
  Uses the tiny serializer I wrote for [Must.js][must] a year and a half ago.
• Fixes calling the replacer function in the proper context (thisArg).
• Fixes calling the cycleReplacer function in the proper context (thisArg).
• Speeds serializing by a factor of Big-O(h-my-god-it-linearly-searched-every-object) it had ever seen. Searching only the ancestors for a circular references speeds up things considerably.