Registry / serialization / safe-stable-stringify

safe-stable-stringify

library2.5.0jsnpmunverified

safe-stable-stringify is a JavaScript utility that provides a deterministic and safe alternative to JSON.stringify. Currently at version 2.5.0, it offers consistent object key ordering, graceful handling of circular references, and configurable serialization of BigInt values, addressing common pitfalls of the native `JSON.stringify`. The library maintains a regular release cadence, frequently adding new options and performance improvements. Key differentiators include its configurable deterministic sorting using custom comparators, options to control maximum serialization depth and breadth, and the ability to define how circular references or BigInts are handled (e.g., replacement values, throwing errors, or omission). It ships with TypeScript types, supports both ESM and CommonJS modules, and has zero external dependencies, making it a robust choice for environments requiring reliable JSON serialization.

serialization

npm install safe-stable-stringify

github ↗package ↗

INSTALL

IMPORT

SIG · SAFE-STABLE-STRING

safe-stable-stringify

serializationjavascriptv2.5.0

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.

stringify

✓ import { stringify } from 'safe-stable-stringify'

✗ import stringify from 'safe-stable-stringify'

For ESM, the primary `stringify` function is a named export. It offers default safe and deterministic behavior. For CJS, use `const stringify = require('safe-stable-stringify')`.

configure

✓ import { configure } from 'safe-stable-stringify'

✗ import configure from 'safe-stable-stringify'

The `configure` function is a named export in ESM, used to create custom stringify functions with specific options (e.g., `circularValue`, `bigint`, `deterministic`). For CJS, it can be accessed via `const { configure } = require('safe-stable-stringify')`.

stringify (CJS)

✓ const stringify = require('safe-stable-stringify')

✗ const { stringify } = require('safe-stable-stringify')

In CommonJS environments, the main `stringify` function is the default export of the package. `configure` is available as a named property on this default export.

Demonstrates configuring `safe-stable-stringify` to handle circular references, BigInts, and ensure deterministic key order, then serializing an object with these features.

import { configure } from 'safe-stable-stringify'; const userObject = { id: 123, name: 'Alice', settings: { theme: 'dark', notifications: true, circularRef: null // Will be set later }, roles: ['admin', 'user'], creationDate: new Date(), bigIntId: 9007199254740991123n // Example BigInt }; userObject.settings.circularRef = userObject; // Create a circular reference // Configure stringify for deterministic output, handling circular refs and BigInts const stringify = configure({ deterministic: true, // Sort object keys alphabetically circularValue: '[CIRCULAR_REF]', // Replace circular references with this string bigint: true, // Convert BigInts to numbers maximumDepth: 3 // Limit serialization depth }); try { const serialized = stringify(userObject, null, 2); console.log(serialized); // Expected output (order of keys will be stable, BigInt converted): // { // "bigIntId": 9007199254740991123, // "creationDate": "2026-04-19T06:51:00.000Z", // Actual date will vary // "id": 123, // "name": "Alice", // "roles": [ // "admin", // "user" // ], // "settings": { // "circularRef": "[CIRCULAR_REF]", // "notifications": true, // "theme": "dark" // } // } } catch (error) { console.error('Serialization error:', error.message); }

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes including default BigInt conversion to number (previously ignored), required ES6 environment, and full ESM support.

fix

Review BigInt handling; if you need to ignore BigInts as in v1, set the `bigint` option to `false`. Ensure your environment supports ES6 and adapt imports for ESM if migrating from CJS.

affects: >=2.0.0

breakingThe default behavior for object key order became deterministic (sorted keys) in v2.0.0. If you relied on insertion order, you need to explicitly set `deterministic: false`.

fix

If non-deterministic (insertion order) serialization is desired, use `configure({ deterministic: false })`.

affects: >=2.0.0

gotchaBoxed primitives (e.g., `Number(5)`, `Boolean(true)`) are treated as regular objects and not unboxed, unlike native `JSON.stringify`. This can lead to different serialization outputs for these specific values.

fix

Avoid using boxed primitives if native `JSON.stringify` unboxing behavior is expected, or manually unbox them before serialization.

affects: all

gotchaUsing the `strict` option verifies full JSON compatibility and will throw an error for non-JSON-compatible values (functions, `NaN`, `Infinity`), or if circular/BigInt values are present without explicit handling options. Sets, Maps, and Symbol keys are also not detected as incompatible.

fix

Ensure all values are JSON-compatible or explicitly configure `bigint` and `circularValue` options if they might be present. Handle `NaN`/`Infinity` or use custom replacers. Be aware that `strict` does not detect Sets, Maps, or Symbol keys as incompatible.

affects: >=2.4.0

gotchaEarlier versions (prior to v2.3.1) could encounter 'invalid regexp group' errors in environments lacking negative lookbehind support for regular expressions (e.g., older browsers or Node.js versions).

fix

Upgrade to `safe-stable-stringify` v2.3.1 or newer to resolve this issue. Ensure your environment supports modern RegExp features if staying on older versions.

affects: <2.3.1

Errors

Common errors & fixes

TypeError: Do not know how to serialize a BigInt

Attempting to serialize a BigInt value using native `JSON.stringify`, or `safe-stable-stringify` with `bigint: false` and `strict: true`.

fix

Use `safe-stable-stringify` with the default `bigint: true` option (or explicitly set it), or provide a custom `replacer` function to handle BigInts. For `strict: true`, explicitly set `bigint: true` or `bigint: false` to ignore/convert.

TypeError: Converting circular structure to JSON

Attempting to serialize an object with circular references using native `JSON.stringify`, or `safe-stable-stringify` configured to throw on circular references (`circularValue: Error`).

fix

Configure `safe-stable-stringify` with `circularValue` set to a string (e.g., `'[Circular]'`), `null`, or `undefined` to handle circular references gracefully instead of throwing an error.

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/BridgeAR/safe-stable-stringify ↗

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