Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const copy = structuredClone({ a: 1, list: [1, 2, { b: 3 }] });

Try it

Node.js What survives a clone

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.

Node.js Limits: functions, classes and getters

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

NODE
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 (the lastIndex is reset), Map, Set, ArrayBuffer, typed arrays, DataView, Blob, Error and its standard subclasses, and boxed primitives.
  • Not supported: functions, symbols as values, WeakMap, WeakSet, WeakRef, and DOM-like host objects. They throw DataCloneError.
  • 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.
  • undefined values are kept, unlike with JSON, which drops them. NaN, Infinity and -0 also survive.
  • Transfer moves memory. After transfer, the original ArrayBuffer is detached (its byteLength becomes 0), 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.