Immutability

Copies instead of surprise changes

Immutability is the habit of treating data like a saved version. When something changes, you make a new version instead of editing the version other code might still be reading. JavaScript does not force this style for ordinary objects and arrays, but it gives you enough tools to use it deliberately.

You already learned in Objects & references that objects and arrays are shared by reference. You also learned in Pure functions & side effects that functions are easier to test when they do not edit their inputs. Immutability is the practical bridge: copy the changed path, return the next value, and let the old value remain true.

Object spread, { ...state }, creates a new object and copies the source object’s own enumerable properties. Array spread, [...items], creates a new array with the same elements. Both are shallow: if a copied property is itself an object, the new wrapper points at the same nested object.

const user = { name: "Ada", city: "Paris" };
const next = { ...user, city: "Tokyo" };
console.log(user.city); // Paris
console.log(next.city); // Tokyo

const state = { user: { address: { city: "Paris" } } };
const next = { ...state };
next.user.address.city = "Tokyo";
console.log(state.user.address.city); // Tokyo

When the changed value is nested, spread every object on the route to that value. That may look noisy at first, but it is wonderfully explicit: each spread says, “this level is part of the new version.”

Here is the heart of the lesson. The state shape has a top-level object, a nested user, a deeper address, and a separate tags array. Try the three update styles, then read the identity checks like a reference map.

1const state = {2  user: { name: "Ada", address: { city: "Paris" } },3  tags: ["admin", "writer"],4};5 6const next = {7  ...state,8  user: {9    ...state.user,10    address: {11      ...state.user.address,12      city: "Tokyo",13    },14  },15};16 17console.log(state.user.address.city);18console.log(next.user.address.city);19console.log(state === next);20console.log(state.user === next.user);21console.log(state.user.address === next.user.address);22console.log(state.tags === next.tags);

The correct update makes state !== next, state.user !== next.user, and state.user.address !== next.user.address. It keeps state.tags === next.tags because tags did not change. That last equality is not a bug; it is intentional structural sharing.

1const state = {Run2  user: { name: "Ada", address: { city: "Paris" } },3  tags: ["admin", "writer"],4};5 6const next = {7  ...state,8  user: {9    ...state.user,10    address: {11      ...state.user.address,12      city: "Tokyo",13    },14  },15};16 17console.log(state.user.address.city);18console.log(next.user.address.city);19console.log(state === next);20console.log(state.user === next.user);21console.log(state.user.address === next.user.address);22console.log(state.tags === next.tags);

Arrays have both families: methods that edit the original and methods that return a new array. The names are easy to mix up, so always ask, “what does the original array print after this line?”

1const numbers = [3, 1, 2];2const pushed = numbers.push(4);3console.log(numbers.join(","));4 5const sorted = numbers.toSorted();6console.log(numbers.join(","));7console.log(sorted.join(","));8 9const mapped = numbers.map((n) => n * 10);10console.log(numbers.join(","));11console.log(mapped.join(","));

Mutating classics include push, sort, reverse, and splice. Copying options include concat, spread, map, filter, and the ES2023 copying methods toSorted, toReversed, toSpliced, and with. Node 22 and modern browsers support those ES2023 methods; older runtimes may need a fallback.

Messaging & structured cloning introduced the structured clone algorithm. structuredClone(value) deep copies supported data: plain objects, arrays, Maps, Sets, Dates, typed arrays, and cycles. It throws DataCloneError for functions because functions are behavior, not cloneable data.

Freezing, sealing & immutability covered the object locks. The crucial reminder here is that Object.freeze is shallow. In strict code, writing a frozen top-level property throws a TypeError; in sloppy classic scripts it often fails silently. But a nested object still changes unless you freeze it too.

1"use strict";2const original = { user: { name: "Ada" }, tags: ["js"] };3const clone = structuredClone(original);4clone.user.name = "Lin";5console.log(original.user.name);6console.log(clone.user.name);7 8const frozen = Object.freeze({ user: { name: "Ada" } });9frozen.user.name = "Grace";10console.log(frozen.user.name);11try {12  frozen.user = { name: "Lin" };13} catch (error) {14  console.log(error instanceof TypeError);15}

Maps and Sets are objects, but their entries live in internal storage. Freezing a Map object does not freeze that internal storage, so frozenMap.set("theme", "light") still changes the Map. The safer API is often a wrapper that only exposes read methods.

1function readonlyMap(map) {2  return {3    get: (key) => map.get(key),4    has: (key) => map.has(key),5    entries: () => map.entries(),6  };7}8 9const frozenMap = Object.freeze(new Map([["theme", "dark"]]));10frozenMap.set("theme", "light");11console.log(frozenMap.get("theme"));12 13const view = readonlyMap(frozenMap);14console.log(view.get("theme"));15console.log("set" in view);

A wrapper is not a force field around the original collection. Code that still has the original Map can mutate it. The wrapper works by controlling what you hand to readers. For larger apps, libraries such as Immer can produce immutable updates from draft-looking code; true persistent collection libraries go further. Records and Tuples are a proposal for deeply immutable value types, but they are not part of JavaScript today.

Shared mutable state is the spooky version of references: two owners have the same object, one owner mutates it, and the other owner sees a change it did not ask for. UI code runs into this constantly when two components receive the same array or object.

1const left = { items: ["draft", "review"] };2const right = { items: left.items };3 4left.items.push("published");5console.log(right.items.join(","));6 7const saferLeft = { items: ["draft", "review"] };8const saferRight = { items: saferLeft.items };9const nextLeft = { ...saferLeft, items: [...saferLeft.items, "published"] };10console.log(saferRight.items.join(","));11console.log(nextLeft.items.join(","));

Notice that the fixed version does not deep-clone everything. It only makes a new array for the changed owner. The old reader keeps the old array and remains stable. This is why immutable updates pair so well with pure functions: the function can return the next state without editing its input.

Structural sharing is the reason immutable updates can be fast enough for real applications. You do not need a deep copy for every update. You need new references from the root to the changed value, plus reused references for unchanged branches. That also makes comparison cheap: if oldState.user !== nextState.user, something under user changed; if oldState.tags === nextState.tags, tags were reused.

• “I used const, so it is immutable.” const protects the variable binding, not the object’s properties.
• “Spread made a deep copy.” Spread copies one level of own enumerable properties.
• “Object.freeze protects the whole tree.” Freeze is shallow unless you recursively freeze nested objects.
• “A frozen Map cannot change.” Map entries are internal; set still works on a frozen Map.
• “Immutable means copy everything.” Structural sharing deliberately reuses unchanged references.
• “structuredClone is always the best update tool.” It is useful for data snapshots, but it cannot clone functions and may be more work than a focused spread update.

Key takeaways

• Immutable updates return a new version instead of changing the old one.
• Spread is shallow: copy every level on the path to the changed value.
• Use copying array methods when callers still need the original array.
• structuredClone deep-copies supported data and throws for functions.
• Object.freeze is shallow, strict writes throw, and frozen Maps can still change entries.
• Structural sharing reuses unchanged references on purpose.

Immutability means each update creates a trustworthy next value while the previous value remains unchanged.

Up next: Currying & partial application.