A blazing fast stringifier that safely handles circular objects
npm install fast-stringifyA tiny, blazing fast stringifier that safely handles circular objects.
The fastest way to stringify an object will always be the native JSON.stringify, but it does not support circular objects out of the box. If you need to stringify objects that have circular references, fast-stringify is there for you! It hsa a simple API to allow for several use-cases that JSON.stringify does not while also maintaining blazing fast performance compared to its peers.
- fast-stringify
- Table of contents
- Usage
- stringify
- Importing
- Benchmarks
- Simple objects
- Complex objects
- Circular objects
- Special objects
- Stable objects
- Stable circularobjects
``javascript
import { stringify } from 'fast-stringify';
const object = {
foo: 'bar',
deeply: {
recursive: {
object: {},
},
},
};
object.deeply.recursive.object = object.deeply.recursive;
console.log(stringify(object));
// {"foo":"bar","deeply":{"recursive":{"object":"[ref=.deeply.recursive]"}}}
`
`ts
interface Options {
circularReplacer?: (key: string, value: any, referenceKey: string) => any;
indent?: number;
replacer?: (key: string, value: any) => any;
stable?: boolean;
stabilizer?: (
entryA: { key: string; value: any },
entryB: { key: string; value: any },
stabilizerOptions: { get: (key: string) => any },
) => any;
}
function stringify(value: any, options?: Options): string;
`
Stringifies the object passed based on the options passed. The only required value is the value. The additional optons passed will customize how the string is compiled. Available options:
- replacer => function to customize how the non-circular value is stringified (see the documentation for JSON.stringify for more details)indent
- => number of spaces to indent the stringified object for pretty-printing (see the documentation for JSON.stringify for more details)circularReplacer
- => function to customize how the circular value is stringified (defaults to [ref=##] where ## is the referenceKey)referenceKey
- is a dot-separated key list reflecting the nested key the object was originally declared atstable
- => whether to sort the keys for stabilitystabilizer
- => function to customize how the stable object is sorted (only applies when stable is true)
`javascript
// ESM
import { stringify } from 'fast-stringify';
// CommonJS
const { stringify } = require('fast-stringify');
`
`bash`
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-stringify │ 1246981 │ '± 0.01%' │
│ faster-stable-stringify │ 1009331 │ '± 0.02%' │
│ fast-json-stable-stringify │ 918643 │ '± 0.02%' │
│ json-stringify-safe │ 736089 │ '± 0.02%' │
│ json-stable-stringify │ 655688 │ '± 0.02%' │
│ decircularize │ 434227 │ '± 0.03%' │
│ superjson │ 260614 │ '± 0.03%' │
│ json-cycle │ 5930 │ '± 0.06%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-stringify".
`bash`
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-stringify │ 182435 │ '± 0.04%' │
│ fast-json-stable-stringify │ 181922 │ '± 0.03%' │
│ faster-stable-stringify │ 164295 │ '± 0.03%' │
│ json-stringify-safe │ 133740 │ '± 0.04%' │
│ json-stable-stringify │ 110923 │ '± 0.04%' │
│ decircularize │ 60097 │ '± 0.05%' │
│ superjson │ 41319 │ '± 0.06%' │
│ json-cycle │ 959 │ '± 0.06%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-stringify".
`bash`
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-stringify │ 154881 │ '± 0.04%' │
│ fast-json-stable-stringify │ 148094 │ '± 0.04%' │
│ faster-stable-stringify │ 139589 │ '± 0.04%' │
│ json-stringify-safe │ 115500 │ '± 0.05%' │
│ json-stable-stringify │ 95238 │ '± 0.06%' │
│ decircularize │ 54071 │ '± 0.08%' │
│ superjson │ 32388 │ '± 0.08%' │
│ json-cycle │ 883 │ '± 0.12%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-stringify".
`bash`
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-stringify │ 68639 │ '± 0.06%' │
│ json-stringify-safe │ 52087 │ '± 0.06%' │
│ fast-json-stable-stringify │ 51025 │ '± 0.06%' │
│ faster-stable-stringify │ 46096 │ '± 0.07%' │
│ json-stable-stringify │ 33479 │ '± 0.08%' │
│ decircularize │ 20333 │ '± 0.11%' │
│ superjson │ 14914 │ '± 0.10%' │
│ json-cycle │ 341 │ '± 0.11%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-stringify".
`bash`
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-json-stable-stringify │ 673986 │ '± 0.02%' │
│ faster-stable-stringify │ 645572 │ '± 0.03%' │
│ fast-stringify │ 524383 │ '± 0.02%' │
│ json-stable-stringify │ 398551 │ '± 0.03%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-json-stable-stringify".
`bash``
┌────────────────────────────┬─────────┬─────────────────┐
│ (index) │ Ops/sec │ Margin of error │
├────────────────────────────┼─────────┼─────────────────┤
│ fast-json-stable-stringify │ 479587 │ '± 0.03%' │
│ faster-stable-stringify │ 477015 │ '± 0.03%' │
│ fast-stringify │ 380990 │ '± 0.03%' │
│ json-stable-stringify │ 288945 │ '± 0.03%' │
└────────────────────────────┴─────────┴─────────────────┘
Fastest was "fast-json-stable-stringify".