Immutability & Value Objects

What makes an object immutable

An object is immutable when there is no legal way to change its data after it's constructed. In practice that means three things working together:

• Set every field once, at construction. Mark fields final (Java), readonly (TypeScript), or const (C++) so the compiler refuses any later write.
• Expose no setters. Provide getters if you like, but nothing that writes. The only moment the data is set is in the constructor.
• Deep-copy on the way in and out. If the constructor receives a mutable thing (a list, an array, a date), store a copy, not the caller's object. If a getter returns a mutable thing, return a copy of that too.

The aliasing bug — one mutation, two surprises

Here's the trap immutability saves you from. When you assign one object to two variables, you don't get two objects — you get two references to the same object. Mutate it through one, and the other sees the change too, often somewhere far away in the code that never asked for it.

// MUTABLE Money — has a setter
const aliasA = new MutableMoney(100, "USD");
const aliasB = aliasA;          // NOT a copy — same object, two names

aliasA.setAmount(0);            // mutate through one reference...
console.log(aliasB.amount);     // 0  ← aliasB changed too! spooky action

// With an IMMUTABLE Money there is no setAmount at all,
// so this bug simply cannot be written.

This is aliasing. It's not a typo or a logic slip — the code reads perfectly. The damage is that aliasB was silently corrupted by something it had no relationship with. Defensive copying (storing and returning copies) is one fix; making the object immutable is the stronger one, because then there's nothing to mutate in the first place.

How an immutable object "changes"

If you can't edit the object, how do you get a different value? You build a new one. A method like plus(amount) doesn't touch this — it constructs and returns a fresh object with the new value, leaving the original exactly as it was:

class Money {
  constructor(readonly amount: number, readonly currency: string) {}

  plus(extra: number): Money {
    return new Money(this.amount + extra, this.currency); // NEW object
  }

  withAmount(amount: number): Money {
    return new Money(amount, this.currency);              // NEW object
  }
}

const a = new Money(100, "USD");
const b = a.plus(50);   // b is Money(150,"USD"); a is STILL Money(100,"USD")

Notice the shape: every "mutator" is really a factory that returns a new instance. The original is read-only and survives untouched, so any other reference pointing at it is never surprised.

Value objects: equality by value, no identity

A value object is a small immutable object whose identity is its value. Two Money(100, "USD") objects are completely interchangeable — it makes no sense to ask which $100 you have, only whether it's $100. So value objects compare by value: Money(100,"USD").equals(Money(100,"USD")) is true even though they're separate instances in memory.

Contrast that with an entity — a User, an Order, a BankAccount. Two users named "Alice" with the same balance are not the same user; each has its own identity (an id) that persists even as its data changes. Entities are compared by id; value objects are compared by their fields. Money, dates, coordinates, colors, and quantities are classic value objects.

Thread-safety, for free

Because an immutable object never changes, multiple threads can read it at the same time with zero locks, zero synchronization, and no chance of seeing a half-updated state. There's no write to race against. This is one of the biggest practical wins of immutability: shared, immutable data is automatically safe to pass anywhere, including across threads.

What each language gives you

• Java — final fields and record types (which are immutable and get value equality for free).
• Python — @dataclass(frozen=True) raises on any attribute write; tuple is the built-in immutable sequence.
• C++ — const members and methods marked const; "mutators" return a new value object.
• TypeScript — readonly fields (compile-time) plus Object.freeze() for a runtime, shallow freeze.

When to reach for an immutable value object

Use immutability for any small concept whose meaning is its value — money, dates, ranges, coordinates, colors, quantities, identifiers. Reach for it whenever an object will be shared across the codebase, used as a map or set key, passed between threads, or cached: in all of those cases the guarantee that it can't change quietly is worth far more than the cost of an occasional new allocation. Keep mutability for things that genuinely model an evolving lifecycle — an Order being filled, a Game in progress — and even then, build them out of immutable value objects.