Structured Clone Algorithm
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.
JSON.parse(JSON.stringify) vs structuredClone()
const copy = JSON.parse(JSON.stringify(state));
// Drops Map, Set, Date -> string, RegExp -> {}
// Crashes on circular referencesSilently corrupts Dates, Maps, Sets, undefined, and NaN.
const copy = structuredClone(state, {
transfer: [state.rawBuffer],
});
// Preserves Map, Set, Date, cycles, and moves bufferPreserves 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.
- Memory Map Deduplication: The engine tracks visited objects in an internal map so circular references and shared sub-objects clone once.
- Type-Tagged Serialization: Built-in internal slots (
[[DateValue]],[[MapData]],[[ArrayBufferData]]) serialize natively in C++. - Prototype Stripping: Cloned class instances become plain
Objectshells without methods. - Transfer Semantics: Passing
[buffer]in{ transfer }detaches the buffer in the sender realm for zero-copy Garbage Collection cleanup.
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); // trueProblem Genealogy
- 2009 (
JSON.parse(JSON.stringify())): Misused as a deep-clone trick; corruptedDate,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
DataCloneErroron Reactive Proxies: Passing Vue/MobXProxyobjects or functions tostructuredClone()throws immediately; unwrap to raw objects first.- Cloning Multi-Megabyte Buffers: Omitting the
transferlist copies the entireArrayBufferon the main thread.
- When not to use
structuredClone(): Never usestructuredClone()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
Arguments and return values crossing the server-client boundary must be acyclic and serializable.
Cross-boundary messages via postMessage and IndexedDB strip prototypes and bypass TypeScript compile-time types.
Transferable ArrayBuffers use the Structured Clone transfer list to move ownership without copying.
Structured clone copies own enumerable properties and discards custom [[Prototype]] chains.
Transferring an ArrayBuffer detaches it in the source realm so GC reclaims only the empty shell.
structuredClone() clones legacy Date internal slots natively, whereas Temporal objects require explicit ISO string serialization.