Node.js Reference ยท Globals and Console
Node.js structuredClone() function
Reference for structuredClone() in Node.js: deep-copy objects, Maps, Sets, Dates and typed arrays, handle cycles, transfer buffers and avoid DataCloneError.
structuredClone(value) makes a deep copy of a value using the structured clone algorithm, the same algorithm that postMessage() and worker threads use to send data. Nested objects and arrays are copied, and so are Date, RegExp, Map, Set, ArrayBuffer, typed arrays, Error objects and even circular references.
It is a global function, so you do not import anything. Compared with JSON.parse(JSON.stringify(x)), it keeps more types and does not choke on cycles, but it refuses to copy functions and it does not preserve class prototypes.
const copy = structuredClone({ a: 1, list: [1, 2, { b: 3 }] });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
structuredClone(value) structuredClone(value, { transfer })
| Name | Description |
|---|---|
value |
The value to copy. Any cloneable value, including primitives. |
transfer |
Optional array of transferable objects (such as ArrayBuffer or MessagePort) to move instead of copy. |
Returns: a deep copy of value.
Errors: a DOMException named DataCloneError is thrown when a value cannot be cloned (functions, symbols, WeakMap, and similar). A TypeError is thrown if you call it with no arguments.
Usage notes
- Supported: primitives (including
BigInt), plain objects, arrays,Date,RegExp(thelastIndexis reset),Map,Set,ArrayBuffer, typed arrays,DataView,Blob,Errorand its standard subclasses, and boxed primitives. - Not supported: functions, symbols as values,
WeakMap,WeakSet,WeakRef, and DOM-like host objects. They throwDataCloneError. - Prototypes are lost. A class instance becomes a plain object with the same own data properties, so methods vanish. Rebuild instances yourself if you need them.
- Only own enumerable string-keyed properties are copied. Symbol keys, non-enumerable properties and property attributes are not kept, and getters are called and replaced by their value.
- Cycles and shared references are preserved. If two properties point at the same object, the copy also has them point at one shared object.
undefinedvalues are kept, unlike with JSON, which drops them.NaN,Infinityand-0also survive.- Transfer moves memory. After
transfer, the originalArrayBufferis detached (itsbyteLengthbecomes0), which avoids copying large binary data. - Cost: the work is proportional to the size of the data and is synchronous, so cloning very large structures blocks the event loop.
- Added as a global in Node.js 17.