Deep-copy application data
Create independent state snapshots containing nested objects, arrays, Maps, or Sets.
JavaScript · Function
structuredClone
structuredClone() creates a deep clone of a structured-cloneable JavaScript value. Its optional transfer list can move transferable resources into the clone instead of copying them.
How it works
structuredClone(value, options) recursively creates a structured clone of a supported value. With options.transfer, listed transferable resources move into the clone instead of being copied, leaving the original resources detached and unusable.
Syntax
structuredClone(value)
structuredClone(value, options)Parameters
| Name | Type | Description |
|---|---|---|
value | any | The value to clone; it must be structured-cloneable. |
options | Object | Optional options object. Its transfer property is an array of transferable objects to move rather than clone. |
Returns
A deep copy of the original value.
Key points
- It produces a deep clone rather than merely copying the top-level reference.
- Circular object graphs are supported because previously encountered references are tracked during cloning.
- The transfer option can move eligible resources instead of allocating a duplicate resource.
- The input must be a value supported by the structured clone algorithm.
- options.transfer identifies the transferable objects to move into the returned clone.
- The return value is the independently cloned value.
Common mistakes
- Functions cannot be cloned; attempting to clone one raises DataCloneError.
- Custom prototypes are not preserved, so a cloned class instance does not retain its prototype behavior.
- Descriptor metadata and accessor definitions are not reproduced in the clone.
- A transferred resource is moved to the result; the corresponding resource in the input becomes unusable.
Example: Deep-clone nested data
const original = { user: { name: "Ada" }, values: new Set([1, 2]) };
const copy = structuredClone(original);
copy.user.name = "Grace";
copy.values.add(3);
console.log(original.user.name); // "Ada"
console.log(original.values.has(3)); // falseCreates an independent deep copy, including the nested object and Set.
When to use it
Transfer binary data efficiently
Move transferable resources such as an ArrayBuffer without duplicating their underlying storage.
Preserve circular references
Clone cyclic data structures that JSON serialization cannot represent.
Interview questions
QWhat does structuredClone do?
It creates a deep clone using the structured clone algorithm, so nested supported values are copied rather than shared. Unlike a shallow copy, changes to nested data in the result do not mutate the source.
Follow-up: How are cycles handled? The algorithm keeps a map of previously visited references while recursing, allowing circular structures without infinite traversal.
QWhat are the parameters?
The first argument is the value to clone. The optional options object can contain transfer, an array of transferable objects that are moved instead of duplicated.
Follow-up: What happens after transfer? The transferred resource is attached to the clone and detached from the original, so the source can no longer use it.
QWhat does it return, and when can it fail?
It returns a deep copy of the input value. If any part is not serializable, it throws a DataCloneError DOMException.
Follow-up: Name two unsupported inputs. Functions and DOM nodes cannot be cloned by the structured clone algorithm.
Related
structured clone algorithmWindow.structuredClone()WorkerGlobalScope.structuredClone()DataCloneErrorTransferable objects