Window: structuredClone() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2022.
ThestructuredClone() method of theWindow interface creates adeep clone of a given value using thestructured clone algorithm.
The method also allowstransferable objects in the original value to betransferred rather than cloned to the new object.Transferred objects are detached from the original object and attached to the new object; they are no longer accessible in the original object.
Syntax
structuredClone(value)structuredClone(value, options)Parameters
valueThe object to be cloned.This can be anystructured-cloneable type.
optionsOptionalAn object with the following properties:
transferAn array oftransferable objects that will be moved rather than cloned to the returned object.
Return value
Adeep copy of the originalvalue.
Exceptions
DataCloneErrorDOMExceptionThrown if any part of the input value is not serializable.
Description
This function can be used todeep copy JavaScript values.It also supports circular references, as shown below:
// Create an object with a value and a circular reference to itself.const original = { name: "MDN" };original.itself = original;// Clone itconst clone = structuredClone(original);console.assert(clone !== original); // the objects are not the same (not same identity)console.assert(clone.name === "MDN"); // they do have the same valuesconsole.assert(clone.itself === clone); // and the circular reference is preservedTransferring values
Transferable objects (only) can be transferred rather than duplicated in the cloned object, using thetransfer property of theoptions parameter. Transferring makes the original object unusable.
Note:A scenario where this might be useful is when asynchronously validating some data in a buffer before saving it.To avoid the buffer being modified before the data is saved, you can clone the buffer and validate that data.If you alsotransfer the data, any attempts to modify the original buffer will fail, preventing its accidental misuse.
The following code shows how to clone an array and transfer its underlying resources to the new object.On return, the originaluInt8Array.buffer will be cleared.
// 16MB = 1024 * 1024 * 16const uInt8Array = Uint8Array.from({ length: 1024 * 1024 * 16 }, (v, i) => i);const transferred = structuredClone(uInt8Array, { transfer: [uInt8Array.buffer],});console.log(uInt8Array.byteLength); // 0You can clone any number of objects and transfer any subset of those objects.For example, the code below would transferarrayBuffer1 from the passed in value, but notarrayBuffer2.
const transferred = structuredClone( { x: { y: { z: arrayBuffer1, w: arrayBuffer2 } } }, { transfer: [arrayBuffer1] },);Examples
Cloning an object
In this example, we clone an object with one member, which is an array. After cloning, changes to each object do not affect the other object.
const mushrooms1 = { amanita: ["muscaria", "virosa"],};const mushrooms2 = structuredClone(mushrooms1);mushrooms2.amanita.push("pantherina");mushrooms1.amanita.pop();console.log(mushrooms2.amanita); // ["muscaria", "virosa", "pantherina"]console.log(mushrooms1.amanita); // ["muscaria"]Transferring an object
In this example we create anArrayBuffer and then clone the object it is a member of, transferring the buffer. We can use the buffer in the cloned object, but if we try to use the original buffer we will get an exception.
// Create an ArrayBuffer with a size in bytesconst buffer = new ArrayBuffer(16);const object1 = { buffer,};// Clone the object containing the buffer, and transfer itconst object2 = structuredClone(object1, { transfer: [buffer] });// Create an array from the cloned bufferconst int32View2 = new Int32Array(object2.buffer);int32View2[0] = 42;console.log(int32View2[0]);// Creating an array from the original buffer throws a TypeErrorconst int32View1 = new Int32Array(object1.buffer);Specifications
| Specification |
|---|
| HTML # dom-structuredclone |