Immutability

Make a new version instead of changing the old one

To mutate a value means to change it in place. For example, user.city = "Tokyo" changes the user object itself.

Immutability is a habit: you don't change data that other code may still be reading. When something needs to change, you make a new version with the change in it. The old version stays exactly as it was.

JavaScript doesn't force this habit. Normal objects and arrays can always be changed. But JavaScript gives you tools to copy, and tools to lock. This lesson shows each tool and its limits.

Two earlier lessons lead here:

• In Objects & references, you learned that a variable holds a reference to an object: a pointer to it, not a copy of it. Two variables can point at the same object.
• In Pure functions & side effects, you learned that functions are easier to test when they don't change their inputs.

Immutability puts these together. You copy the parts you change, return the new value, and leave the old value alone.

The three dots ... are called spread. They copy things into a new object or array:

• { ...state } makes a new object. It copies every property that state holds itself (its own properties that show up when you list them).
• [...items] makes a new array with the same items in the same order.

Both copies are shallow. Shallow means only the top level is new. If a property holds another object, the copy gets a reference to that same object, not a new one. An object inside another object is called a 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

In the first example, line 2 copies user and sets a new city on the copy. city is a top-level property, so the copy has its own. user.city stays Paris, and next.city is Tokyo.

In the second example, line 2 copies only the top level of state. The user property in next points at the same user object as in state. Line 3 changes the city through next, so line 4 prints Tokyo for state too.

The fix: when the value you change is nested, spread every object on the way to it. The code gets longer, but each spread clearly says "this level is new in the next version."

This is the main experiment of the lesson. The state object has these parts:

• a user object,
• an address object inside user, which holds the city,
• a tags array, next to user.

Each button changes the city from Paris to Tokyo in a different way. The result shows two things: the city in the old and the new state, and which objects are new.

The checks use ===. For objects, === asks "is this the very same object?", not "do they look the same?". "shared" means the old and new state use that same object. "new" means the new state has its own copy.

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 three new objects, one for each level on the way to city:

• state !== next: a new top-level object.
• state.user !== next.user: a new user.
• state.user.address !== next.user.address: a new address.

It keeps state.tags === next.tags, because the tags didn't change. This is not a mistake. Sharing the parts that didn't change is called structural sharing.

Now step through the code one line at a time. Choose the correct update or the shallow mistake.

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);

Some array methods change the array you call them on. Others leave it alone and return a new array. The names are easy to mix up. After each line, ask: "What does the original array print now?"

const items = ["tea", "bread", "rice"];
const reversed = items.toReversed();
const replaced = items.with(1, "coffee");
const inserted = items.toSpliced(1, 1, "milk", "eggs");

console.log(items.join(","));
console.log(reversed.join(","));
console.log(replaced.join(","));
console.log(inserted.join(","));

Line by line:

1. Line 1 makes a shopping list, items.
2. Line 2: toReversed() returns a copy in reverse order.
3. Line 3: with(1, "coffee") returns a copy where the item at index 1 is coffee.
4. Line 4: toSpliced(1, 1, "milk", "eggs") returns a copy. At index 1 it removes one item and puts milk and eggs there.

The four logs show that items still prints tea,bread,rice. Each new array has its one change. An index below zero counts from the end, so items.with(-1, "fruit") replaces the last item.

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(","));

These methods change the original array:

• push adds an item at the end.
• sort puts the items in order.
• reverse flips the order.
• splice removes or inserts items.

These return a new array and leave the original alone: concat, spread, map, filter, toSorted, toReversed, toSpliced, and with. The last four were added to JavaScript in 2023 (ES2023). Node 22 and current browsers have them. Older browsers may not.

Messaging & structured cloning showed structuredClone(value). It makes a deep copy: a copy of every level, nested objects too. It works on data:

• plain objects and arrays,
• Maps, Sets, and Dates,
• typed arrays (arrays of raw numbers),
• objects that point back at themselves.

It can't copy functions. A function is code, not data. If the value holds a function, structuredClone throws an error called DataCloneError.

Freezing, sealing & immutability showed the object locks. Object.freeze(obj) locks the properties of obj: you can't add, remove, or change them. But it locks only the top level. A nested object can still change unless you freeze it too.

What happens when code writes to a locked property depends on the mode:

