structuredClone & Deep Copying

Also Known As

TL;DR

Explanation

Deep copying creates an independent copy of a nested object — mutations to the copy don't affect the original. Before structuredClone (2022): JSON roundtrip (loses undefined, functions, Dates become strings, no circular refs), Object.assign/spread (shallow only), lodash cloneDeep (dependency). structuredClone handles: Date, Map, Set, ArrayBuffer, RegExp, circular references. Does not handle: functions, DOM nodes, class instances (loses prototype). Available in all modern browsers and Node 17+.

Common Misconception

Why It Matters

Common Mistakes

• Spread operator for nested objects: {...obj} — only shallow; nested objects are still shared.
• JSON roundtrip losing Date objects — Date becomes string, never comes back as Date.
• Not using structuredClone for state management — accidentally mutating shared state causes hard-to-trace bugs.
• structuredClone on objects with functions — functions are not cloneable; they are silently dropped.

Code Examples

// JSON roundtrip — lossy:
const original = { date: new Date(), value: undefined, map: new Map() };
const clone = JSON.parse(JSON.stringify(original));
// clone.date is a string, not Date
// clone.value is gone (undefined dropped)
// clone.map is {} (Map not supported)

// Shallow copy mutation bug:
const state = { user: { name: 'Alice' } };
const copy = { ...state };
copy.user.name = 'Bob'; // ALSO mutates state.user.name!

// structuredClone — handles most types correctly:
const original = { date: new Date(), set: new Set([1,2,3]), arr: [1,[2,3]] };
const clone = structuredClone(original);
clone.date; // Still a Date object ✓
clone.set;  // Still a Set ✓
clone.arr[1].push(4); // Does NOT affect original.arr ✓

// For class instances, implement a clone method:
class Order {
    clone(): Order {
        return Object.assign(new Order(), structuredClone({ ...this }));
    }
}

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/API/structuredClone

Tags

Related Terms