7a:T7f6,// MUTABLE Point - State can change after creation public class MutablePoint { public double x; // Public, modifiable field public double y; // Public, modifiable field public MutablePoint(double x, double y) { this.x = x; this.y = y; } public void move(double dx, double dy) { // Modifies the point in place this.x += dx; this.y += dy; } } // Usage — The same object changes over time MutablePoint p = new MutablePoint(0, 0); System.out.println("Initial: (" + p.x + ", " + p.y + ")"); // (0, 0) p.move(5, 3); System.out.println("After move: (" + p.x + ", " + p.y + ")"); // (5, 3) // Problem: If you passed 'p' to another function earlier, // that function's reference now points to different data. // ───────────────────────────────────────────────────── // IMMUTABLE Point - State is fixed at creation public final class ImmutablePoint { private final double x; // Private, final — set once private final double y; // Private, final — set once public ImmutablePoint(double x, double y) { this.x = x; this.y = y; } public double getX() { return x; } // Read-only access public double getY() { return y; } // Read-only access public ImmutablePoint move(double dx, double dy) { // Returns a NEW point; original unchanged return new ImmutablePoint(this.x + dx, this.y + dy); } @Override public String toString() { return "ImmutablePoint(" + x + ", " + y + ")"; } } // Usage — Each operation creates a new object ImmutablePoint p1 = new ImmutablePoint(0, 0); ImmutablePoint p2 = p1.move(5, 3); // p1 unchanged, p2 is new System.out.println("p1: (" + p1.getX() + ", " + p1.getY() + ")"); // (0, 0) System.out.println("p2: (" + p2.getX() + ", " + p2.getY() + ")"); // (5, 3) // Any reference to p1 is guaranteed to always see (0, 0)7b:T6fd,# MUTABLE Point - State can change after creation class MutablePoint: def __init__(self, x: float, y: float): self.x = x # Public, modifiable attribute self.y = y # Public, modifiable attribute def move(self, dx: float, dy: float): """Modifies the point in place""" self.x += dx self.y += dy # Usage — The same object changes over time p = MutablePoint(0, 0) print(f"Initial: ({p.x}, {p.y})") # (0, 0) p.move(5, 3) print(f"After move: ({p.x}, {p.y})") # (5, 3) — Same object, different state! # Problem: If you passed 'p' to another function earlier, # that function's reference now points to different data. # ───────────────────────────────────────────────────── # IMMUTABLE Point - State is fixed at creation class ImmutablePoint: def __init__(self, x: float, y: float): self._x = x # Private, set once self._y = y # Private, set once @property def x(self) -> float: return self._x # Read-only access @property def y(self) -> float: return self._y # Read-only access def move(self, dx: float, dy: float) -> 'ImmutablePoint': """Returns a NEW point; original unchanged""" return ImmutablePoint(self._x + dx, self._y + dy) def __repr__(self): return f"ImmutablePoint({self._x}, {self._y})" # Usage — Each operation creates a new object p1 = ImmutablePoint(0, 0) p2 = p1.move(5, 3) # p1 unchanged, p2 is new print(f"p1: ({p1.x}, {p1.y})") # (0, 0) — Still original values! print(f"p2: ({p2.x}, {p2.y})") # (5, 3) — New object with new values # Any reference to p1 is guaranteed to always see (0, 0)7c:T78a,// MUTABLE Point - State can change after creation class MutablePoint { public x: number; // Public, modifiable property public y: number; // Public, modifiable property constructor(x: number, y: number) { this.x = x; this.y = y; } move(dx: number, dy: number): void { // Modifies the point in place this.x += dx; this.y += dy; } } // Usage — The same object changes over time const p = new MutablePoint(0, 0); console.log(`Initial: (${p.x}, ${p.y})`); // (0, 0) p.move(5, 3); console.log(`After move: (${p.x}, ${p.y})`); // (5, 3) // Problem: If you passed 'p' to another function earlier, // that function's reference now points to different data. // ───────────────────────────────────────────────────── // IMMUTABLE Point - State is fixed at creation class ImmutablePoint { private readonly _x: number; // Private, readonly — set once private readonly _y: number; // Private, readonly — set once constructor(x: number, y: number) { this._x = x; this._y = y; } get x(): number { return this._x; } // Read-only access get y(): number { return this._y; } // Read-only access move(dx: number, dy: number): ImmutablePoint { // Returns a NEW point; original unchanged return new ImmutablePoint(this._x + dx, this._y + dy); } toString(): string { return `ImmutablePoint(${this._x}, ${this._y})`; } } // Usage — Each operation creates a new object const p1 = new ImmutablePoint(0, 0); const p2 = p1.move(5, 3); // p1 unchanged, p2 is new console.log(`p1: (${p1.x}, ${p1.y})`); // (0, 0) — Still original! console.log(`p2: (${p2.x}, ${p2.y})`); // (5, 3) — New object // Any reference to p1 is guaranteed to always see (0, 0)7d:Tc0d,// SHALLOW IMMUTABILITY — The dangerous illusion import java.util.List; import java.util.ArrayList; public class ShallowlyImmutablePerson { /** * BROKEN: This class LOOKS immutable but isn't! * The 'address' field references a mutable List. */ private final String name; private final List address; // Danger: final ≠ immutable contents! public ShallowlyImmutablePerson(String name, List address) { this.name = name; this.address = address; // Danger: stores reference, not copy! } public String getName() { return name; } public List getAddress() { return address; } // Danger! } // The illusion of immutability... List addressList = new ArrayList<>(); addressList.add("123 Main St"); addressList.add("Apt 4"); ShallowlyImmutablePerson person = new ShallowlyImmutablePerson("Alice", addressList); System.out.println("Original: " + person.getAddress()); // [123 Main St, Apt 4] // External mutation through original reference — BREAKS "immutability" addressList.add("New York"); System.out.println("After external mutation: " + person.getAddress()); // [123 Main St, Apt 4, New York] // Mutation through returned reference — ALSO breaks "immutability" person.getAddress().clear(); System.out.println("After direct mutation: " + person.getAddress()); // [] // ───────────────────────────────────────────────────── // DEEP IMMUTABILITY — True protection import java.util.Collections; import java.util.List; import java.util.ArrayList; public final class DeeplyImmutablePerson { /** * CORRECT: True immutability with defensive copying * and unmodifiable collections. */ private final String name; private final List address; // Internally immutable public DeeplyImmutablePerson(String name, List address) { this.name = name; // Defensive copy + unmodifiable wrapper = true protection this.address = Collections.unmodifiableList(new ArrayList<>(address)); } public String getName() { return name; } public List getAddress() { return address; // Safe: already unmodifiable } public DeeplyImmutablePerson withAddress(List newAddress) { return new DeeplyImmutablePerson(this.name, newAddress); } } // True immutability in action List addressList = new ArrayList<>(); addressList.add("123 Main St"); addressList.add("Apt 4"); DeeplyImmutablePerson person = new DeeplyImmutablePerson("Alice", addressList); System.out.println("Original: " + person.getAddress()); // [123 Main St, Apt 4] // Original list mutation has no effect addressList.add("New York"); System.out.println("After external mutation: " + person.getAddress()); // [123 Main St, Apt 4] — Protected by defensive copy! // Attempt to mutate returned list throws exception // person.getAddress().clear(); // UnsupportedOperationException!7e:Tbcf,# SHALLOW IMMUTABILITY — The dangerous illusion class ShallowlyImmutablePerson: """ BROKEN: This class LOOKS immutable but isn't! The 'address' field references a mutable object. """ def __init__(self, name: str, address: list): self._name = name self._address = address # Danger: stores reference, not copy! @property def name(self) -> str: return self._name @property def address(self) -> list: return self._address # Danger: exposes mutable reference! # The illusion of immutability... address_list = ["123 Main St", "Apt 4"] person = ShallowlyImmutablePerson("Alice", address_list) print(f"Original: {person.address}") # ['123 Main St', 'Apt 4'] # External mutation through original reference — BREAKS "immutability" address_list.append("New York") print(f"After external mutation: {person.address}") # ['123 Main St', 'Apt 4', 'New York'] # Mutation through returned reference — ALSO breaks "immutability" person.address.clear() print(f"After direct mutation: {person.address}") # [] — Completely emptied! # The "immutable" object's state has been changed TWICE! # ───────────────────────────────────────────────────── # DEEP IMMUTABILITY — True protection from typing import Tuple class DeeplyImmutablePerson: """ CORRECT: True immutability with defensive copying and immutable internal structures. """ def __init__(self, name: str, address: tuple): self._name = name # Store as tuple (immutable) — no external mutation possible self._address = tuple(address) if not isinstance(address, tuple) else address @property def name(self) -> str: return self._name @property def address(self) -> Tuple[str, ...]: return self._address # Tuples are immutable — safe to share def with_address(self, new_address: tuple) -> 'DeeplyImmutablePerson': """Functional update: returns new person with new address""" return DeeplyImmutablePerson(self._name, new_address) # True immutability in action address_tuple = ("123 Main St", "Apt 4") person = DeeplyImmutablePerson("Alice", address_tuple) print(f"Original: {person.address}") # ('123 Main St', 'Apt 4') # Can't mutate tuple — this would raise an error: # person.address.append("New York") # AttributeError: 'tuple' has no attribute 'append' # Original reference mutation has no effect # (tuple is already copied/converted during construction) address_tuple = ("Different",) # Rebinding doesn't affect person print(f"After rebinding: {person.address}") # ('123 Main St', 'Apt 4') — Unchanged! # To change address, must create new person person2 = person.with_address(("456 Oak Ave",)) print(f"Person 1: {person.address}") # ('123 Main St', 'Apt 4') — Original intact print(f"Person 2: {person2.address}") # ('456 Oak Ave',) — New person7f:Ta76,// SHALLOW IMMUTABILITY — The dangerous illusion class ShallowlyImmutablePerson { /** * BROKEN: This class LOOKS immutable but isn't! * The 'address' field references a mutable array. */ private readonly _name: string; private readonly _address: string[]; // readonly ≠ immutable contents! constructor(name: string, address: string[]) { this._name = name; this._address = address; // Danger: stores reference, not copy! } get name(): string { return this._name; } get address(): string[] { return this._address; } // Danger! } // The illusion of immutability... const addressList = ["123 Main St", "Apt 4"]; const person = new ShallowlyImmutablePerson("Alice", addressList); console.log("Original:", person.address); // ['123 Main St', 'Apt 4'] // External mutation through original reference — BREAKS "immutability" addressList.push("New York"); console.log("After external mutation:", person.address); // ['123 Main St', 'Apt 4', 'New York'] // Mutation through returned reference — ALSO breaks "immutability" person.address.length = 0; console.log("After direct mutation:", person.address); // [] // ───────────────────────────────────────────────────── // DEEP IMMUTABILITY — True protection class DeeplyImmutablePerson { /** * CORRECT: True immutability with defensive copying * and frozen arrays. */ private readonly _name: string; private readonly _address: readonly string[]; constructor(name: string, address: readonly string[]) { this._name = name; // Defensive copy + freeze = true protection this._address = Object.freeze([...address]); } get name(): string { return this._name; } get address(): readonly string[] { return this._address; // Safe: frozen array } withAddress(newAddress: readonly string[]): DeeplyImmutablePerson { return new DeeplyImmutablePerson(this._name, newAddress); } } // True immutability in action const addressArray = ["123 Main St", "Apt 4"]; const personDeep = new DeeplyImmutablePerson("Alice", addressArray); console.log("Original:", personDeep.address); // ['123 Main St', 'Apt 4'] // Original array mutation has no effect addressArray.push("New York"); console.log("After external mutation:", personDeep.address); // ['123 Main St', 'Apt 4'] — Protected by defensive copy! // Attempt to mutate returned array throws in strict mode / is ignored // (personDeep.address as string[]).push("Fail"); // Throws or ignored80:T4e2,// String immutability in Java String original = "Hello"; String modified = original + " World"; // Key insight: 'original' is UNCHANGED System.out.println("original: '" + original + "'"); // 'Hello' System.out.println("modified: '" + modified + "'"); // 'Hello World' // They are different objects in memory System.out.println("Same object? " + (original == modified)); // false // You CANNOT mutate a String (no setter methods exist) // String is final — cannot even extend it to add mutators // Even methods that "change" the string return new strings String greeting = " hello world "; String trimmed = greeting.trim(); String upper = greeting.toUpperCase(); System.out.println("original: '" + greeting + "'"); // ' hello world ' System.out.println("trimmed: '" + trimmed + "'"); // 'hello world' System.out.println("upper: '" + upper + "'"); // ' HELLO WORLD ' // The StringBuilder alternative — when you NEED mutability StringBuilder builder = new StringBuilder("Hello"); builder.append(" World"); // Mutates in place String result = builder.toString(); // Convert back to immutable // Use StringBuilder for efficient string concatenation in loops // But the final result should typically be an immutable String81:T4b8,// String immutability in JavaScript const original = "Hello"; const modified = original + " World"; // Key insight: 'original' is UNCHANGED console.log(`original: '${original}'`); // 'Hello' console.log(`modified: '${modified}'`); // 'Hello World' // Strings are primitives — compared by value, but immutable console.log(`Same value? ${original === "Hello"}`); // true // You CANNOT mutate a string character // This silently fails (or throws in strict mode): // original[0] = "J"; // Has no effect console.log(`After attempted mutation: '${original}'`); // Still 'Hello' // Even methods that "change" the string return new strings const greeting = " hello world "; const trimmed = greeting.trim(); const upper = greeting.toUpperCase(); console.log(`original: '${greeting}'`); // ' hello world ' console.log(`trimmed: '${trimmed}'`); // 'hello world' console.log(`upper: '${upper}'`); // ' HELLO WORLD ' // The original 'greeting' string is untouched by any operation // Key insight for JS developers: // Primitive types (string, number, boolean) are ALWAYS immutable // Objects {} and arrays [] are MUTABLE by default // Use Object.freeze() or libraries for immutable objects82:Taee,import java.math.BigDecimal; import java.util.Objects; // VALUE OBJECT: Money // - No identity (any $100 is as good as another) // - Defined entirely by its attributes // - MUST be IMMUTABLE public final class Money { private final BigDecimal amount; private final String currency; public Money(BigDecimal amount, String currency) { this.amount = amount; this.currency = currency; } public BigDecimal getAmount() { return amount; } public String getCurrency() { return currency; } public Money add(Money other) { if (!this.currency.equals(other.currency)) { throw new IllegalArgumentException( "Cannot add " + this.currency + " to " + other.currency ); } return new Money(this.amount.add(other.amount), this.currency); } public Money multiply(BigDecimal factor) { return new Money(this.amount.multiply(factor), this.currency); } // Critical: Value equality based on attributes @Override public boolean equals(Object o) { if (this == o) return true; if (o == null || getClass() != o.getClass()) return false; Money money = (Money) o; return Objects.equals(amount, money.amount) && Objects.equals(currency, money.currency); } @Override public int hashCode() { return Objects.hash(amount, currency); } @Override public String toString() { return currency + " " + amount; } } // Usage — Value semantics Money price1 = new Money(new BigDecimal("100.00"), "USD"); Money price2 = new Money(new BigDecimal("100.00"), "USD"); // Value equality: same attributes = equal System.out.println("price1.equals(price2): " + price1.equals(price2)); // true // Immutable operations return new objects Money total = price1.add(new Money(new BigDecimal("50.00"), "USD")); System.out.println("price1: " + price1); // USD 100.00 (unchanged) System.out.println("total: " + total); // USD 150.00 (new object) // ───────────────────────────────────────────────────── // Java 16+ Record syntax for concise Value Objects: public record EmailAddress(String value) { public EmailAddress { // Compact constructor for validation if (!value.contains("@") || !value.contains(".")) { throw new IllegalArgumentException("Invalid email: " + value); } } public String domain() { return value.split("@")[1]; } } // Records are automatically: // - Immutable (final fields) // - Have equals/hashCode based on all fields // - Have toString implementation // - Have accessor methods for all fields83:Ta82,from dataclasses import dataclass from decimal import Decimal from typing import Self # VALUE OBJECT: Money # - No identity (any $100 is as good as another) # - Defined entirely by its attributes # - Should be IMMUTABLE @dataclass(frozen=True) # frozen=True makes it immutable class Money: amount: Decimal currency: str def add(self, other: 'Money') -> 'Money': if self.currency != other.currency: raise ValueError(f"Cannot add {self.currency} to {other.currency}") return Money(self.amount + other.amount, self.currency) def multiply(self, factor: Decimal) -> 'Money': return Money(self.amount * factor, self.currency) def __str__(self) -> str: return f"{self.currency} {self.amount:.2f}" # Usage — Value semantics price1 = Money(Decimal("100.00"), "USD") price2 = Money(Decimal("100.00"), "USD") # Value equality: same attributes = equal print(f"price1 == price2: {price1 == price2}") # True # Immutable operations return new objects total = price1.add(Money(Decimal("50.00"), "USD")) print(f"price1: {price1}") # USD 100.00 (unchanged) print(f"total: {total}") # USD 150.00 (new object) # ───────────────────────────────────────────────────── # Other common Value Objects: @dataclass(frozen=True) class DateRange: """Immutable representation of a date range""" start: str # ISO date string for simplicity end: str def contains(self, date: str) -> bool: return self.start <= date <= self.end def extend_by_days(self, days: int) -> 'DateRange': # Returns NEW DateRange, original unchanged from datetime import datetime, timedelta end_date = datetime.fromisoformat(self.end) new_end = (end_date + timedelta(days=days)).isoformat()[:10] return DateRange(self.start, new_end) @dataclass(frozen=True) class EmailAddress: """Immutable, validated email address""" value: str def __post_init__(self): if "@" not in self.value or "." not in self.value: raise ValueError(f"Invalid email: {self.value}") @property def domain(self) -> str: return self.value.split("@")[1] @dataclass(frozen=True) class Coordinate: """Immutable geographic coordinate""" latitude: float longitude: float def distance_to(self, other: 'Coordinate') -> float: # Simplified distance calculation import math return math.sqrt( (self.latitude - other.latitude) ** 2 + (self.longitude - other.longitude) ** 2 )84:Tb53,// VALUE OBJECT: Money // - No identity (any $100 is as good as another) // - Defined entirely by its attributes // - Should be IMMUTABLE class Money { private readonly _amount: number; private readonly _currency: string; constructor(amount: number, currency: string) { this._amount = amount; this._currency = currency; Object.freeze(this); // Enforce immutability } get amount(): number { return this._amount; } get currency(): string { return this._currency; } add(other: Money): Money { if (this._currency !== other.currency) { throw new Error( `Cannot add ${this._currency} to ${other.currency}` ); } return new Money(this._amount + other.amount, this._currency); } multiply(factor: number): Money { return new Money(this._amount * factor, this._currency); } // Value equality based on attributes equals(other: Money): boolean { return this._amount === other.amount && this._currency === other.currency; } toString(): string { return `${this._currency} ${this._amount.toFixed(2)}`; } } // Usage — Value semantics const price1 = new Money(100.00, "USD"); const price2 = new Money(100.00, "USD"); // Value equality: same attributes = equal console.log(`price1.equals(price2): ${price1.equals(price2)}`); // true // Immutable operations return new objects const total = price1.add(new Money(50.00, "USD")); console.log(`price1: ${price1}`); // USD 100.00 (unchanged) console.log(`total: ${total}`); // USD 150.00 (new object) // ───────────────────────────────────────────────────── // Other common Value Objects: class EmailAddress { private readonly _value: string; constructor(value: string) { if (!value.includes("@") || !value.includes(".")) { throw new Error(`Invalid email: ${value}`); } this._value = value; Object.freeze(this); } get value(): string { return this._value; } get domain(): string { return this._value.split("@")[1]; } equals(other: EmailAddress): boolean { return this._value === other.value; } } class Coordinate { constructor( public readonly latitude: number, public readonly longitude: number ) { Object.freeze(this); } distanceTo(other: Coordinate): number { return Math.sqrt( Math.pow(this.latitude - other.latitude, 2) + Math.pow(this.longitude - other.longitude, 2) ); } equals(other: Coordinate): boolean { return this.latitude === other.latitude && this.longitude === other.longitude; } }85:T602,# THE MUTABLE STATE NIGHTMARE # This is a simplified but realistic debugging scenario class MutableOrder: def __init__(self, items: list, total: float): self.items = items self.total = total self.status = "pending" def apply_discount(order: MutableOrder, discount: float): """Mutates order in place""" order.total = order.total * (1 - discount) def add_item(order: MutableOrder, item: str, price: float): """Mutates order in place""" order.items.append(item) order.total += price def process_order(order: MutableOrder): """Complex processing that may mutate order""" if order.total > 100: apply_discount(order, 0.1) # 10% discount order.status = "processed" # Debugging session — The nightmare begins order = MutableOrder(["Widget"], 50.0) print(f"A: {order.total}") # 50.0 # Some code path calls this... add_item(order, "Gadget", 75.0) print(f"B: {order.total}") # 125.0 # Then this gets called... process_order(order) print(f"C: {order.total}") # 112.5 (10% discount applied!) # Bug report: "Customer was charged 112.5 but expected 125.0" # Questions you must now answer: # 1. When exactly was the discount applied? # 2. What was the order state when the discount decision was made? # 3. Which code path led to this? (there could be dozens) # 4. Is there a race condition if this is multithreaded? # The same 'order' object had THREE different total values # at different points in time. Debugging requires reconstructing # the entire execution history.86:T838,# THE IMMUTABLE CLARITY # Same scenario, but with immutable design from dataclasses import dataclass from typing import Tuple @dataclass(frozen=True) class ImmutableOrder: items: Tuple[str, ...] # Immutable tuple total: float status: str = "pending" def with_discount(self, discount: float) -> 'ImmutableOrder': return ImmutableOrder( items=self.items, total=self.total * (1 - discount), status=self.status ) def with_item(self, item: str, price: float) -> 'ImmutableOrder': return ImmutableOrder( items=self.items + (item,), total=self.total + price, status=self.status ) def processed(self) -> 'ImmutableOrder': return ImmutableOrder( items=self.items, total=self.total, status="processed" ) def apply_discount_if_eligible(order: ImmutableOrder) -> ImmutableOrder: """Returns new order with discount if eligible""" if order.total > 100: return order.with_discount(0.1) return order # Clear execution with full history preserved order_v1 = ImmutableOrder(items=("Widget",), total=50.0) print(f"V1: {order_v1.total}") # 50.0 order_v2 = order_v1.with_item("Gadget", 75.0) print(f"V2: {order_v2.total}") # 125.0 order_v3 = apply_discount_if_eligible(order_v2) print(f"V3: {order_v3.total}") # 112.5 order_v4 = order_v3.processed() print(f"V4 status: {order_v4.status}") # "processed" # Debugging is TRIVIAL: # - order_v1, v2, v3, v4 are ALL still available # - Each represents the exact state at that point # - You can compare any two versions directly # - No need to reconstruct execution history print(f" Full audit trail:") print(f" v1 → v2: added Gadget (+75.0)") print(f" v2 → v3: discount applied (-12.5)") print(f" v3 → v4: status changed to processed") # You can even keep the entire history: history = [order_v1, order_v2, order_v3, order_v4] for i, version in enumerate(history): print(f" Version {i+1}: total={version.total}, status={version.status}")72:{"json":{"id":"seed_655b2ba911a4f15e15b01d216bfa364e","slug":"immutable-objects","category":"System Design LLD","topic":"Immutable Objects","title":"Immutable Objects — Unchanging by Design","description":"Master the art of designing immutable objects—one of the most powerful techniques in software engineering. Learn how immutability eliminates entire categories of bugs, enables thread-safe code, and simplifies reasoning about system state.","difficulty":"INTERMEDIATE","estimatedMinutes":60,"pages":[{"id":"seed_bd4ce78e38e24222020cbf106efb0670","title":"What Is Immutability","order":0,"content":[{"id":"opening-hook","title":"The Unchanging Promise","content":[{"data":{"content":"Imagine you hand someone a document. With a mutable document, they could alter it—crossing out words, adding new paragraphs, changing numbers. Every time you reference that document afterward, you can never be certain it still says what you originally wrote. Now imagine handing them a *photocopy*—sealed, unchangeable, permanent. No matter what they do with their copy, your original remains pristine. **This is the essence of immutability.**\n\nIn object-oriented programming, an **immutable object** is one whose state cannot be modified after creation. Once an immutable object is constructed, its internal data remains fixed for its entire lifetime. This seemingly simple constraint has profound implications for how we design, debug, and reason about software systems."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand the precise definition of immutability, distinguish between true immutability and shallow immutability, recognize immutable objects in familiar code, and appreciate why immutability has become a cornerstone principle in modern software architecture.","variant":"info"},"type":"callout"}]},{"id":"defining-immutability","title":"Defining Immutability","content":[{"data":{"content":"At its core, immutability is a guarantee: **once an object is created, its observable state never changes**. This definition, while simple, requires careful unpacking to understand fully.\n\n**Observable state** refers to the values that can be accessed through the object's public interface. An immutable object provides no methods, properties, or mechanisms that could alter what callers see when they query the object.\n\n**The formal definition:**\n\n> An object is **immutable** if, after construction, no operation—whether internal or external—can change the values returned by its methods or properties.\n\nThis is a strict contract. It's not enough for an object to *appear* unchanged most of the time. A truly immutable object provides a mathematical guarantee: given the same object reference, all queries will return identical results, forever."},"type":"text"},{"data":{"icon":"Lightbulb","title":"The Snapshot Mental Model","content":"Think of an immutable object as a **snapshot**—a frozen moment in time. Just as a photograph captures a scene exactly as it was, an immutable object captures data exactly as it was at construction. The photograph doesn't change if the actual scene changes later; similarly, the immutable object doesn't change even if the data it was based on changes elsewhere.","variant":"tip"},"type":"callout"},{"data":{"content":"**Mutable vs. Immutable — A Comparison:**\n\nLet's contrast these two approaches with a concrete example. Consider a simple `Point` class representing a coordinate in 2D space."},"type":"text"},{"data":{"code":{"java":"$7a","python":"$7b","typescript":"$7c"},"fileName":"point_comparison.py","languages":[{"label":"Python","value":"python"},{"label":"Java","value":"java"},{"label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"The key insight: with `ImmutablePoint`, the `move` method doesn't modify the existing point—it creates and returns a *new* point representing the moved position. The original point remains frozen at its initial coordinates forever. This pattern is sometimes called **functional update** or **copy-on-write semantics**."},"type":"text"}],"titleType":"number","titleNumber":1},{"id":"deep-vs-shallow","title":"Deep vs. Shallow Immutability","content":[{"data":{"content":"One of the most critical—and commonly misunderstood—aspects of immutability is the distinction between **shallow immutability** and **deep immutability**. Getting this wrong can introduce subtle, devastating bugs.\n\n**Shallow Immutability:**\n\nAn object is shallowly immutable if its **direct fields** cannot be changed, but those fields may reference mutable objects that *can* be changed. The outer object appears immutable, but mutation can leak through its references."},"type":"text"},{"data":{"icon":"AlertCircle","title":"The Hidden Danger","content":"Shallow immutability is a common trap. Developers believe they've created an immutable object, but external code can still mutate the internal state through shared references. This breaks the immutability contract and eliminates its benefits.","variant":"warning"},"type":"callout"},{"data":{"code":{"java":"$7d","python":"$7e","typescript":"$7f"},"fileName":"shallow_immutability_trap.py","languages":[{"label":"Python","value":"python"},{"label":"Java","value":"java"},{"label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"**The Immutability Contract:**\n\nFor true (deep) immutability, every component of the object's state must also be immutable, recursively. This leads to a fundamental principle:\n\n> **Deep Immutability Principle:** An object is deeply immutable if and only if:\n> 1. All its fields are immutable (primitive values or references to immutable objects)\n> 2. It never exposes direct references to internal mutable state\n> 3. All collections it contains are immutable or defensively copied"},"type":"text"},{"data":{"rows":[["Direct fields","Cannot be reassigned","Cannot be reassigned"],["Referenced objects","Can be mutated externally","Also immutable (recursively)"],["Thread safety","Not guaranteed","Fully guaranteed"],["Equality stability","Can change over time","Permanent and reliable"],["Defensive copying","Not done (or incomplete)","On both input and output"],["Bug surface area","Large (hidden mutation)","Minimal (true snapshot)"]],"caption":"Shallow vs. Deep Immutability Comparison","headers":["Aspect","Shallow Immutability","Deep Immutability"]},"type":"table"}],"titleType":"number","titleNumber":2},{"id":"recognizing-immutability","title":"Recognizing Immutability in Practice","content":[{"data":{"content":"Immutability isn't an exotic concept—it's all around us in everyday programming. Many of the most commonly used types in modern languages are immutable by design. Understanding these examples builds intuition for when and how to apply immutability in your own designs.\n\n**Built-in Immutable Types:**"},"type":"text"},{"data":{"rows":[["Java","`String`, `Integer`, `Long`, `Double`, `BigDecimal`, `LocalDate`, `LocalDateTime`","Java 8+ date/time API is fully immutable"],["Python","`str`, `int`, `float`, `tuple`, `frozenset`, `bytes`","Contrast with mutable `list`, `dict`, `set`"],["JavaScript/TS","`string`, `number`, `boolean`, `Symbol`, `BigInt`","All primitives; objects require `Object.freeze()`"],["C#","`string`, `DateTime`, `TimeSpan`, value types (structs)","Records with `init` properties in C# 9+"],["Scala","`String`, `Int`, case classes (default)","Immutability is the default paradigm"],["Kotlin","`String`, `Int`, data classes with `val`","`val` = immutable, `var` = mutable"]],"caption":"Common Immutable Types Across Languages","headers":["Language","Immutable Types","Notes"]},"type":"table"},{"data":{"content":"**The String Example — Immutability in Action:**\n\nStrings are arguably the most familiar immutable type. When you \"modify\" a string, you're actually creating a new string:"},"type":"text"},{"data":{"code":{"java":"$80","python":"# String immutability in Python\noriginal = \"Hello\"\nmodified = original + \" World\"\n\n# Key insight: 'original' is UNCHANGED\nprint(f\"original: '{original}'\") # 'Hello'\nprint(f\"modified: '{modified}'\") # 'Hello World'\n\n# They are different objects in memory\nprint(f\"Same object? {original is modified}\") # False\nprint(f\"original id: {id(original)}\")\nprint(f\"modified id: {id(modified)}\") # Different!\n\n# You CANNOT mutate a string character\n# original[0] = \"J\" # TypeError: 'str' object does not support item assignment\n\n# Even methods that \"change\" the string return new strings\ngreeting = \" hello world \"\ntrimmed = greeting.strip()\nupper = greeting.upper()\n\nprint(f\"original: '{greeting}'\") # ' hello world '\nprint(f\"trimmed: '{trimmed}'\") # 'hello world'\nprint(f\"upper: '{upper}'\") # ' HELLO WORLD '\n\n# The original 'greeting' string is untouched by any operation","javascript":"$81"},"fileName":"string_immutability.py","languages":[{"label":"Python","value":"python"},{"label":"Java","value":"java"},{"label":"JavaScript","value":"javascript"}]},"type":"code"},{"data":{"icon":"Info","title":"Why Strings Are Immutable","content":"Strings were made immutable in most languages for critical reasons: **security** (strings often hold passwords, URLs, file paths that shouldn't change unexpectedly), **thread safety** (strings can be safely shared across threads), **string interning** (identical strings can share memory), and **hash stability** (strings are commonly used as map keys, which requires stable hash codes).","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"value-object-pattern","title":"The Value Object Pattern","content":[{"data":{"content":"Immutability is intimately connected to a fundamental design pattern called **Value Objects**. Understanding this connection illuminates when immutability is most appropriate.\n\n**What is a Value Object?**\n\nA Value Object is an object that represents a descriptive aspect of the domain with no conceptual identity. Two Value Objects are considered equal if all their attributes are equal—it doesn't matter *which* instance you have, only *what values* it holds.\n\n**Contrast with Entity Objects:**\n\n- **Entity:** Has identity. Two `User` objects with the same name are different if they have different IDs. Changing a user's name doesn't create a new user—it updates the existing one.\n\n- **Value Object:** Has no identity. Two `Money(100, USD)` objects are interchangeable. There's no concept of \"the same hundred dollars\"—any hundred dollars is as good as another."},"type":"text"},{"data":{"code":{"java":"$82","python":"$83","typescript":"$84"},"fileName":"value_objects.py","languages":[{"label":"Python","value":"python"},{"label":"Java","value":"java"},{"label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"items":["**Money** — Amount and currency; arithmetic operations return new Money","**Date/Time ranges** — Start and end; extensions return new ranges","**Addresses** — Street, city, postal code; validation at construction","**Email addresses** — Validated string wrapper with domain operations","**Measurements** — Value and unit (10 kg, 5 meters); unit-aware math","**Colors** — RGB/HSL values; color operations return new colors","**Geographic coordinates** — Lat/long; distance calculations","**Version numbers** — Major.minor.patch; comparison operations"],"title":{"icon":"CheckCircle","text":"Common Value Objects in Domain Modeling","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"icon":"Lightbulb","title":"The Value Object Rule","content":"**Value Objects should ALWAYS be immutable.** Since they have no identity, \"modifying\" a Value Object conceptually creates a different value. Making them mutable is not just unnecessary—it's actively harmful, leading to bugs where shared values unexpectedly change.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":4},{"id":"temporal-reasoning","title":"Immutability and Temporal Reasoning","content":[{"data":{"content":"One of the most powerful benefits of immutability is how it simplifies **temporal reasoning**—understanding how your program's state evolves over time.\n\n**The Mutable State Problem:**\n\nWith mutable objects, understanding a program requires tracking not just *what* an object is, but *when* you're looking at it. The same variable can have different values at different points in execution, and determining when a mutation occurred becomes a debugging nightmare."},"type":"text"},{"data":{"code":{"python":"$85"},"fileName":"temporal_nightmare.py","languages":[{"label":"Python","value":"python"}]},"type":"code"},{"data":{"content":"**The Immutable Alternative:**\n\nWith immutable objects, temporal reasoning becomes trivial. Each \"version\" of the data is a separate object, and you can inspect any version at any time without worrying about it changing."},"type":"text"},{"data":{"code":{"python":"$86"},"fileName":"temporal_clarity.py","languages":[{"label":"Python","value":"python"}]},"type":"code"},{"data":{"icon":"CheckCircle","title":"The Immutability Advantage","content":"With immutable objects: **Variables don't change; they get replaced.** This means looking at any variable at any point gives you the complete, permanent truth about that value. There's no hidden history to reconstruct, no race conditions to worry about, and debugging becomes a matter of comparing snapshots rather than reconstructing timelines.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":5},{"id":"summary","title":"Summary: What Is Immutability","content":[{"data":{"content":"We've established the foundational understanding of immutability. Let's consolidate the key concepts:"},"type":"text"},{"data":{"type":"ordered","items":["**Immutability means state cannot change** — Once created, an immutable object's observable state remains fixed forever.","**Deep vs. shallow matters critically** — True immutability requires that all nested references are also immutable; shallow immutability is a dangerous illusion.","**Familiar types are often immutable** — Strings, numbers, and date/time types in most languages are immutable by design, demonstrating the pattern's practicality.","**Value Objects should always be immutable** — Objects defined by their attributes (not identity) naturally map to immutable designs.","**Immutability simplifies temporal reasoning** — Each variable represents a permanent snapshot, eliminating the mental overhead of tracking state changes over time.","**Modification creates new objects** — The functional update pattern (returning new instances) replaces in-place mutation while preserving the original."],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next:**\n\nNow that you understand what immutability *is*, the next page explores *why* it matters so deeply. We'll examine the concrete benefits of immutability—thread safety, simplicity, predictability—and see how these advantages compound in real systems to dramatically reduce bugs and complexity."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand the definition and mechanics of immutability. This foundation prepares you to appreciate the profound benefits that immutability provides—benefits that have made it a cornerstone of modern software architecture.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":6}],"isLocked":false},{"id":"seed_60e81025665a0d9c9757fb517648d3bc","title":"Benefits: Thread Safety, Simplicity, and Beyond","order":1,"content":null,"isLocked":true},{"id":"seed_def54c8484877c9c73eea7d2be1523f5","title":"Designing Immutable Classes","order":2,"content":null,"isLocked":true},{"id":"seed_2fed94761ea74b0ec63608b25fe66028","title":"Immutability Trade-offs","order":3,"content":null,"isLocked":true}]}}