Because TypeScript is structurally typed, a UserId and an OrderId that are both string are interchangeable — the compiler can't stop you from mixing them up. Branded types simulate nominal typing by attaching a unique, phantom "brand" so otherwise-identical types become distinct.
// the brand is a property that exists only in the type system, never at runtime
type Brand<T, B> = T & { readonly __brand: B };
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
function getUser(id: UserId) { return id; }
const uid = "u1" as UserId;
const oid = "o1" as OrderId;
getUser(uid); // ✅
getUser(oid); // ❌ Error: OrderId is not assignable to UserId
getUser("u1"); // ❌ Error: plain string is not a UserId
The __brand property never exists at runtime (the value is just a string), but in the type system it makes UserId and OrderId incompatible — preventing a whole class of mix-up bugs.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Validate once at the boundary; the rest of the code trusts the branded type.
IDs (UserId vs OrderId), validated/sanitized strings (Email, SafeHtml), units (Meters vs Feet), PositiveNumber — anywhere two values share a primitive type but must not be confused.
Branded types add nominal safety where structural typing is too permissive.
They catch argument-order mix-ups and "unvalidated vs validated" confusion at compile time, with zero runtime cost — a powerful pattern for domain modeling in large, correctness-critical codebases.