strong-tie/inbound-calls

1# safe-stable-stringify2 3Safe, deterministic and fast serialization alternative to [JSON.stringify][].4Zero dependencies. ESM and CJS. 100% coverage.5 6Gracefully handles circular structures and bigint instead of throwing.7 8Optional custom circular values, deterministic behavior or strict JSON9compatibility check.10 11## stringify(value[, replacer[, space]])12 13The same as [JSON.stringify][].14 15* `value` {any}16* `replacer` {string[]|function|null}17* `space` {number|string}18* Returns: {string}19 20```js21const stringify = require('safe-stable-stringify')22 23const bigint = { a: 0, c: 2n, b: 1 }24 25stringify(bigint)26// '{"a":0,"b":1,"c":2}'27JSON.stringify(bigint)28// TypeError: Do not know how to serialize a BigInt29 30const circular = { b: 1, a: 0 }31circular.circular = circular32 33stringify(circular)34// '{"a":0,"b":1,"circular":"[Circular]"}'35JSON.stringify(circular)36// TypeError: Converting circular structure to JSON37 38stringify(circular, ['a', 'b'], 2)39// {40//   "a": 0,41//   "b": 142// }43```44 45## stringify.configure(options)46 47* `bigint` {boolean} If `true`, bigint values are converted to a number. Otherwise48  they are ignored. **Default:** `true`.49* `circularValue` {string|null|undefined|ErrorConstructor} Defines the value for50  circular references. Set to `undefined`, circular properties are not51  serialized (array entries are replaced with `null`). Set to `Error`, to throw52  on circular references. **Default:** `'[Circular]'`.53* `deterministic` {boolean|function} If `true` or a `Array#sort(comparator)`54  comparator method, guarantee a deterministic key order instead of relying on55  the insertion order. **Default:** `true`.56* `maximumBreadth` {number} Maximum number of entries to serialize per object57  (at least one). The serialized output contains information about how many58  entries have not been serialized. Ignored properties are counted as well59  (e.g., properties with symbol values). Using the array replacer overrules this60  option. **Default:** `Infinity`61* `maximumDepth` {number} Maximum number of object nesting levels (at least 1)62  that will be serialized. Objects at the maximum level are serialized as63  `'[Object]'` and arrays as `'[Array]'`. **Default:** `Infinity`64* `strict` {boolean} Instead of handling any JSON value gracefully, throw an65  error in case it may not be represented as JSON (functions, NaN, ...).66  Circular values and bigint values throw as well in case either option is not67  explicitly defined. Sets and Maps are not detected as well as Symbol keys!68  **Default:** `false`69* Returns: {function} A stringify function with the options applied.70 71```js72import { configure } from 'safe-stable-stringify'73 74const stringify = configure({75  bigint: true,76  circularValue: 'Magic circle!',77  deterministic: false,78  maximumDepth: 1,79  maximumBreadth: 480})81 82const circular = {83  bigint: 999_999_999_999_999_999n,84  typed: new Uint8Array(3),85  deterministic: "I don't think so",86}87circular.circular = circular88circular.ignored = true89circular.alsoIgnored = 'Yes!'90 91const stringified = stringify(circular, null, 4)92 93console.log(stringified)94// {95//     "bigint": 999999999999999999,96//     "typed": "[Object]",97//     "deterministic": "I don't think so",98//     "circular": "Magic circle!",99//     "...": "2 items not stringified"100// }101 102const throwOnCircular = configure({103  circularValue: Error104})105 106throwOnCircular(circular);107// TypeError: Converting circular structure to JSON108```109 110## Differences to JSON.stringify111 1121. _Circular values_ are replaced with the string `[Circular]` (configurable).1131. _Object keys_ are sorted instead of using the insertion order (configurable).1141. _BigInt_ values are stringified as regular number instead of throwing a115   TypeError (configurable).1161. _Boxed primitives_ (e.g., `Number(5)`) are not unboxed and are handled as117   regular object.118 119Those are the only differences to `JSON.stringify()`. This is a side effect free120variant and [`toJSON`][], [`replacer`][] and the [`spacer`][] work the same as121with `JSON.stringify()`.122 123## Performance / Benchmarks124 125Currently this is by far the fastest known stable (deterministic) stringify126implementation. This is especially important for big objects and TypedArrays.127 128(Dell Precision 5540, i7-9850H CPU @ 2.60GHz, Node.js 16.11.1)129 130```md131simple:   simple object x 3,463,894 ops/sec ±0.44% (98 runs sampled)132simple:   circular      x 1,236,007 ops/sec ±0.46% (99 runs sampled)133simple:   deep          x 18,942 ops/sec ±0.41% (93 runs sampled)134simple:   deep circular x 18,690 ops/sec ±0.72% (96 runs sampled)135 136replacer:   simple object x 2,664,940 ops/sec ±0.31% (98 runs sampled)137replacer:   circular      x 1,015,981 ops/sec ±0.09% (99 runs sampled)138replacer:   deep          x 17,328 ops/sec ±0.38% (97 runs sampled)139replacer:   deep circular x 17,071 ops/sec ±0.21% (98 runs sampled)140 141array:   simple object x 3,869,608 ops/sec ±0.22% (98 runs sampled)142array:   circular      x 3,853,943 ops/sec ±0.45% (96 runs sampled)143array:   deep          x 3,563,227 ops/sec ±0.20% (100 runs sampled)144array:   deep circular x 3,286,475 ops/sec ±0.07% (100 runs sampled)145 146indentation:   simple object x 2,183,162 ops/sec ±0.66% (97 runs sampled)147indentation:   circular      x 872,538 ops/sec ±0.57% (98 runs sampled)148indentation:   deep          x 16,795 ops/sec ±0.48% (93 runs sampled)149indentation:   deep circular x 16,443 ops/sec ±0.40% (97 runs sampled)150```151 152Comparing `safe-stable-stringify` with known alternatives:153 154```md155fast-json-stable-stringify x 18,765 ops/sec ±0.71% (94 runs sampled)156json-stable-stringify x 13,870 ops/sec ±0.72% (94 runs sampled)157fast-stable-stringify x 21,343 ops/sec ±0.33% (95 runs sampled)158faster-stable-stringify x 17,707 ops/sec ±0.44% (97 runs sampled)159json-stringify-deterministic x 11,208 ops/sec ±0.57% (98 runs sampled)160fast-safe-stringify x 21,460 ops/sec ±0.75% (99 runs sampled)161this x 30,367 ops/sec ±0.39% (96 runs sampled)162 163The fastest is this164```165 166The `fast-safe-stringify` comparison uses the modules stable implementation.167 168## Acknowledgements169 170Sponsored by [MaibornWolff](https://www.maibornwolff.de/) and [nearForm](http://nearform.com)171 172## License173 174MIT175 176[`replacer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The%20replacer%20parameter177[`spacer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The%20space%20argument178[`toJSON`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior179[JSON.stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify180