Reference · print-friendly

Structured clone decision playbook

One page for design reviews. Walk top to bottom; stop when a row rejects the current candidate.

← Lesson 5 Copy spectrum Type matrix Transfer Checklist Glossary

1. Gate A · Job (which copy tool?)

If…	Prefer…
New outer object; nested refs may stay shared	Shallow copy
A JSON document (HTTP, file, log)	`JSON.stringify` — design for loss
Same-realm snapshot; nested identity must break	`structuredClone(plainData)`
Value already crossing postMessage / BC / IDB / History	Implicit clone — don’t double-copy
Large binary; sender is done with the bytes	Transfer `.buffer` (in value and list)
Methods, class identity, versioned wire, revival	Custom serializer

2. Gate B · Shape (will it survive?)

Keep: Date, Map, Set, cycles, buffers, Blobs, undefined keys.
Flatten: class instances → plain Object; getters snap to data.
Throw: functions, DOM, symbol values, Promise, WeakMap, Proxy (React-wrapped objects if they are Proxies — snapshot a plain DTO).
Send data, not behavior. Rebuild methods on each side.

3. Gate C · Move (clone vs transfer)

Both sides still need the bytes → clone.
Sender is done → structuredClone(value, { transfer: [buf] }) or postMessage(value, [buf]). List .buffer, not the typed array.
Buffer must be in the value. An orphan list entry still detaches and never arrives.
No transfer list on BroadcastChannel, IndexedDB, History.
Detached is terminal — cannot clone or transfer again.

4. Gate D · Cost & ship risks

Huge / high-frequency graphs → patches, chunking, or transfer (Surma), not another clone helper.
Don’t structuredClone and then post/put/pushState unless you need a local snapshot for another reason.
Loud vs silent: clone throws on functions/DOM/Proxy; JSON drops or stringifies. Know which algorithm you are on.

Sentence you should be able to say

“We use shallow | JSON | structuredClone | implicit clone | transfer | custom serializer because job; shape is plain data / keep-flatten-throw; move is copy | list .buffer on the payload | no list here; we own cost · detach · no double-clone · no Proxy.”