json-stable-stringify

What is json-stable-stringify?

The json-stable-stringify npm package is used to convert a JavaScript object into a JSON string with a deterministic order of keys. This is particularly useful when you want to ensure that the string output is consistent for the same structural data, which is important for tasks like creating cryptographic hashes, caching, or simply when you need a stable serialization of JSON that you can compare.

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

Deterministic JSON.stringify

This feature allows you to serialize a JavaScript object into a JSON string with a consistent ordering of keys. This is useful when you need to compare JSON strings for equality or when you need to generate a hash from a JSON string and require that the string be the same for the same data.

{"result": "json-stable-stringify"}

Custom comparator

json-stable-stringify allows you to provide a custom comparison function to determine the order of keys. This is useful when you have specific requirements for the order of keys beyond simple alphabetical sorting.

{"result": "json-stable-stringify with custom comparator"}

Space argument for pretty-printing

The package also supports the 'space' argument like JSON.stringify, which allows you to pretty-print the output with indentation for better readability.

{"result": "json-stable-stringify with pretty-printing"}

Other packages similar to json-stable-stringify

fast-json-stable-stringify

This package offers similar functionality to json-stable-stringify but focuses on performance. It claims to be the fastest stable JSON.stringify available.

faster-stable-stringify

Similar to fast-json-stable-stringify, this package also aims to provide fast and stable JSON stringification. It compares to json-stable-stringify by offering a different balance of speed and features.

README

json-stable-stringify

deterministic version of JSON.stringify() so you can get a consistent hash from stringified results

You can also pass in a custom comparison function.

example

var stringify = require('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('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('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 b.key.localeCompare(a.key);
});

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('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}

space

If you specify opts.space, it will indent the output for pretty-printing. Valid values are strings (e.g. {space: \t}) or a number of spaces ({space: 3}).

For example:

var obj = { b: 1, a: { foo: 'bar', and: [1, 2, 3] } };

var s = stringify(obj, { space: '  ' });

console.log(s);

which outputs:

{
  "a": {
    "and": [
      1,
      2,
      3
    ],
    "foo": "bar"
  },
  "b": 1
}

replacer

The replacer parameter is a function opts.replacer(key, value) that behaves the same as the replacer from the core JSON object.

install

With npm do:

npm install json-stable-stringify

license

MIT

Changelog

v1.0.2 - 2022-11-07

Commits

• [eslint] fix indentation and whitespace c97e78c
• [eslint] more cleanup c162117
• [meta] add auto-changelog 83934ff
• [actions] add reusable workflows 7b24830
• [readme] rename, add badges 5433588
• [eslint] add eslint 7be6c27
• [meta] create FUNDING.yml; add funding in package.json 6edbece
• [meta] use npmignore to autogenerate an npmignore file b5d7d3a
• [Dev Deps] update tape 2200cf1
• [actions] update rebase action e41ac00
• [meta] update URLs f17e490
• Only apps should have lockfiles 4f052f4
• add breaking test (acyclic detected as cyclic) 7f5f443
• [meta] add safe-publish-latest ddb843f
• [Tests] add aud in posttest 245c9bf
• [Deps] update jsonify 7b79a68
• fix conflict e43ca2a