Lesson 2 of the DDD course · Identity, lifecycle, and mutable-looking state with immutable data · ~25 minutes
Last lesson everything was frozen: an Email is its characters, forever.
Today we loosen exactly one screw — identity — and keep everything else immutable.
Meridian has a customer, cus_9f2, with email [email protected]. Today she
changes it to [email protected]. Ask the business: “Is she the same customer?”
Of course she is. Same person, new email. Her attributes changed; she didn't get replaced. That's the definition of an entity: a domain concept defined not by its attribute values but by an identity that persists through state changes.[Evans]
| Value object | Entity | |
|---|---|---|
| Equal when… | all attribute values match | identity matches |
| Changes? | never — replaced, not edited | state changes, identity doesn't |
| Meridian examples | Email, Cents, Quantity, PromoCode | Customer, Order, Subscription |
[email protected] → [email protected]: same
customer (entity). Ten dollars → fifteen dollars: different money (value object).
The identity of an entity is a small, rule-governed value — which means Lesson 1's machinery applies directly. Brand it, parse it once, and ids can never cross-wire:
type CustomerId = string & { readonly __brand: "CustomerId" };
type OrderId = string & { readonly __brand: "OrderId" };
function fulfill(orderId: OrderId, customerId: CustomerId) { … }
fulfill(customerId, orderId); // ☠ compile error — brands don't mix
Both are strings underneath; only one parses to the other's type. Every “which id went where”
bug dies at tsc.
interface Customer {
readonly id: CustomerId; // identity — stable through every change
readonly email: Email; // state — may change over time
}
const sameCustomer = (a: Customer, b: Customer): boolean =>
a.id === b.id;
Notice what's absent: no class, no constructor, no this, no framework. An entity is
a plain, frozen record whose identity field is the anchor. Notice also that the id field
is readonly — identity never changes; that's the whole point.
“But entities change!” Yes — their state does. In this course, change is a function that takes the old state and returns the new state, identity intact:
function changeEmail(c: Customer, raw: string): Result<Customer, string> {
const r = parseEmail(raw);
return r.ok ? { ok: true, value: { ...c, email: r.value } } : r;
}
// ana: { id: "cus_9f2", email: "[email protected]" }
// after: { id: "cus_9f2", email: "[email protected]" } ← same customer, new state
Three payoffs, straight from Lesson 1's philosophy:
changeEmail re-parses because the
raw string is outside input — the result is a proven entity.deepEqual — two different customers can
momentarily hold equal field values. (2) Don't generate identity inside domain functions — ids
are minted at the boundary (DB, id service) and parsed in. (3) A bare
type CustomerId = string alias protects nothing, as before.
Implement changeEmail. Your tests check the runtime logic and that the
original customer object was never mutated.
A customer is one thing with one identity. An order is a cluster — lines, totals, status — whose pieces must obey rules together (“total equals the sum of its lines”). Next lesson: aggregates, the consistency boundary that keeps those rules in exactly one place.