Branded Types & Nominal Typing

The plain-language idea

From the structural typing lesson: TypeScript considers two types compatible if they have the same shape, regardless of name. Usually that's exactly what you want — but sometimes it's actively wrong:

type UserId = string;
type PostId = string;

function getUser(id: UserId) { /* ... */ }
const postId: PostId = "post_123";
getUser(postId);   // ✅ compiles — but this is a real bug, wrong id entirely

UserId and PostId are both just string underneath — structurally identical, so TypeScript happily lets you pass one where the other is expected. Nothing about the shape distinguishes them, even though they mean completely different things.

Branding fakes a distinct identity

type UserId = string & { readonly __brand: "UserId" };
type PostId = string & { readonly __brand: "PostId" };

function makeUserId(id: string): UserId { return id as UserId; }

function getUser(id: UserId) { /* ... */ }
getUser(postId);              // ❌ now a real compile error
getUser(makeUserId("u_1"));   // ✅

The __brand field doesn't exist at runtime at all — it's a type-space-only marker (the type-vs-value-space idea) that makes UserId and PostId structurally incompatible even though both are still, underneath, plain strings. This opts a specific pair of types out of structural typing on purpose.

type UserId = string; type OrderId = string; — structurally identical, TypeScript can't tell them apart.

BackNext

What people usually miss

Watch out

• The brand field never exists at runtime. as UserId performs no actual transformation — a branded type is purely a compile-time fiction layered on top of a real, ordinary string.
• Only use branding where mixing up the values would be a real, meaningful bug — ids, currency amounts, validated/sanitized strings (a SafeHtml branded type, distinct from plain string) are the classic cases; branding everything adds friction with no payoff.
• A "smart constructor" function (makeUserId, or a parseEmail(s: string): Email | null that validates first) is the idiomatic way to produce a branded value — you can't just assert any string as branded and expect the validation to have actually happened.

Why this matters in interviews

"How would you prevent a UserId and a PostId — both just strings underneath — from being accidentally swapped?" is a great, concrete question, and branded types is the real, idiomatic TypeScript answer that most candidates haven't encountered unless they've hit this exact bug in production.