• In strict mode (code that starts with "use strict", and all modules and classes), JavaScript throws a TypeError.
• In sloppy mode (an old-style script without "use strict"), the write is ignored without any error.

const settings = { theme: "dark" };
settings.theme = "light";
console.log(settings.theme);

const sealed = Object.seal({ theme: "dark" });
sealed.theme = "light";
sealed.mode = "quiet";
console.log(sealed.theme);
console.log("mode" in sealed);

const closed = Object.preventExtensions({ theme: "dark" });
closed.theme = "light";
closed.mode = "quiet";
console.log(closed.theme);
console.log("mode" in closed);

This code runs in sloppy mode, so blocked writes are ignored instead of throwing. Line by line:

1. Lines 1 to 3: the write works and prints light. const only stops you from giving settings a different value. The object itself can still change.
2. Lines 5 to 9: Object.seal lets you change a property that already exists, so theme becomes light. It blocks new properties, so "mode" in sealed prints false.
3. Lines 11 to 15: Object.preventExtensions also blocks new properties. The existing theme still changes to light.

"use strict";
const frozen = Object.freeze({ theme: "dark" });
let threw = false;
try {
  frozen.theme = "light";
} catch (error) {
  threw = error instanceof TypeError;
}
console.log(frozen.theme);
console.log(threw);

Line 1 turns on strict mode. Line 5 tries to change the frozen theme, which throws. Lines 6 and 7 catch the error and check that it is a TypeError. The code prints dark and true: the value didn't change, and JavaScript reported a TypeError.

Use a lock to catch writes you didn't mean to make. When you do want a change, make a new copy with the change.

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}

This table compares the tools for copying and locking. Read one row per tool.

This table compares the four kinds of objects, from the most open to the most locked.

Maps and Sets are objects, but they don't keep their entries in normal properties. They keep them in hidden storage inside the object. Object.freeze locks only normal properties, so it doesn't lock that storage. After freezing a Map, frozenMap.set("theme", "light") still changes it.

A better way is a read-only view, also called a wrapper. It is a small object that keeps the real Map inside and offers only reading methods, such as get and has. It has no set method, so code that gets the view has no way to write.

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);

The view doesn't lock the Map itself. Code that still has the real Map can change it. The view works because you choose what to give to other code: you give out the view, not the Map.

Some libraries help in bigger apps:

• Immer lets you write code that looks like a change, and it builds the new copy for you.
• Other libraries offer collections that can never change.

Records and Tuples were a proposal for objects and arrays that can never change. They are not part of JavaScript today.

Shared mutable state means two parts of a program hold a reference to the same object or array, and one of them changes it. The other part then sees a change it never asked for. This happens a lot on web pages, when two parts of the page get the same array.

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(","));

The fix doesn't deep-copy everything. On line 9, only nextLeft gets a new array with the extra item. saferRight keeps the old array, so it still prints draft,review.

This is why immutable updates fit well with pure functions. The function returns the new state and doesn't change its input.

Structural sharing is why immutable updates are fast enough for real apps. You don't deep-copy everything on each change. You make new objects only on the way from the top to the changed value. Everything else is shared.

It also makes changes quick to find:

• If oldState.user !== nextState.user, something inside user changed.
• If oldState.tags === nextState.tags, the tags are the same array, so they didn't change.

• "I used const, so the object can't change." const only stops you from giving the variable a different value. The object's properties can still change.
• "Spread made a deep copy." Spread copies only the top level. Nested objects are still shared.
• "Object.freeze locks every level." Object.freeze locks only the top level. Nested objects need their own freeze.
• "A frozen Map can't change." A Map keeps its entries in hidden storage, so set still works on a frozen Map.
• "Immutable means copy everything." Structural sharing keeps the parts that didn't change, on purpose.
• "structuredClone is always the best way to update." It is good for saving a full copy of data. But it can't copy functions, and it copies far more than a small spread update needs.

Key takeaways

• An immutable update returns a new version and leaves the old one as it was.
• Spread copies only the top level. Copy every object on the way to the value you change.
• Use array methods that return a copy when other code still needs the original array.
• structuredClone copies every level of data, and throws for functions.
• Object.freeze locks only the top level. Writes to it throw in strict mode. A frozen Map can still change its entries.
• Structural sharing keeps the parts that didn't change, on purpose.

Immutability means each change makes a new value, and the old value stays exactly as it was.

Up next: Currying & partial application.