Como TypeScript usa tipado estructural, un UserId y un OrderId que ambos son string son intercambiables: el compilador no puede impedir que los confundas. Los tipos con marca (branded types) simulan el tipado adjuntando una "marca" fantasma y única para que tipos por lo demás idénticos se vuelvan 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
La propiedad __brand nunca existe en tiempo de ejecución (el valor no es más que un string), pero en el sistema de tipos hace que UserId y OrderId sean incompatibles, previniendo toda una clase de errores por confusión.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Valida una sola vez en el límite; el resto del código confía en el tipo con marca.
Identificadores (UserId vs OrderId), strings validados/saneados (Email, SafeHtml), unidades (Meters vs Feet), PositiveNumber: en cualquier lugar donde dos valores comparten un tipo primitivo pero no deben confundirse.
Los tipos con marca añaden seguridad nominal allí donde el tipado estructural es demasiado permisivo.
Detectan confusiones en el orden de los argumentos y la confusión entre "sin validar y validado" en tiempo de compilación, con cero coste en tiempo de ejecución: un patrón potente para el modelado de dominios en bases de código grandes y críticas en cuanto a corrección.