You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

131 lines
3.4 KiB

  1. # fast-json-stable-stringify
  2. Deterministic `JSON.stringify()` - a faster version of [@substack](https://github.com/substack)'s json-stable-strigify without [jsonify](https://github.com/substack/jsonify).
  3. You can also pass in a custom comparison function.
  4. [![Build Status](https://travis-ci.org/epoberezkin/fast-json-stable-stringify.svg?branch=master)](https://travis-ci.org/epoberezkin/fast-json-stable-stringify)
  5. [![Coverage Status](https://coveralls.io/repos/github/epoberezkin/fast-json-stable-stringify/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/fast-json-stable-stringify?branch=master)
  6. # example
  7. ``` js
  8. var stringify = require('fast-json-stable-stringify');
  9. var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
  10. console.log(stringify(obj));
  11. ```
  12. output:
  13. ```
  14. {"a":3,"b":[{"x":4,"y":5,"z":6},7],"c":8}
  15. ```
  16. # methods
  17. ``` js
  18. var stringify = require('fast-json-stable-stringify')
  19. ```
  20. ## var str = stringify(obj, opts)
  21. Return a deterministic stringified string `str` from the object `obj`.
  22. ## options
  23. ### cmp
  24. If `opts` is given, you can supply an `opts.cmp` to have a custom comparison
  25. function for object keys. Your function `opts.cmp` is called with these
  26. parameters:
  27. ``` js
  28. opts.cmp({ key: akey, value: avalue }, { key: bkey, value: bvalue })
  29. ```
  30. For example, to sort on the object key names in reverse order you could write:
  31. ``` js
  32. var stringify = require('fast-json-stable-stringify');
  33. var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
  34. var s = stringify(obj, function (a, b) {
  35. return a.key < b.key ? 1 : -1;
  36. });
  37. console.log(s);
  38. ```
  39. which results in the output string:
  40. ```
  41. {"c":8,"b":[{"z":6,"y":5,"x":4},7],"a":3}
  42. ```
  43. Or if you wanted to sort on the object values in reverse order, you could write:
  44. ```
  45. var stringify = require('fast-json-stable-stringify');
  46. var obj = { d: 6, c: 5, b: [{z:3,y:2,x:1},9], a: 10 };
  47. var s = stringify(obj, function (a, b) {
  48. return a.value < b.value ? 1 : -1;
  49. });
  50. console.log(s);
  51. ```
  52. which outputs:
  53. ```
  54. {"d":6,"c":5,"b":[{"z":3,"y":2,"x":1},9],"a":10}
  55. ```
  56. ### cycles
  57. Pass `true` in `opts.cycles` to stringify circular property as `__cycle__` - the result will not be a valid JSON string in this case.
  58. TypeError will be thrown in case of circular object without this option.
  59. # install
  60. With [npm](https://npmjs.org) do:
  61. ```
  62. npm install fast-json-stable-stringify
  63. ```
  64. # benchmark
  65. To run benchmark (requires Node.js 6+):
  66. ```
  67. node benchmark
  68. ```
  69. Results:
  70. ```
  71. fast-json-stable-stringify x 17,189 ops/sec ±1.43% (83 runs sampled)
  72. json-stable-stringify x 13,634 ops/sec ±1.39% (85 runs sampled)
  73. fast-stable-stringify x 20,212 ops/sec ±1.20% (84 runs sampled)
  74. faster-stable-stringify x 15,549 ops/sec ±1.12% (84 runs sampled)
  75. The fastest is fast-stable-stringify
  76. ```
  77. ## Enterprise support
  78. 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.
  79. ## Security contact
  80. To report a security vulnerability, please use the
  81. [Tidelift security contact](https://tidelift.com/security).
  82. Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.
  83. # license
  84. [MIT](https://github.com/epoberezkin/fast-json-stable-stringify/blob/master/LICENSE)