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

const stringify = require('json-stable-stringify');

const 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

const stringify = require('json-stable-stringify')

const 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 }, { get(key): value })

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

const stringify = require('json-stable-stringify');

const obj = { c: 8, b: [{ z: 6, y: 5, x: 4 },7], a: 3 };

const 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:

const stringify = require('json-stable-stringify');

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

const 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}

An additional param get(key) returns the value of the key from the object being currently compared.

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:

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

const 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.1.1 - 2024-01-16

Fixed

• [Performance] use an array join instead of a string. #9

Commits

• [readme] replaced var with const e22d419
• [Dev Deps] update aud, tape dc26af2