Omdat TypeScript structureel getypeerd is, zijn een UserId en een OrderId die beide string zijn uitwisselbaar — de compiler kan je niet tegenhouden om ze door elkaar te halen. Branded types simuleren nominale typing door een unieke, phantom "brand" toe te voegen zodat anders identieke types onderscheidend worden.
// 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
De __brand eigenschap bestaat nooit in runtime (de waarde is gewoon een string), maar in het type system maakt het UserId en OrderId incompatibel — waarmee een hele klasse van mix-up bugs wordt voorkomen.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Valideer eenmalig op de grens; de rest van de code vertrouwt het branded type.
IDs (UserId vs OrderId), gevalideerde/gezuiverde strings (Email, SafeHtml), eenheden (Meters vs Feet), PositiveNumber — overal waar twee waarden hetzelfde primitieve type delen maar niet door elkaar mogen worden gehaald.
Branded types voegen nominale veiligheid toe waar structurele typing te permissief is.
Ze onderscheppen argument-order mix-ups en "ongevalideerde vs gevalideerde" verwarring op compile-time, zonder runtime kosten — een krachtig patroon voor domeinmodellering in grote, nauwkeurigheid-kritische codebases.