Safe Stable Stringify

Common errors

• TypeError: Do not know how to serialize a BigInt

  cause 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

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

Warnings

• breaking Version 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.
• breaking The 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 })`.
• gotcha Boxed 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.
• gotcha Using 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.
• gotcha Earlier 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.

Install

• npm install safe-stable-stringify npm
• yarn add safe-stable-stringify yarn
• pnpm add safe-stable-stringify pnpm

Imports

• stringify
  wrong:

  import stringify from 'safe-stable-stringify'

  correct:

  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
  wrong:

  import configure from 'safe-stable-stringify'

  correct:

  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)
  wrong:

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

  correct:

  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.

Quickstart

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);
}