globalThis and structuredClone

## The two things people mean by "copy" A **shallow** copy (`{ ...obj }`, `Object.assign({}, obj)`) makes a new outer object whose properties still point at the same nested objects. A **deep** copy makes new objects all the way down, so mutating the copy cannot be observed through the original. The JavaScript standard library had no deep-copy function for a long time, which is why `JSON.parse(JSON.stringify(x))` became folklore. ## Why the JSON round trip is not a deep copy It is a *serialisation followed by a parse*, and it can only express what the JSON data model can express. Going through it, at the level that matters for copying: - values with no JSON representation — `undefined`, functions, symbols — are dropped from objects and become `null` inside arrays; - a `Date` comes back as a string, because serialising it produced a string; - `Map`, `Set`, `RegExp` and class instances come back as ordinary objects, usually empty ones, because their state is not in enumerable own properties; - `BigInt` throws; - a cycle throws, because there is no way to write one down. So the round trip works only for graphs that were already plain JSON-shaped data, and fails *silently* for most of the interesting cases — which is what makes it dangerous rather than merely limited. ## What structuredClone does instead `structuredClone(value)` runs the **structured clone algorithm**, which walks the live object graph and builds a parallel graph of the same kinds of objects. Types it reproduces as themselves include `Date`, `RegExp`, `Map`, `Set`, `ArrayBuffer`, `DataView`, the typed arrays, and `Error` objects; in a browser it also handles host types marked serializable, such as `Blob`, `File` and `ImageData`. It handles graph shape, not just tree shape: ```js const state = { when: new Date(), tags: new Set(['a']), by: new Map([['k', 1]]) }; state.self = state; // a cycle const shared = { id: 1 }; state.left = shared; state.right = shared; // two paths to one object const copy = structuredClone(state); copy.when instanceof Date; // true copy.tags.has('a'); // true copy.self === copy; // true — cycle preserved, not infinite copy.left === copy.right; // true — sharing preserved copy.left === shared; // false — but it is a new object ``` That cycle-and-sharing preservation is the property a hand-written recursive clone usually gets wrong, and it is the strongest single reason to prefer the built-in. ## What it refuses: DataCloneError The algorithm has no way to copy behaviour, so it does not try. A function or a symbol anywhere in the graph makes the call throw a `DataCloneError` (a `DOMException`), and the throw is **all-or-nothing**: you do not get a partial clone with the offending property omitted. ```js structuredClone({ n: 1, onDone() {} }); // DataCloneError: onDone() {} could not be cloned. ``` Browser DOM nodes are likewise not cloneable and throw. Note that this differs from `JSON.stringify`, which drops functions quietly — structuredClone's loudness is a feature: it tells you the value you were about to copy contained something a copy cannot represent. ## What it changes silently The important silent transformation is **prototypes are not preserved**. Cloning an instance of your own class produces a plain object carrying the same own data properties, with `Object.prototype` as its prototype: ```js class User { constructor(name) { this.name = name; } greet() { return `hi ${this.name}`; } } const clone = structuredClone(new User('ada')); clone.name; // 'ada' clone instanceof User; // false clone.greet; // undefined ``` In the same vein, accessor properties are read and stored as plain data, and property attributes such as non-enumerable or non-writable are not carried across. Private class fields (`#x`) are not own properties at all, so they do not survive either. `structuredClone` also ignores `toJSON()` — that hook belongs to JSON serialisation and has no role in the clone algorithm. ## Where it comes from and where it is available `structuredClone` is a global function defined by the HTML specification rather than by ECMAScript, which is why you will not find it in a language reference under `Object`. The underlying algorithm has been in the platform for years as the mechanism behind `postMessage` and IndexedDB storage; exposing it as a callable function is the recent part. It is available in evergreen browsers from early 2022 and in Node from version 17. ## How to decide Use `structuredClone` when you need a deep copy of *data* — state snapshots for undo, defensive copies before a mutating routine, detaching a value from a reactive store. Use a manual or library clone when the graph contains behaviour or when you must preserve class identity. Use `JSON.parse(JSON.stringify(x))` essentially never as a clone: if the data really is JSON-shaped, structuredClone copies it correctly too and faster; if it is not, the JSON round trip corrupts it quietly.