Deep copies and structuredClone

Understanding Deep copies and structuredClone

A spread copy duplicates a property list: each own enumerable key is read from the source and written into a fresh object. If a value is a number or a string, the copy is genuinely independent afterwards; if the value is an object, what gets duplicated is the reference, so both objects still point at the same nested array or Map. A deep copy instead walks the whole reachable graph and builds a parallel graph, so the copy shares no object with the original. structuredClone(value) performs that walk and returns the root of the new graph.

structuredClone is the structured clone algorithm that postMessage and IndexedDB already used, exposed as an ordinary function. That origin explains its rules: the value is written out into a realm-independent data form and then rebuilt from nothing, so anything whose meaning is code rather than data cannot make the trip. A function or a DOM node raises a DOMException named DataCloneError, and a class instance clones successfully but arrives as a plain object because the link to its prototype is not data. Only own enumerable string-keyed properties are carried over, and they are read with a normal get, so an own getter runs once during cloning and its result is stored as a fixed value.

Against the older JSON.parse(JSON.stringify(value)) trick the differences are not cosmetic. The algorithm remembers every object it has already visited, so a cycle such as obj.self = obj is reproduced as a clone pointing at itself, while JSON.stringify throws a TypeError on the same input. Dates stay Dates, Map, Set, RegExp, typed arrays, Error objects and BigInt all survive, and a property whose value is undefined is kept rather than dropped. The trade is that structuredClone refuses what it cannot represent instead of quietly degrading it, so you find out at the clone site rather than three functions later.

Property attributes are outside the payload as well, which matters when the source was locked down: a frozen or non-writable source produces a plain writable clone, and non-enumerable or symbol-keyed properties vanish without an error.

const settings = {
  name: 'editor',
  updated: new Date('2024-03-01T09:30:00Z'),
  limits: { retries: 3, tags: ['draft', 'wip'] },
  seen: new Map([['a', 1]])
};
settings.self = settings;

const deep = structuredClone(settings);
const shallow = { ...settings };

shallow.limits.retries = 99;
console.log('shallow edit ->', settings.limits.retries);

deep.limits.retries = 7;
console.log('deep edit ->', settings.limits.retries, deep.limits.retries);

console.log(deep.updated instanceof Date, deep.updated.getTime() === settings.updated.getTime());
console.log(deep.seen instanceof Map, deep.seen.get('a'));
console.log(deep.self === deep, deep.self === settings);

Worked examples

const record = {
  when: new Date('2020-06-01T12:00:00Z'),
  count: NaN,
  missing: undefined,
  ids: new Set([1, 2])
};

const viaJson = JSON.parse(JSON.stringify(record));
console.log(typeof viaJson.when, viaJson.count, 'missing' in viaJson, viaJson.ids instanceof Set);

const viaClone = structuredClone(record);
console.log(viaClone.when instanceof Date, Number.isNaN(viaClone.count), 'missing' in viaClone, viaClone.ids.has(2));

try {
  JSON.stringify({ total: 9007199254740993n });
} catch (err) {
  console.log(err.name);
}
console.log(structuredClone({ total: 9007199254740993n }).total === 9007199254740993n);

const source = {
  base: 2,
  get doubled() { return this.base * 2; },
  nested: { list: [1, 2] }
};

const copy = structuredClone(source);
source.base = 50;

console.log(source.doubled, copy.doubled);
console.log(Object.getOwnPropertyDescriptor(copy, 'doubled').get);
console.log(copy.nested === source.nested, copy.nested.list[1]);

class Point {
  constructor(x, y) { this.x = x; this.y = y; }
  scaled(k) { return new Point(this.x * k, this.y * k); }
}

const state = { at: new Point(3, 4), onSave() {} };

try {
  structuredClone(state);
} catch (err) {
  console.log(err.name);
}

const { onSave, ...data } = state;
const copy = structuredClone(data);
console.log(copy.at instanceof Point, typeof copy.at.scaled, copy.at.x);

copy.at = Object.assign(new Point(0, 0), copy.at);
console.log(copy.at instanceof Point, copy.at.scaled(2).y, copy.at === state.at);

Important notes

Common mistakes

Try it yourself