Entities: Identity Without Classes

Lesson 2 of the DDD course · Identity, lifecycle, and mutable-looking state with immutable data · ~25 minutes

1 · Value objects 2 · Entities & identity 3 · Aggregates 4 · Lifecycle state machines 5 · Domain events 6 · Bounded contexts 7 · Context mapping 8 · Functional core 9 · Capstone
Why this matters for your mission Value objects can't change. But your startup's most important data does change — a customer updates their email, an order moves through stages. Today you learn to model things that persist through change without a single class or mutation, so state lives in plain data your functions transform.

Last lesson everything was frozen: an Email is its characters, forever. Today we loosen exactly one screw — identity — and keep everything else immutable.

1 · The question entities answer

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 objectEntity
Equal when…all attribute values matchidentity matches
Changes?never — replaced, not editedstate changes, identity doesn't
Meridian examplesEmail, Cents, Quantity, PromoCodeCustomer, Order, Subscription
The decision test Ask: “If every attribute changed, would the business still call it the same thing?” Yes → entity. No → value object. [email protected] → [email protected]: same customer (entity). Ten dollars → fifteen dollars: different money (value object).

2 · Identity is itself a 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.

3 · The entity, as plain data

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.

4 · Change without mutation

“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:

Gotchas (1) Equality is by id, never 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.

5 · Practice: change state, keep identity

Implement changeEmail. Your tests check the runtime logic and that the original customer object was never mutated.

6 · Retrieval check

7 · Where this goes next

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.

Your teacher is the agent Unclear on value object vs entity for a specific concept in your product? Ask me with the concrete case — that judgment call is the actual skill, and it's exactly what I'm here for.
Primary source for this lesson Read Evans' definition of entities via Fowler's DDD overview (~5 min), then the fuller treatment in *Domain Modeling Made Functional*, chapters 2–4 — Wlaschin builds entities and workflow state in exactly our style, just in F#.
← Lesson 1: Value Objects Glossary →