From Strings to Domain Types

Lesson 1 of the DDD course · Value objects, smart constructors, and parse-don't-validate · ~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 You're starting a product from zero. Every later DDD idea — aggregates, invariants, bounded contexts — is built out of one primitive move: replace a primitive with a domain type that can only exist when the business rule holds. Master this move today and the compiler starts defending your business rules from day one.

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.

1 · The smell: primitives everywhere

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:

This smell has a name: primitive obsession — modeling business concepts with raw primitives so their rules live nowhere in particular.[Wlaschin]

2 · Ubiquitous language: the business already named these things

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 wordRules the business assumesWhat the code had
an emaillooks like an addressstring
a customer ida specific id formatstring
a totalmoney, ≥ 0number
an order statusone of a fixed set of stagesstring

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.

3 · Value objects: concepts with rules, no identity

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.

The rule If the business would say two things are “the same thing” when their values match — email, money, quantity, postal code, promo code — it's a value object. Make it a type of its own.

4 · The functional move: brand, then parse

Two small functions per concept, in this exact order.

Step 1 — brand the primitive (zero runtime cost)

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.

Step 2 — one smart constructor that parses

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:

The principle — cite this “Parse, don't validate.” Validation checks data and returns a boolean, leaving raw data in circulation. Parsing converts raw data into a richer type and hands you the proof.[King] After parsing, no function that receives an Email ever re-checks it — it can't be anything else.

5 · The payoff

Before — trust nothing
function ship(order: Order) {
  if (!isValidEmail(order.email)) throw …;
  if (order.total <= 0) throw …;
  // …still can't trust status
}
After — the types did the checking
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:

Gotchas (1) Don't brand everything on day one — brand concepts with rules (email, money, quantity) or mix-up risk (id types). (2) 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.

6 · Practice: build the parser yourself

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.

7 · Retrieval check

Answer from memory — that effort is the point. Don't scroll up first.

8 · Where this goes next

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.

Your teacher is the agent Anything unclear — the __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.
Primary source for this lesson Read “Parse, don't validate” — Alexis King (free, ~10 min) — it's the sharpest short text on today's idea. When you want the full course in book form: *Domain Modeling Made Functional* — Scott Wlaschin (chapters 1–3 cover today + next lesson, in F# that reads like our TS).
Glossary — today's terms →