Structured Clone Semantics

## What the function is `structuredClone(value)` is a global function exposed on `Window` and on worker global scopes. It takes any value and returns a deep copy of it, produced by the **structured clone algorithm** — a serialize-then-deserialize pair defined by the HTML specification. The function is new (Chrome 98, Firefox 94, Safari 15.4, all shipped by early 2022), but the algorithm behind it is old: it is the rule the browser has always used to decide what may cross `postMessage`, what may be written into IndexedDB, and what may be handed to `history.pushState`. Learning it once explains all of those boundaries at the same time. ```js const copy = structuredClone(original); copy.nested.value = 'changed'; // original.nested.value is untouched ``` ## What "deep" actually means here The algorithm walks the whole reachable graph of the input. Every plain object and array is rebuilt, so mutating anything in the copy — at any depth — cannot be observed through the original. This is the property a shallow copy such as `{ ...obj }` or `Object.assign({}, obj)` does not give you: those copy the top-level properties, so a nested object is still the *same* object in both. ## What survives The cloneable set is broad and is defined by the specification, not by the function: - primitives, including `BigInt`, and boxed `String`/`Number`/`Boolean` objects - plain objects and arrays (including sparse arrays) - `Date`, `RegExp` (source and flags; `lastIndex` is not carried over) - `Map` and `Set`, with their keys and values cloned recursively - `ArrayBuffer`, all typed arrays and `DataView` - `Blob`, `File`, `FileList`, `ImageData`, `ImageBitmap` - `Error` and its standard subclasses (`name`, `message`, and `cause`) - cyclic and shared references, which are reproduced as cycles and shared references ## What a JSON round-trip does instead `JSON.parse(JSON.stringify(value))` is a text round-trip, and JSON's data model is far smaller than JavaScript's. A `Date` serializes through its `toJSON` method and comes back as a string. A `Map` or `Set` has no enumerable own properties, so it serializes as `{}` and the contents are simply gone. `undefined`, functions and symbol values are dropped from objects and turned into `null` inside arrays. `NaN` and `Infinity` become `null`. A cycle makes `JSON.stringify` throw. And a `BigInt` makes it throw as well. ```js const src = { when: new Date(0), tags: new Set(['a']) }; structuredClone(src).tags instanceof Set; // true JSON.parse(JSON.stringify(src)).tags; // {} ``` The practical difference is not that one is "better": it is that JSON's losses are *silent* while the clone algorithm's refusals are *loud*. ## Where structuredClone is stricter Anything outside the cloneable set throws a `DOMException` whose `name` is `"DataCloneError"`. Functions, symbols as values, DOM nodes, `Promise`, `WeakMap`/`WeakSet` and proxies all fail this way. So if your object carries a callback, `structuredClone` will not quietly hand you a copy missing that callback — it will refuse the whole operation. Two more things change quietly rather than throwing. Prototypes are not preserved: a class instance comes back as a plain object whose prototype is `Object.prototype`, so its methods are gone. And property descriptors are flattened: only own **enumerable string-keyed** properties are copied, a getter is invoked once and its result stored as an ordinary data property, and symbol-keyed properties are skipped. ## Choosing between them Use `structuredClone` when you want an in-memory deep copy and you control the shape of the value — it is faster than serializing to text and back, and it keeps the rich types. Use `JSON.stringify` when the destination genuinely needs *text*: an HTTP body, a log line, or `localStorage`, whose API only accepts strings. Reach for a library deep-clone only when you need behaviour the algorithm deliberately does not give you, such as preserving class prototypes or copying functions by reference. One last practical note: `structuredClone` is synchronous and runs on the calling thread, so on a very large graph it is not free — the cost is proportional to the size of the graph it has to walk.