Master Deep Copy in JavaScript with the Native structuredClone() Method

Deep copying is a common yet tricky problem in JavaScript. Historically developers relied on custom methods or third‑party libraries, often using JSON.parse(JSON.stringify(obj)), which has many limitations. The modern native solution is the structuredClone() method.

Traditional Deep‑Copy Solutions and Their Problems

Typical approaches include:

These methods have drawbacks:

JSON method cannot handle functions, Symbol, undefined, circular references, and loses prototype chains; it also mishandles Date, RegExp, Map, Set, etc.

Custom recursive functions are complex, error‑prone, and often need special‑case handling for various types, with uncertain performance.

Third‑party libraries increase project dependencies and bundle size.

structuredClone: Modern JavaScript Deep‑Copy Solution

Introduced in the 2022 WHATWG HTML specification, structuredClone() is now supported by all major browsers and Node.js, providing an efficient, standardized way to deep‑copy complex objects.

Basic Usage

Using structuredClone() is straightforward:

Just one line of code, no extra libraries or recursive functions needed.

Advantages of structuredClone

Built into the JavaScript engine, requiring no external dependencies.

Handles circular references without throwing errors.

Correctly clones most built‑in types, including Date, RegExp, Map, Set, ArrayBuffer, TypedArray, Blob, File, ImageData, and nested complex structures.

Example: Handling Circular References

Supported Data Types in Detail

structuredClone()

supports a far broader range of types than the JSON method:

const original = {
  // Primitive types
  string: 'Hello',
  number: 123,
  boolean: true,
  null: null,
  undefined: undefined, // preserved by structuredClone

  // Date object (preserved as Date)
  date: new Date('2023-06-15'),

  // RegExp object (preserved as RegExp)
  regex: /pattern/g,

  // Collection types
  map: new Map([['key', 'value']]),
  set: new Set([1, 2, 3]),

  // Binary data
  arrayBuffer: new Uint8Array([1, 2, 3]).buffer,
  typedArray: new Uint8Array([1, 2, 3]),

  // Nested arrays and objects
  array: [1, 2, { nested: true }],
  object: { nested: { deep: true } }
};

const clone = structuredClone(original);

// Verify type preservation
console.log(clone.date instanceof Date);          // true
console.log(clone.regex instanceof RegExp);      // true
console.log(clone.map instanceof Map);           // true
console.log(clone.set instanceof Set);           // true
console.log(clone.arrayBuffer instanceof ArrayBuffer); // true
console.log(clone.typedArray instanceof Uint8Array);   // true

Limitations of structuredClone

While structuredClone() solves most deep‑copy problems, it still has some constraints:

Functions are not cloned, similar to the JSON method.

Prototype chains are not preserved; cloned objects lose the original prototype.

DOM nodes cannot be cloned.

Error objects are not supported.

Overall, structuredClone() represents a significant advancement in the JavaScript ecosystem, offering a simple, efficient, and standardized solution for deep copying in most common scenarios, and it is now supported by all major browsers.