Weil TypeScript strukturell typisiert ist, sind UserId und OrderId, die beide string sind, austauschbar — der Compiler kann dich nicht daran hindern, sie zu vermischen. Branded Types simulieren Typisierung, indem sie eine eindeutige, phantom "Marke" anhängen, sodass andernfalls identische Typen unterschiedlich werden.
// 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
Die __brand-Eigenschaft existiert zur Laufzeit nie (der Wert ist nur ein String), aber im Typensystem macht sie UserId und OrderId inkompatibel — verhindert eine ganze Klasse von Verwechslungsfehlern.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Validiere einmal an der Grenze; der Rest des Codes vertraut dem Branded Type.
IDs (UserId vs OrderId), validierte/bereinigte Strings (Email, SafeHtml), Einheiten (Meters vs Feet), PositiveNumber — überall dort, wo zwei Werte einen primitiven Typ teilen, aber nicht verwechselt werden dürfen.
Branded Types fügen nominale Sicherheit hinzu, wo strukturelle Typisierung zu permissiv ist.
Sie fangen Argument-Reihenfolge-Verwechslungen und "unvalidiert vs. validiert"-Verwirrung zur Kompilierungszeit ab, ohne Runtime-Kosten — ein mächtiges Muster für Domain Modeling in großen, korrektheitskritischen Codebasen.