Registry / serialization / fast-safe-stringify

fast-safe-stringify

library2.1.1jsnpmunverified

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.

serialization

npm install fast-safe-stringify

github ↗package ↗

INSTALL

IMPORT

SIG · FAST-SAFE-STRINGIF

fast-safe-stringify

serializationjavascriptv2.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

safeStringify

✓ import safeStringify from 'fast-safe-stringify';

✗ const safeStringify = require('fast-safe-stringify');

CommonJS is shown in documentation, but ESM is preferred for modern projects. The default export is the main stringify function.

stableStringify

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

✗ import safeStringify.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'.

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}'

Debug

Known issues

breakingVersion 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.

affects: >=2.1.0

gotchaWhen 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.

affects: >=1.0.0

gotchaManipulating 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Converting circular structure to JSON

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

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;`

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/davidmarkclements/fast-safe-stringify ↗

packagehttps://www.npmjs.com/package/fast-safe-stringify ↗