Fast Safe Stringify

2.1.1 · active · verified Sun Apr 19

fast-safe-stringify is a utility library designed for safely and quickly serializing JavaScript objects into JSON strings. It provides a robust alternative to the native `JSON.stringify`, specifically excelling at gracefully handling circular references within objects without throwing a `TypeError`. Instead, it intelligently replaces circular structures with a `[Circular]` string or `[...]` when configured limits are reached. The current stable version is 2.1.1, with recent updates (v2.1.0 and v2.1.1) introducing and refining `depthLimit` and `edgesLimit` options to prevent excessive recursion in complex objects. The library also offers a `stableStringify` function, which guarantees a deterministic output order for object keys, enhancing reproducibility. It is actively maintained and ships with TypeScript type definitions, making it suitable for modern JavaScript and TypeScript environments where predictable serialization of potentially self-referential data structures is crucial, such as in logging or API responses.

Common errors

```
TypeError: Converting circular structure to JSON
```
cause Attempting to serialize an object containing self-referencing properties or loops using `JSON.stringify`.

fix Replace `JSON.stringify` with `safeStringify` from `fast-safe-stringify`. Example: `const serialized = safeStringify(myObject);`
```
Replacer function not modifying circular reference as expected
```
cause The `replacer` function is receiving the string `"[Circular]"` instead of the actual object, limiting modification capabilities.

fix Check the `value` argument within your `replacer` for the literal string `"[Circular]"` to handle circular references. For example: `if (value === '[Circular]') return;`

Warnings

breaking Version 2.1.0 introduced `depthLimit` and `edgesLimit` options. While defaults are set very high (`Number.MAX_SAFE_INTEGER`), code that implicitly relied on truly infinite recursion (e.g., in very rare, extremely deep structures) might now hit these limits, resulting in `[...]` instead of `[Circular]` for deeply nested references.
Fix: Review and potentially adjust `depthLimit` or `edgesLimit` in the options object passed to `safeStringify` or `stableStringify` if previous behavior is desired for extremely complex objects.
gotcha When a circular reference is detected, the `replacer` function receives the string `"[Circular]"` as its `value` argument, not the original circular object itself. This prevents the `replacer` from directly inspecting or modifying the circular object.
Fix: Design your `replacer` functions to handle the `"[Circular]"` string explicitly if you need to modify or omit circular references, rather than expecting the object itself.
gotcha Manipulating the input object or its circular structure within a `toJSON` method or a `replacer` function may not have the expected effect. For `safeStringify`, manipulating a circular structure in `toJSON` or `replacer` is not possible. For `stableStringify`, any modification to the input object within `toJSON` or `replacer` will be ignored, as the output is based on the initial shape of the value.
Fix: Avoid side-effecting `toJSON` or `replacer` logic for circular references or for any part of the input object when using `stableStringify`. If such manipulation is critical, consider `safe-stable-stringify` (though noted as experimental) or manual pre-processing.

Install

npm install fast-safe-stringify npm
yarn add fast-safe-stringify yarn
pnpm add fast-safe-stringify pnpm

Imports

safeStringify
wrong:
```
const safeStringify = require('fast-safe-stringify');
```
correct:
```
import safeStringify from 'fast-safe-stringify';
```
CommonJS is shown in documentation, but ESM is preferred for modern projects. The default export is the main stringify function.

stableStringify

wrong:

import safeStringify.stableStringify from 'fast-safe-stringify';

correct:

import { stableStringify } from 'fast-safe-stringify';

stableStringify is a named export for deterministic serialization.

default as stringify
```
import stringify from 'fast-safe-stringify';
```
You can alias the default export for clarity, e.g., 'stringify' instead of 'safeStringify'.

Quickstart

Demonstrates `safeStringify` and `stableStringify` handling circular references and optional depth limits.

import safeStringify, { stableStringify } from 'fast-safe-stringify';

const obj = { a: 1, b: 0 };
obj.circular = obj;
obj.anotherRef = obj;

console.log('Original object with circular refs:', obj);

// Using fast-safe-stringify to handle circular references
const safeSerialized = safeStringify(obj);
console.log('\nSafe Stringify Output (non-deterministic key order):', safeSerialized);
// Expected: '{"a":1,"b":0,"circular":"[Circular]","anotherRef":"[Circular]"}'

// Using stableStringify for deterministic output order
const stableSerialized = stableStringify(obj);
console.log('Stable Stringify Output (deterministic key order):', stableSerialized);
// Expected: '{"a":1,"b":0,"anotherRef":"[Circular]","circular":"[Circular]"}'

const deepCircular = { level1: { level2: {} } };
deepCircular.level1.level2.parent = deepCircular;

console.log('\nSafe Stringify with depth limit (default is MAX_SAFE_INTEGER):');
const limitedSerialized = safeStringify(deepCircular, null, 2, { depthLimit: 2 });
console.log(limitedSerialized);
// Expected: '{\n  "level1": {\n    "level2": "[...]"\n  }\n}'

view raw JSON →