Poiché TypeScript è tipizzato strutturalmente, un UserId e un OrderId che sono entrambi string sono intercambiabili — il compilatore non può impedirti di mescolarli. I tipi con marchio simulano la tipizzazione allegando un "marchio" univoco e fantasma in modo che i tipi altrimenti identici diventino distinti.
// 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
La proprietà __brand non esiste mai in fase di esecuzione (il valore è solo una stringa), ma nel sistema dei tipi rende UserId e OrderId incompatibili — prevenendo un'intera classe di bug di confusione.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Valida una volta al confine; il resto del codice si fida del tipo con marchio.
ID (UserId vs OrderId), stringhe convalidate/sanitizzate (Email, SafeHtml), unità (Meters vs Feet), PositiveNumber — ovunque due valori condividano un tipo primitivo ma non devono essere confusi.
I tipi con marchio aggiungono sicurezza nominale dove la tipizzazione strutturale è troppo permissiva. Catturano errori di confusione dell'ordine degli argomenti e confusione "non convalidato vs convalidato" in fase di compilazione, a costo di runtime zero — un modello potente per la modellazione del dominio in basi di codice grandi e critiche per la correttezza.