Parce que TypeScript est typé structurellement, un UserId et un OrderId qui sont tous deux string sont interchangeables — le compilateur ne peut pas vous empêcher de les confondre. Les types nominaux simulent la typification en attachant une unique "marque" fantôme, de sorte que des types sinon identiques deviennent distincts.
// 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 propriété __brand n'existe jamais à l'exécution (la valeur est juste une chaîne), mais dans le système de types, elle rend UserId et OrderId incompatibles — prévenant toute une classe de bugs de confusion.
Les types nominaux ajoutent une sécurité nominale là où la typification structurelle est trop permissive.
Ils détectent à la compilation les confusions d'ordre d'arguments et la confusion "non validé vs validé", sans coût d'exécution — un modèle puissant pour la modélisation de domaines dans de grandes bases de code où la correction est critique.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Validez une fois à la limite ; le reste du code fait confiance au type nominal.
IDs (UserId vs OrderId), chaînes validées/nettoyées (Email, SafeHtml), unités (Meters vs Feet), PositiveNumber — partout où deux valeurs partagent un type primitif mais ne doivent pas être confondues.