JS RuntimeBaseline · Widely

Structured Clone Algorithm

Mental Model

The Structured Clone Algorithm powers structuredClone(), postMessage(), and IndexedDB. Unlike JSON.stringify(), it preserves Date, Map, Set, RegExp, and cyclic references, drops custom Prototype Chains, and throws DataCloneError on functions or DOM nodes.

Interactive Simulator

JSON.parse(JSON.stringify) vs structuredClone()

Lines of Code
Before
3
After
4
Reflows / Browser Cost
Before
2 string passes
After
1 binary C++ walk
BeforeJSON Round-Trip Hack
const copy = JSON.parse(JSON.stringify(state));
// Drops Map, Set, Date -> string, RegExp -> {}
// Crashes on circular references
Lines: 3Reflows: 2 string passesDependencies: Loses types & cycles

Silently corrupts Dates, Maps, Sets, undefined, and NaN.

After (Native)Native structuredClone(val, { transfer })
const copy = structuredClone(state, {
  transfer: [state.rawBuffer],
});
// Preserves Map, Set, Date, cycles, and moves buffer
Lines: 4Reflows: 1 binary C++ walkDependencies: 0 JS dependencies

Preserves cyclic graphs and transfers ArrayBuffers in O(1).

Under the Hood

The HTML StructuredSerializeInternal algorithm walks object graphs in C++ while maintaining a visited-object memory map to preserve cycles and shared references. Built-in internal slots serialize natively, custom [[Prototype]] chains are stripped to plain Object shells, and functions or DOM nodes throw DataCloneError.

  1. Memory Map Deduplication: The engine tracks visited objects in an internal map so circular references and shared sub-objects clone once.
  2. Type-Tagged Serialization: Built-in internal slots ([[DateValue]], [[MapData]], [[ArrayBufferData]]) serialize natively in C++.
  3. Prototype Stripping: Cloned class instances become plain Object shells without methods.
  4. Transfer Semantics: Passing [buffer] in { transfer } detaches the buffer in the sender realm for zero-copy Garbage Collection cleanup.
JS
const payload = { created: new Date(), items: new Set([1, 2]) };
payload.self = payload; // Cyclic reference

const clone = structuredClone(payload);
console.log(clone.self === clone); // true
console.log(clone.items instanceof Set); // true

Problem Genealogy

  • 2009 (JSON.parse(JSON.stringify())): Misused as a deep-clone trick; corrupted Date, Map, Set, NaN, and crashed on cycles.
  • 2010 (postMessage & IndexedDB): Exposed structured cloning indirectly across workers and storage.
  • 2022 (globalThis.structuredClone): Exposed the browser's C++ clone engine directly as a synchronous global function.

Production Pitfalls

Production Pitfall
  • DataCloneError on Reactive Proxies: Passing Vue/MobX Proxy objects or functions to structuredClone() throws immediately; unwrap to raw objects first.
  • Cloning Multi-Megabyte Buffers: Omitting the transfer list copies the entire ArrayBuffer on the main thread.
When Not to Use
  • When not to use structuredClone(): Never use structuredClone() to clone class instances when you need their methods or prototype chain intact, or for Temporal API objects (serialize them as ISO strings instead).

Connections & Logical Next Steps

Mechanical Comparisons