Lesson 1 of the DDD course · Value objects, smart constructors, and parse-don't-validate · ~25 minutes
Your working assumption today: Meridian, your storefront. A customer places an order. You need their email, an order id, a total, and a status. Watch how much of DDD's worldview is already hiding in that sentence.
Here's how almost every TypeScript codebase starts:
type Order = {
customerId: string;
email: string;
total: number;
status: string; // "draft" | "placed" | "shipped" …in someone's head
};
Nothing is wrong at a glance. The rot shows up over the following weeks:
customerId where an email goes. Both are strings. The compiler shrugs.total: -3 ships to production because a refund path forgot a guard.status: "shipped " (trailing space, from a CSV import) matches no branch anywhere.This smell has a name: primitive obsession — modeling business concepts with raw primitives so their rules live nowhere in particular.[Wlaschin]
DDD's first move isn't technical. It's linguistic. Ubiquitous language means the code uses the exact words the business uses — same terms in conversation, in tickets, in type names.[Evans via Fowler] Your team doesn't say “non-empty string with an at-sign”; it says email. It doesn't say “number greater than zero”; it says total.
| Business word | Rules the business assumes | What the code had |
|---|---|---|
| an email | looks like an address | string |
| a customer id | a specific id format | string |
| a total | money, ≥ 0 | number |
| an order status | one of a fixed set of stages | string |
Each row is a concept the business considers closed — there's a fixed set of valid values — but the code treats as infinitely open. That gap is where the bugs live.
A value object is a domain concept defined entirely by its attribute values — no identity, immutable, and two instances with the same value are interchangeable.[Evans; Fowler] An email is its characters. A money amount is its number and currency. Compare that with a customer, which has identity and changes over time — that's next lesson's “entity”, don't conflate them yet.
Two small functions per concept, in this exact order.
type Email = string & { readonly __brand: "Email" };
type CustomerId = string & { readonly __brand: "CustomerId" };
The __brand field never exists at runtime — it's a promise to the compiler. Now
Email and CustomerId are both strings underneath, but
not interchangeable: pass one where the other goes and tsc fails the
build. This is the TypeScript translation of Wlaschin's “single-case union” wrapper[Wlaschin] — no classes needed.
type Result<T, E> =
| { readonly ok: true; readonly value: T }
| { readonly ok: false; readonly error: E };
function parseEmail(raw: string): Result<Email, string> {
const email = raw.trim();
const parts = email.split("@");
if (parts.length !== 2 || parts[0] === "" || parts[1] === "") {
return { ok: false, error: "invalid email" };
}
return { ok: true, value: email as Email };
}
Notes on the pattern:
parseEmail is the smart
constructor — the only door into the type. The as Email cast is safe
here and only here, immediately after the checks.Result union makes failure part of the signature. A caller can't forget the
failure branch: narrowing on ok forces it.Email
ever re-checks it — it can't be anything else.
function ship(order: Order) {
if (!isValidEmail(order.email)) throw …;
if (order.total <= 0) throw …;
// …still can't trust status
}
type Order = {
customerId: CustomerId;
email: Email;
total: Cents;
status: OrderStatus;
};
// ship(order) needs no guards:
// an Order cannot exist unparsed.
Three compounding wins, all from one move:
parseEmail tells you input is
untrusted; a parameter of type Email tells you it's already good.type Total = number (a bare alias) does
nothing — aliases are transparent; brands are not. (3) Keep parsing at boundaries; if
you're re-parsing the same value deep in the core, something upstream returned a primitive.
Write parseEmail from scratch. TypeScript types are checked by
tsc, which isn't running here — so this playground verifies your runtime logic
and result shape. Write the types in your head; make the tests green.
Answer from memory — that effort is the point. Don't scroll up first.
Value objects have no identity. But a customer stays the same customer when they change
their email, and an order stays the same order as its status moves. Next lesson:
entities — modeling identity without classes, where Meridian's
OrderId stops being a string.
__brand cast, why Result beats exceptions, when
not to brand — just ask in the chat. That's what I'm for. No question is too basic; you
paid for this course with your attention.