Handling Circular References in JavaScript: circular-json vs flatted vs json-stringify-safe

When working with complex JavaScript objects — especially those involving DOM nodes, class instances, or bidirectional relationships — you’ll eventually hit a wall with JSON.stringify(). It throws a TypeError: Converting circular structure to JSON the moment it detects a loop. The three packages under review (circular-json, flatted, and json-stringify-safe) each offer a way around this problem, but they do so with very different strategies, trade-offs, and maintenance statuses. Let’s break down what each actually does, how they work, and which one deserves your attention in 2024.

🔄 Core Strategy: How Each Package Handles Cycles

circular-json: Encode → Stringify → Decode

circular-json uses a two-step process: first, it walks the object tree and replaces circular references with special placeholder strings (like "$ref$0"). Then it safely calls JSON.stringify() on the transformed structure. To restore the original object, you use CircularJSON.parse(), which reverses the transformation.

// circular-json example
import CircularJSON from 'circular-json';

const obj = { a: 1 };
obj.self = obj; // circular reference

const serialized = CircularJSON.stringify(obj);
// Result: '{"a":1,"self":"$ref$0"}'

const restored = CircularJSON.parse(serialized);
console.log(restored.self === restored); // true

⚠️ Important: According to its npm page, circular-json is deprecated. The author explicitly recommends using flatted instead. Do not use this in new projects.

flatted: Leverage JSON’s Native Structure with Path-Based References

flatted takes a clever approach by converting any object into an array where the first element is the root object, and subsequent elements represent referenced sub-objects. It uses string keys like "1" or "2" to point to indices in that array. This avoids inventing custom syntax and stays within standard JSON.

// flatted example
import { stringify, parse } from 'flatted';

const obj = { a: 1 };
obj.self = obj;

const serialized = stringify(obj);
// Result: '[{"a":1,"self":"1"},"0"]'
// Explanation: Root object at index 0, "self" points to index 1, which is "0" (a string pointing back to index 0)

const restored = parse(serialized);
console.log(restored.self === restored); // true

This method is fully compatible with native JSON.parse() for the outer structure — only the inner logic of reconstruction requires flatted.parse().

json-stringify-safe: Silently Drop or Replace Problematic Values

Unlike the other two, json-stringify-safe doesn’t preserve circular structures. Instead, it avoids errors by replacing circular references (and other non-serializable values like functions) with a placeholder — by default, the string "[Circular]". There’s no built-in way to reconstruct the original object.

// json-stringify-safe example
import stringify from 'json-stringify-safe';

const obj = { a: 1 };
obj.self = obj;
obj.fn = () => {};

const serialized = stringify(obj);
// Result: '{"a":1,"self":"[Circular]","fn":"[Function]"}'

// No parse() method — this is one-way serialization only

This is useful for logging or debugging, where you just need a readable snapshot — not a reversible transformation.

🔁 Reversibility: Can You Get Your Object Back?

• circular-json: ✅ Yes — via CircularJSON.parse()
• flatted: ✅ Yes — via flatted.parse()
• json-stringify-safe: ❌ No — it’s a lossy, one-way operation

If your goal is to transmit or store a complex object and later reconstruct it exactly, only circular-json and flatted qualify. But since circular-json is deprecated, flatted becomes the only viable reversible option.

🧪 Behavior with Edge Cases

All three handle basic cycles, but differ on edge cases:

Multiple references to the same object

const shared = { value: 42 };
const obj = { a: shared, b: shared };

• flatted preserves referential identity: after parse(), obj.a === obj.b is true.
• circular-json also preserves identity (but again — deprecated).
• json-stringify-safe turns both into {"value":42} as plain objects — so obj.a === obj.b becomes false.

Non-object values (functions, undefined, symbols)

• flatted and circular-json will throw or behave unpredictably with functions/symbols — they assume you’re working with plain objects.
• json-stringify-safe explicitly handles them by replacing with descriptive strings like "[Function]" or "[undefined]".

🛠️ API Design and Integration

• flatted exports stringify and parse — clean, minimal, and mirrors the native JSON API.
• circular-json uses static methods (CircularJSON.stringify / .parse) — slightly more verbose.
• json-stringify-safe only provides a stringify function — no parsing capability.

📦 Real-World Use Cases

Use flatted when:

• You need to serialize and later reconstruct complex objects with cycles (e.g., saving app state, sending data over WebSockets).
• You want a maintained, modern solution that works reliably with nested references.
• Example: Storing a Redux state tree that includes entity relationships with back-references.

// Saving and restoring state with flatted
localStorage.setItem('state', stringify(reduxState));
const restoredState = parse(localStorage.getItem('state'));

Use json-stringify-safe when:

• You’re logging objects for debugging or error reporting.
• You don’t care about reconstruction — just want to avoid crashes during serialization.
• Example: Sending error context to a logging service like Sentry.

// Safe logging
console.log(stringify(errorContext)); // Won't crash, even with cycles

Avoid circular-json:

• It’s officially deprecated.
• The author (Andrea Giammarchi) now maintains flatted as its successor.
• Using it introduces technical debt and potential security risks from unmaintained code.

🆚 Summary Table

💡 Final Recommendation

• For new projects requiring reversible serialization: Use flatted. It’s lightweight, well-designed, and actively maintained.
• For logging or one-way safe stringification: Use json-stringify-safe. It’s battle-tested and perfect for observability.
• Do not use circular-json — it’s deprecated, and flatted is its direct, improved replacement.

In short: if you need to save and restore complex state, go with flatted. If you just need to print without crashing, json-stringify-safe has your back.