README.md (3517B)
1 # fast-json-stable-stringify 2 3 Deterministic `JSON.stringify()` - a faster version of [@substack](https://github.com/substack)'s json-stable-strigify without [jsonify](https://github.com/substack/jsonify). 4 5 You can also pass in a custom comparison function. 6 7 [](https://travis-ci.org/epoberezkin/fast-json-stable-stringify) 8 [](https://coveralls.io/github/epoberezkin/fast-json-stable-stringify?branch=master) 9 10 # example 11 12 ``` js 13 var stringify = require('fast-json-stable-stringify'); 14 var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 }; 15 console.log(stringify(obj)); 16 ``` 17 18 output: 19 20 ``` 21 {"a":3,"b":[{"x":4,"y":5,"z":6},7],"c":8} 22 ``` 23 24 25 # methods 26 27 ``` js 28 var stringify = require('fast-json-stable-stringify') 29 ``` 30 31 ## var str = stringify(obj, opts) 32 33 Return a deterministic stringified string `str` from the object `obj`. 34 35 36 ## options 37 38 ### cmp 39 40 If `opts` is given, you can supply an `opts.cmp` to have a custom comparison 41 function for object keys. Your function `opts.cmp` is called with these 42 parameters: 43 44 ``` js 45 opts.cmp({ key: akey, value: avalue }, { key: bkey, value: bvalue }) 46 ``` 47 48 For example, to sort on the object key names in reverse order you could write: 49 50 ``` js 51 var stringify = require('fast-json-stable-stringify'); 52 53 var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 }; 54 var s = stringify(obj, function (a, b) { 55 return a.key < b.key ? 1 : -1; 56 }); 57 console.log(s); 58 ``` 59 60 which results in the output string: 61 62 ``` 63 {"c":8,"b":[{"z":6,"y":5,"x":4},7],"a":3} 64 ``` 65 66 Or if you wanted to sort on the object values in reverse order, you could write: 67 68 ``` 69 var stringify = require('fast-json-stable-stringify'); 70 71 var obj = { d: 6, c: 5, b: [{z:3,y:2,x:1},9], a: 10 }; 72 var s = stringify(obj, function (a, b) { 73 return a.value < b.value ? 1 : -1; 74 }); 75 console.log(s); 76 ``` 77 78 which outputs: 79 80 ``` 81 {"d":6,"c":5,"b":[{"z":3,"y":2,"x":1},9],"a":10} 82 ``` 83 84 ### cycles 85 86 Pass `true` in `opts.cycles` to stringify circular property as `__cycle__` - the result will not be a valid JSON string in this case. 87 88 TypeError will be thrown in case of circular object without this option. 89 90 91 # install 92 93 With [npm](https://npmjs.org) do: 94 95 ``` 96 npm install fast-json-stable-stringify 97 ``` 98 99 100 # benchmark 101 102 To run benchmark (requires Node.js 6+): 103 ``` 104 node benchmark 105 ``` 106 107 Results: 108 ``` 109 fast-json-stable-stringify x 17,189 ops/sec ±1.43% (83 runs sampled) 110 json-stable-stringify x 13,634 ops/sec ±1.39% (85 runs sampled) 111 fast-stable-stringify x 20,212 ops/sec ±1.20% (84 runs sampled) 112 faster-stable-stringify x 15,549 ops/sec ±1.12% (84 runs sampled) 113 The fastest is fast-stable-stringify 114 ``` 115 116 117 ## Enterprise support 118 119 fast-json-stable-stringify package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-fast-json-stable-stringify?utm_source=npm-fast-json-stable-stringify&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers. 120 121 122 ## Security contact 123 124 To report a security vulnerability, please use the 125 [Tidelift security contact](https://tidelift.com/security). 126 Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues. 127 128 129 # license 130 131 [MIT](https://github.com/epoberezkin/fast-json-stable-stringify/blob/master/LICENSE)