Serializing Complex JavaScript Objects: Circular References and Determinism

Standard JSON.stringify() is powerful but has two major limitations for advanced engineering: it throws an error on circular references, and it does not guarantee consistent key ordering. The packages circular-json, flatted, json-stringify-deterministic, and json-stringify-safe address these gaps in different ways. Let's compare how they handle real-world serialization challenges.

⚠️ Handling Circular References: Round-Trip vs. Logging

The most common failure point in JavaScript serialization is the circular reference — when object A points to object B, which points back to object A.

circular-json was an early solution that allowed serialization and parsing of circular structures.

• It maps references to special IDs.
• Status: Deprecated. Do not use.

// circular-json: Deprecated API
import CircularJSON from 'circular-json';

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

// Works, but package is unmaintained
const str = CircularJSON.stringify(obj); 
const parsed = CircularJSON.parse(str);

flatted is the modern replacement for circular-json.

• It uses a similar reference mapping strategy but is actively maintained.
• Supports full round-trip (stringify and parse).

// flatted: Modern API
import { stringify, parse } from 'flatted';

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

// Recommended approach
const str = stringify(obj); 
const parsed = parse(str); // parsed.self === parsed

json-stringify-safe handles circles by masking them, not preserving them.

• It prevents the crash but replaces the circle with text.
• You cannot parse the result back to the original structure.
• Ideal for logging.

// json-stringify-safe: Logging API
import stringify from 'json-stringify-safe';

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

// Does not throw, but output is for reading only
const str = stringify(obj); 
// Output: {"name":"test","self":"[Circular]"}

json-stringify-deterministic focuses on key order, not circles.

• If you pass a circular object, it will likely throw like standard JSON.
• It is not designed to solve the circular reference problem.

// json-stringify-deterministic: Key Order API
import stringify from 'json-stringify-deterministic';

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

// Will throw TypeError: Converting circular structure to JSON
const str = stringify(obj); 

🔢 Ensuring Consistent Key Order: Hashing and Caching

When generating hashes or cache keys, "{a:1, b:2}" must equal "{b:2, a:1}". Standard JSON does not guarantee this.

circular-json does not guarantee key order.

• Its primary focus is reference preservation.
• Not suitable for checksums.

// circular-json: No order guarantee
import CircularJSON from 'circular-json';

const obj = { b: 2, a: 1 };
const str = CircularJSON.stringify(obj); 
// Key order depends on insertion, not sorted

flatted does not guarantee key order.

• It prioritizes reference integrity over key sorting.
• Not suitable for checksums.

// flatted: No order guarantee
import { stringify } from 'flatted';

const obj = { b: 2, a: 1 };
const str = stringify(obj); 
// Key order depends on insertion, not sorted

json-stringify-deterministic sorts keys alphabetically.

• Ensures the same input always yields the same string.
• Essential for cryptographic signatures or cache keys.

// json-stringify-deterministic: Sorted Keys
import stringify from 'json-stringify-deterministic';

const obj = { b: 2, a: 1 };
const str = stringify(obj); 
// Output: {"a":1,"b":2} (Always sorted)

json-stringify-safe does not guarantee key order.

• It wraps standard stringify logic primarily for safety.
• Not suitable for checksums.

// json-stringify-safe: No order guarantee
import stringify from 'json-stringify-safe';

const obj = { b: 2, a: 1 };
const str = stringify(obj); 
// Key order depends on insertion, not sorted

🛠️ API Simplicity and Integration

How these packages fit into your existing codebase varies by design.

circular-json uses a default export that mimics JSON.

• Drop-in replacement style, but legacy.

// circular-json: Legacy namespace
import CircularJSON from 'circular-json';
CircularJSON.stringify(data);

flatted uses named exports for clarity.

• Explicit stringify and parse functions.

// flatted: Named exports
import { stringify, parse } from 'flatted';
stringify(data);

json-stringify-deterministic exports a single function.

• Often named stringify.

// json-stringify-deterministic: Single function
import stringify from 'json-stringify-deterministic';
stringify(data);

json-stringify-safe exports a single function with optional arguments.

• Matches JSON.stringify signature (obj, replacer, space).

// json-stringify-safe: Standard signature
import stringify from 'json-stringify-safe';
stringify(data, null, 2);

🌐 Real-World Scenarios

Scenario 1: Saving Application State to LocalStorage

You have a complex state tree with circular references (e.g., parent-child links).

• ✅ Best choice: flatted
• Why? You need to restore the state exactly as it was, including links.

// flatted: State persistence
import { stringify, parse } from 'flatted';
localStorage.setItem('state', stringify(appState));
const restored = parse(localStorage.getItem('state'));

Scenario 2: Logging Errors in a Backend Service

You are logging request objects that might contain circular references (e.g., req.res.req).

• ✅ Best choice: json-stringify-safe
• Why? You just need to read the log. Crashing the logger is worse than seeing [Circular].

// json-stringify-safe: Error logging
import stringify from 'json-stringify-safe';
logger.error(stringify(errorObject));

Scenario 3: Generating an API Signature

You need to hash a payload to verify integrity. Key order must be consistent.

• ✅ Best choice: json-stringify-deterministic
• Why? hash({a:1}) must equal hash({a:1}) regardless of how the object was created.

// json-stringify-deterministic: Signing
import stringify from 'json-stringify-deterministic';
const signature = crypto.createHash('sha256').update(stringify(payload)).digest('hex');

Scenario 4: Legacy Code Maintenance

You encounter circular-json in an old codebase.

• ✅ Best choice: Refactor to flatted
• Why? circular-json is deprecated and may have unpatched vulnerabilities.

// Refactor target
// Old: import CircularJSON from 'circular-json';
// New: import { stringify } from 'flatted';

📊 Summary: Key Differences

💡 The Big Picture

flatted is the go-to solution for data that needs to travel and return with its structure intact. It solves the circular reference problem without sacrificing the ability to parse the data later.

json-stringify-safe is a safety net for observability. It ensures your logging infrastructure never crashes due to unexpected object shapes, trading data fidelity for stability.

json-stringify-deterministic is a tool for integrity. It removes ambiguity from serialization, making it essential for security and caching layers.

circular-json belongs in the past. It served a purpose but has been superseded by better, maintained alternatives.

Final Thought: Don't reach for a circular serializer when you just need to log an error, and don't use a safe logger when you need to generate a hash. Match the tool to the data flow requirement.