JSON Stringification Strategies for Production Applications

Native JSON.stringify() works well for simple data, but real-world applications often hit its limits. Circular references crash it. Key ordering changes between runs. Performance drops on large objects. The six packages in this comparison each solve specific problems that native JSON cannot handle. Let's examine how they differ and when to use each one.

⚠️ Deprecation Status: What to Avoid

Before diving into features, note that circular-json is deprecated. The maintainer officially recommends migrating to flatted. Using deprecated packages in new projects introduces security and maintenance risks.

// circular-json - DEPRECATED, do not use in new projects
import CircularJSON from 'circular-json';
const str = CircularJSON.stringify(obj); // Works but unmaintained

// flatted - Recommended replacement
import { stringify } from 'flatted';
const str = stringify(obj); // Same capability, actively maintained

json-stringify-safe is also in maintenance mode with minimal updates. It still works but lacks modern optimizations. Consider flatted if you need circular reference support with active maintenance.

🔄 Handling Circular References

Circular references occur when objects reference themselves or each other. Native JSON.stringify() throws TypeError: Converting circular structure to JSON.

flatted encodes circular references so they can be revived later.

import { stringify, parse } from 'flatted';

const obj = { name: 'parent' };
obj.self = obj; // Circular reference

const str = stringify(obj); // '{"name":"parent","self":"~0"}'
const revived = parse(str); // Circular reference restored
console.log(revived.self === revived); // true

circular-json works similarly but is deprecated.

import CircularJSON from 'circular-json';

const obj = { name: 'parent' };
obj.self = obj;

const str = CircularJSON.stringify(obj);
const revived = CircularJSON.parse(str);
console.log(revived.self === revived); // true

json-stringify-safe replaces circular references with placeholder strings instead of encoding them.

import stringify from 'json-stringify-safe';

const obj = { name: 'parent' };
obj.self = obj;

const str = stringify(obj);
// '{"name":"parent","self":"[Circular ~]"}'
// Cannot be parsed back to restore circular reference

fast-json-stringify, fast-stable-stringify, and json-stable-stringify do not handle circular references. They will throw errors if circular structures are passed.

import fastJsonStringify from 'fast-json-stringify';

const stringify = fastJsonStringify({
  type: 'object',
  properties: { name: { type: 'string' } }
});

const obj = { name: 'test' };
obj.self = obj; // Will throw error

stringify(obj); // TypeError: Converting circular structure to JSON

⚡ Performance: Schema-Based vs General Purpose

fast-json-stringify is the fastest option but requires a JSON schema.

import fastJsonStringify from 'fast-json-stringify';

const stringify = fastJsonStringify({
  type: 'object',
  properties: {
    id: { type: 'number' },
    name: { type: 'string' },
    active: { type: 'boolean' }
  },
  required: ['id', 'name']
});

const obj = { id: 1, name: 'User', active: true };
const str = stringify(obj); // Extremely fast, schema-validated

fast-stable-stringify offers good performance without schema requirements.

import fastStableStringify from 'fast-stable-stringify';

const obj = { z: 1, a: 2, m: 3 };
const str = fastStableStringify(obj); // '{"a":2,"m":3,"z":1}'
// Keys sorted alphabetically, faster than json-stable-stringify

json-stable-stringify prioritizes compatibility over speed.

import stableStringify from 'json-stable-stringify';

const obj = { z: 1, a: 2, m: 3 };
const str = stableStringify(obj); // '{"a":2,"m":3,"z":1}'
// Keys sorted alphabetically, well-tested but slower

flatted and json-stringify-safe have overhead from circular reference handling.

import { stringify as flattedStringify } from 'flatted';
import safeStringify from 'json-stringify-safe';

const obj = { a: 1, b: 2 };

const flattedStr = flattedStringify(obj); // Extra encoding overhead
const safeStr = safeStringify(obj); // Circular check overhead

🔑 Deterministic Key Ordering

Native JSON.stringify() does not guarantee key order across JavaScript engines. This breaks hashing, caching, and comparison logic.

fast-stable-stringify sorts keys alphabetically with high performance.

import fastStableStringify from 'fast-stable-stringify';

const obj1 = { id: 1, name: 'Test' };
const obj2 = { name: 'Test', id: 1 };

const str1 = fastStableStringify(obj1); // '{"id":1,"name":"Test"}'
const str2 = fastStableStringify(obj2); // '{"id":1,"name":"Test"}'

console.log(str1 === str2); // true - consistent for hashing

json-stable-stringify also sorts keys with custom comparator support.

import stableStringify from 'json-stable-stringify';

const obj = { b: 2, a: 1 };

// Default alphabetical sort
const str1 = stableStringify(obj); // '{"a":1,"b":2}'

// Custom comparator (e.g., sort by value)
const str2 = stableStringify(obj, {
  cmp: (a, b) => a.value < b.value ? -1 : 1
});

flatted preserves insertion order but encodes circular references.

import { stringify } from 'flatted';

const obj = { z: 1, a: 2 };
const str = stringify(obj); // Order preserved but with encoding layer

fast-json-stringify, circular-json, and json-stringify-safe do not guarantee deterministic ordering without additional configuration.

