Como TypeScript é estruturalmente tipado, um UserId e um OrderId que são ambos string são intercambiáveis — o compilador não consegue impedir que você os misture. Tipos marcados simulam tipagem nominal anexando uma "marca" única e fantasma, tornando tipos normalmente idênticos distintos.
// 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
A propriedade __brand nunca existe em tempo de execução (o valor é apenas uma string), mas no sistema de tipos torna UserId e OrderId incompatíveis — prevenindo toda uma classe de bugs de confusão.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Valide uma vez na fronteira; o resto do código confia no tipo marcado.
IDs (UserId vs OrderId), strings validadas/sanitizadas (Email, SafeHtml), unidades (Meters vs Feet), PositiveNumber — em qualquer lugar onde dois valores compartilham um tipo primitivo mas não devem ser confundidos.
Tipos marcados adicionam segurança nominal onde a tipagem estrutural é muito permissiva.
Eles capturam confusões de ordem de argumentos e confusões de "não validado versus validado" em tempo de compilação, com zero custo em tempo de execução — um padrão poderoso para modelagem de domínio em grandes bases de código críticas para correção.