42. Branded/nominal types

TypeScript's structural typing means two differently-named types with the same shape are interchangeable — usually helpful, but risky for values like `UserId` and `OrderId` that are both just `string` underneath. Branding adds a fake, unused property to force distinctness.

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

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

function getUser(id: UserId) { /* ... */ }

const oid = "order-1" as OrderId;
getUser(oid); // error: OrderId is not assignable to UserId, despite both being strings

The `__brand` field never actually exists at runtime — it's a compile-time-only tag. This pattern is common for modelling distinct identifier types (wallet address vs. transaction hash vs. block hash) that would otherwise all collapse to plain `string` and be silently interchangeable.

Read in another language

How to study this topic

Scoring

Check your understanding

Badges