fast-json-stable-stringify

What is fast-json-stable-stringify?

The fast-json-stable-stringify npm package is used to stringify JSON objects in a deterministic order, which is useful for tasks such as creating consistent hashes from JSON objects or ensuring consistent outputs in distributed systems. Unlike the native JSON.stringify, it guarantees the order of keys in the output string.

What are fast-json-stable-stringify's main functionalities?

Deterministic JSON.stringify

This feature allows you to convert a JSON object into a string with keys sorted in a consistent order. The code sample shows the output of stringifying an object with unordered keys.

{"c":6,"b":[4,5],"a":3}

Custom comparator

This feature enables the use of a custom comparison function to determine the order of keys. The code sample demonstrates the output when a custom comparator is used to sort keys alphabetically.

{"a":3,"b":[4,5],"c":6}

Other packages similar to fast-json-stable-stringify

json-stable-stringify

This package offers similar functionality to fast-json-stable-stringify, providing a deterministic version of JSON.stringify. It is an earlier and more widely used package, but fast-json-stable-stringify claims to have performance improvements.

json-stable-stringify-without-jsonify

Similar to fast-json-stable-stringify, this package provides deterministic JSON stringification. It differs in that it does not include the jsonify dependency, which may be beneficial for certain build environments or for those looking to minimize their dependency tree.

README

fast-json-stable-stringify

Deterministic JSON.stringify() - a faster version of @substack's json-stable-strigify without jsonify.

You can also pass in a custom comparison function.

example

var stringify = require('fast-json-stable-stringify');
var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
console.log(stringify(obj));

output:

{"a":3,"b":[{"x":4,"y":5,"z":6},7],"c":8}

methods

var stringify = require('fast-json-stable-stringify')

var str = stringify(obj, opts)

Return a deterministic stringified string str from the object obj.

options

cmp

If opts is given, you can supply an opts.cmp to have a custom comparison function for object keys. Your function opts.cmp is called with these parameters:

opts.cmp({ key: akey, value: avalue }, { key: bkey, value: bvalue })

For example, to sort on the object key names in reverse order you could write:

var stringify = require('fast-json-stable-stringify');

var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
var s = stringify(obj, function (a, b) {
    return a.key < b.key ? 1 : -1;
});
console.log(s);

which results in the output string:

{"c":8,"b":[{"z":6,"y":5,"x":4},7],"a":3}

Or if you wanted to sort on the object values in reverse order, you could write:

var stringify = require('fast-json-stable-stringify');

var obj = { d: 6, c: 5, b: [{z:3,y:2,x:1},9], a: 10 };
var s = stringify(obj, function (a, b) {
    return a.value < b.value ? 1 : -1;
});
console.log(s);

which outputs:

{"d":6,"c":5,"b":[{"z":3,"y":2,"x":1},9],"a":10}

cycles

Pass true in opts.cycles to stringify circular property as __cycle__ - the result will not be a valid JSON string in this case.

TypeError will be thrown in case of circular object without this option.

install

With npm do:

npm install fast-json-stable-stringify

benchmark

To run benchmark (requires Node.js 6+):

node benchmark

Results:

fast-json-stable-stringify x 17,189 ops/sec ±1.43% (83 runs sampled)
json-stable-stringify x 13,634 ops/sec ±1.39% (85 runs sampled)
fast-stable-stringify x 20,212 ops/sec ±1.20% (84 runs sampled)
faster-stable-stringify x 15,549 ops/sec ±1.12% (84 runs sampled)
The fastest is fast-stable-stringify

Enterprise support

fast-json-stable-stringify package is a part of Tidelift enterprise subscription - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.

Security contact

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.

license

MIT