Immutable updates: change the data, not the copy

A variable holding an object or array holds a reference — an arrow pointing at the object, not the object itself. Copying the variable copies the arrow:

const a = { name: "Ada" };
const b = a;      // same object, two arrows
b.name = "Grace";
a.name;           // "Grace"

Spread ({ ...obj }, [...arr]) makes a new outer object and copies each property into it. But a property that holds an object holds an arrow too, and the arrow is what gets copied:

const state = { user: { name: "Ada" }, count: 1 };
const next = { ...state, count: 2 };

next === state;           // false — a new outer object
next.user === state.user; // true  — the SAME inner object
next.user.name = "Grace";
state.user.name;          // "Grace" — the "copy" changed the original

That's what shallow means: one level copied, everything below it shared.

To change something nested without touching the original, copy every level on the path from the top down to the thing you change, and nothing else:

const next = {
  ...state,                          // new outer object
  user: { ...state.user, name: "Grace" }, // new user object with the change
};

state.user.name; // "Ada" — untouched

Everything you didn't change is still shared between state and next — and that's fine, as long as nobody mutates it. "Immutable updates" means exactly this: never change an existing object; build a new one with the change, reusing the parts that stayed the same.

A board holds columns, each column holds cards. Every update below returns a new board and leaves the old one exactly as it was:

type Card = { id: string; title: string; done: boolean; tags: string[] };
type Board = { name: string; columns: { id: string; cards: Card[] }[] };

// Toggle one card: copy the board, the columns array, the one column, its cards array, the card.
function toggleCard(board: Board, columnId: string, cardId: string): Board {
  return {
    ...board,
    columns: board.columns.map((col) =>
      col.id !== columnId
        ? col // untouched columns are reused as-is
        : {
            ...col,
            cards: col.cards.map((card) =>
              card.id === cardId ? { ...card, done: !card.done } : card,
            ),
          },
    ),
  };
}

// Add a tag: the tags array is one level deeper, so it gets its own copy.
const tagged = { ...card, tags: [...card.tags, "urgent"] };

// Insert, remove, replace, move — the ES2023 copying methods:
const inserted = cards.toSpliced(2, 0, newCard);      // insert at index 2
const removed = cards.filter((c) => c.id !== cardId); // remove by id
const replaced = cards.with(index, updatedCard);      // replace at an index
const moved = cards.toSpliced(from, 1).toSpliced(to, 0, cards[from]); // move one card
const sorted = cards.toSorted((a, b) => a.title.localeCompare(b.title));

What to notice:

• map is the workhorse. It returns a new array, and the callback decides per item: return the same object (unchanged) or a new one (changed). Unchanged items keep their identity — which is what lets memoized children and selectors skip work.
• Every level on the path gets a spread: board → columns → the column → cards → the card. Miss one and you are mutating something the old board still points to.
• { ...card, tags: [...card.tags, "urgent"] }, not { ...card } then push. Spreading the card copies the arrow to its tags array; pushing into it changes the original card's tags too.
• with(index, value) throws a RangeError for an index outside the array (negative indexes count from the end, like at). arr[index] = value on a copy would silently grow the array instead.

When the nesting gets deeper than this, the spreads become hard to read, and that's the usual argument for flattening state (store cards by id, columns as lists of ids) or for a helper library. React's docs point to Immer, which lets you write draft.columns[0].cards[2].done = true against a draft and produces the copies for you.

structuredClone: a real deep copy, with limits

structuredClone(value) (in every major browser since 2022, Node 17+) copies every level. Unlike the old JSON.parse(JSON.stringify(x)) trick, it keeps Date, Map, Set, RegExp, typed arrays and undefined values, and handles circular references. It isn't magic, though. MDN's list of what the structured clone algorithm can't do:

• Functions throw. An object holding a callback fails with a DataCloneError — the whole call, not just that property.
• DOM nodes throw, the same way.
• The prototype chain is not copied. A class instance comes back as a plain object with its fields and none of its methods: structuredClone(new Money(250)) is { cents: 250 }, and copy instanceof Money is false.
• Getters, setters and property descriptors are not copied: a getter is read once and stored as a plain value; a read-only property comes back writable. Class private fields (#x) are dropped.

const copy = structuredClone({ at: new Date(0), price: new Money(250) });
copy.at instanceof Date;    // true
copy.price instanceof Money; // false — methods gone

structuredClone({ onSave: () => {} }); // DataCloneError

Deep copying is usually the wrong fix for a state update

It's tempting to structuredClone(state), mutate the clone freely, and return it. It works, but it gives every object in the state a new identity, changed or not. Every memo child sees new props, every selector returns a "new" value, every effect that depends on a slice re-runs. The targeted update — copy the changed path, reuse the rest — is what lets everything else skip work. Use structuredClone when you need an independent snapshot (a form draft, an undo history entry, data handed to code you don't trust), not as the default way to update.

Object.freeze is shallow, and returns the same object

Object.freeze(obj) makes obj's own properties read-only and stops new ones being added. It freezes that one object: nested objects stay writable. And it returns the same object, not a frozen copy.

const config = Object.freeze({ retries: 3, api: { timeout: 1000 } });
config.retries = 5;        // TypeError in strict mode; silently ignored otherwise
config.api.timeout = 9999; // works — api itself isn't frozen

ES modules and class bodies are always strict, so in modern code the first line throws. Array methods throw on a frozen array in any mode: Object.freeze([3, 1, 2]).sort() is a TypeError, while .toSorted() works.