Lesson 4 of the DDD course · Lifecycle as a discriminated union, exhaustiveness, typed transitions · ~30 minutes
shipped that was never paid, because some
code path set fields directly. Today the lifecycle becomes the type system's job —
the compiler refuses to ship a draft, in every code path, forever.
This is the lesson where functional TypeScript stops imitating OOP DDD and starts beating it. What classes-with-inheritance do awkwardly, discriminated unions do natively.
status: stringHere's the model everyone writes first:
interface Order {
id: OrderId;
status: string; // "draft" | "placed" | "shipped" … in someone's head
paymentId?: PaymentId; // present when placed… usually
shipment?: Shipment; // present when shipped… we hope
}
Count what this type permits: status: "draft" with a shipment.
status: "shipped" with no paymentId. Every optional field doubles the
state space, and only a handful of combinations are legal. So every consumer writes defensive
checks — “is payment there? is it shipped? am I sure?” — forever, for states that should
not exist.
interface DraftOrder {
readonly kind: "draft"; // the discriminant
readonly id: OrderId;
readonly customerId: CustomerId;
readonly lines: readonly OrderLine[];
readonly total: Cents;
}
interface PlacedOrder {
readonly kind: "placed";
readonly id: OrderId;
readonly customerId: CustomerId;
readonly lines: readonly OrderLine[];
readonly total: Cents;
readonly paymentId: PaymentId; // only a placed order was paid
}
interface ShippedOrder {
readonly kind: "placed" | "shipped"; // hmm — see below
readonly shipment: Shipment; // only a shipped order has one
}
type Order = DraftOrder | PlacedOrder | ShippedOrder;
Each stage carries only the data valid at that stage. A DraftOrder has no
paymentId because drafts aren't paid. There is no such value as “a shipped order
without a shipment” — the type won't construct one. The impossible states aren't checked at
runtime; they're inexpressible.[Wlaschin]
function ship(o: PlacedOrder, carrier: Carrier): Result<ShippedOrder, ShipError>
ship(draftOrder, carrier); // ☠ compile error: DraftOrder is not PlacedOrder
The parameter type is the state machine. ship can't be called on a draft
— not “will throw if you do”, but the program doesn't compile. Two layers of
protection now cooperate:
Result errors, exhaustively handled.And narrowing reads like the business: switch (order.kind) — in the
"placed" branch, order.paymentId is simply there, no optional
gymnastics:
function trackingUrl(o: Order): string | null {
switch (o.kind) {
case "draft": return null;
case "placed": return null;
case "shipped": return o.shipment.trackingUrl;
}
}
Add a "refunded" stage next quarter. Watch what happens:
function assertNever(x: never): never {
throw new Error("unhandled stage: " + JSON.stringify(x));
}
function label(o: Order): string {
switch (o.kind) {
case "draft": return "Cart";
case "placed": return "Confirmed";
default: return assertNever(o); // ☠ won't compile until handled
}
}
assertNever turns the union into a work list: every place that must learn about
the new stage fails the build until updated. String statuses give you the opposite — a
switch with a silent default and a hope.
kind: "draft"),
or narrowing dies. (2) Don't share one mega-interface with optional fields “for convenience” —
that re-opens the illegal combinations. (3) Keep stage data minimal: if
Shipment data is huge, ship a ShipmentId and load it in the shell
(Lesson 8).
Placing an order has consequences — emails, warehouse feeds, analytics. Next lesson: domain events, the pattern that lets pure transitions announce facts without knowing who listens.
never trick or narrowing behavior surprises you, ask — I can walk through
exactly what the compiler proves, line by line. Understanding why it's safe is what
makes you able to design new unions on your own product.