🛡️ Error Handling and Safety

json-stringify-safe never throws — it gracefully degrades on circular references.

import safeStringify from 'json-stringify-safe';

const obj = { name: 'test' };
obj.ref = obj;

const str = safeStringify(obj, null, 2, function(key, value) {
  if (value === '[Circular]') {
    return undefined; // Remove circular refs entirely
  }
  return value;
});
// Safe for logging — never crashes

flatted handles circular references but can throw on non-serializable values.

import { stringify } from 'flatted';

const obj = { fn: () => {} }; // Functions not serializable

try {
  const str = stringify(obj); // May throw or skip functions
} catch (e) {
  // Handle serialization error
}

fast-json-stringify validates against schema and throws on mismatch.

import fastJsonStringify from 'fast-json-stringify';

const stringify = fastJsonStringify({
  type: 'object',
  properties: { id: { type: 'number' } }
});

stringify({ id: 'not-a-number' }); // Throws validation error
// This is a feature — catches data issues early

fast-stable-stringify and json-stable-stringify behave like native JSON.stringify() for errors.

import fastStableStringify from 'fast-stable-stringify';

const obj = { value: BigInt(1) }; // BigInt not JSON-serializable

fastStableStringify(obj); // TypeError: Do not know how to serialize a BigInt

📦 Real-World Usage Scenarios

Scenario 1: API Response Serialization

High-throughput REST API with known response shapes.

• ✅ Best choice: fast-json-stringify
• Why? Schema validation catches bugs early, 5-10x performance gain.

const stringify = fastJsonStringify({
  type: 'object',
  properties: {
    status: { type: 'string' },
    data: { type: 'array', items: { type: 'object' } }
  }
});

app.get('/users', (req, res) => {
  const response = { status: 'ok', data: users };
  res.send(stringify(response)); // Fast, validated
});

Scenario 2: State Persistence with Circular References

Saving application state that contains self-referential objects.

• ✅ Best choice: flatted
• Why? Circular references preserved, can be revived on load.

import { stringify, parse } from 'flatted';

// Save state
const state = createAppState(); // May contain circular refs
localStorage.setItem('app-state', stringify(state));

// Load state
const loaded = parse(localStorage.getItem('app-state'));
// Circular references restored

Scenario 3: Cache Key Generation

Creating consistent hash keys from configuration objects.

• ✅ Best choice: fast-stable-stringify
• Why? Deterministic output, good performance.

import fastStableStringify from 'fast-stable-stringify';
import { createHash } from 'crypto';

function createCacheKey(config) {
  const normalized = fastStableStringify(config);
  return createHash('sha256').update(normalized).digest('hex');
}

// Same config, different key order = same hash

Scenario 4: Error Logging

Serializing error objects that may contain circular references.

• ✅ Best choice: json-stringify-safe
• Why? Never crashes, circular refs replaced with placeholders.

import safeStringify from 'json-stringify-safe';

logger.error({
  message: 'Request failed',
  error: err, // May have circular refs
  context: req // May reference error
});

// Internally uses safeStringify to prevent crashes

Scenario 5: Test Assertions

Comparing objects in unit tests where order should not matter.

• ✅ Best choice: json-stable-stringify
• Why? Well-tested, custom comparators for special cases.

import stableStringify from 'json-stable-stringify';

expect(stableStringify(actual)).toBe(stableStringify(expected));
// Order-independent comparison

📊 Feature Comparison Table

🌱 Shared Capabilities

Despite their differences, these packages share some common ground:

1. JSON-Compatible Output

All packages produce valid JSON strings (except flatted and circular-json which use special encoding).

// All produce string output
const str1 = fastStableStringify(obj);
const str2 = stableStringify(obj);
const str3 = safeStringify(obj);
// All are valid JSON (parseable with JSON.parse except flatted/circular-json)

2. Replacer Function Support

Most support custom replacer functions for transforming values.

// fast-stable-stringify
fastStableStringify(obj, (key, value) => {
  if (key.startsWith('_')) return undefined; // Hide private keys
  return value;
});

// json-stable-stringify
stableStringify(obj, {
  replacer: (key, value) => value
});

// json-stringify-safe
safeStringify(obj, (key, value) => value, 2);

3. Indentation Options

Pretty-printing supported across most packages.

// fast-stable-stringify
fastStableStringify(obj, null, 2); // 2-space indent

// json-stable-stringify
stableStringify(obj, { space: 2 });

// json-stringify-safe
safeStringify(obj, null, 2);

💡 The Big Picture

For performance-critical APIs — fast-json-stringify wins if you can define schemas. The speed gain is substantial for high-throughput systems.

For circular references — flatted is the modern choice. Avoid circular-json in new code. Use json-stringify-safe for logging where revival is not needed.

For deterministic output — fast-stable-stringify offers the best balance of speed and consistency. Choose json-stable-stringify for maximum compatibility and custom comparators.

Final Thought: Native JSON.stringify() remains the default for simple cases. These tools solve specific edge cases — pick based on your actual requirements, not hypothetical needs. Adding dependencies has costs, so only reach for these when native JSON falls short.