Protože je TypeScript strukturálně typovaný, UserId a OrderId, které jsou oba string, jsou zaměnitelné — kompilátor vás nemůže zastavit před jejich smícháním. Značené typy simulují nominální typování připojením jedinečné, fantómové "značky", takže se jinak identické typy stanou odlišné.
// 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
Vlastnost __brand v době běhu nikdy neexistuje (hodnota je jen řetězec), ale v systému typů činí UserId a OrderId nekompatibilní — zabraňují celé třídě chyb pomíchání.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Zavalidujte jednou na hranici; zbytek kódu důvěřuje značenému typu.
ID (UserId vs OrderId), ověřené/čištěné řetězce (Email, SafeHtml), jednotky (Meters vs Feet), PositiveNumber — kdekoli se dvě hodnoty dělí primitivní typ, ale nesmějí být zaměňovány.
Značené typy přidávají nominální bezpečnost tam, kde je strukturální typování příliš tolerantní.
Zachycují chyby v pořadí argumentů a zmatení "neověřené vs ověřené" v čase kompilace, s nulovou cenou za běh — mocný vzor pro modelování domény ve velkých, bezpečnostně kritických kódech.