Branded types en TypeScript: tipado nominal con ejemplos

TypeScript compara los tipos por su forma, así que dos alias de string son intercambiables. Un branded type añade una etiqueta que solo existe en el sistema de tipos, string & { readonly __brand: "UserId" }, que hace que un UserId sea incompatible con un string normal y con cualquier otra marca:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const userId = "u_42" as UserId;
const orderId = "ord_7" as OrderId;

loadUser(userId); // loading user u_42

// @ts-expect-error: an OrderId is not a UserId
loadUser(orderId); // loading user ord_7 (the error is suppressed, and types do not exist at runtime)

En ejecución, userId es solo el string "u_42". La marca es una etiqueta de compilación, y su única función es impedir que se mezclen IDs, unidades y strings validados.

El problema: los alias son solo nombres

Un type alias no crea un tipo nuevo. Da un segundo nombre a un tipo que ya existe, y el compilador trata los dos nombres como la misma cosa:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: both are just string
// cancelling u_42  (the bug ships)

Esto es tipado estructural: TypeScript comprueba que la forma encaja, y string encaja con string. En los objetos las formas suelen diferir; en IDs, emails, monedas y unidades, nunca. Las marcas resuelven ese caso concreto.

Cómo funciona la marca

string & { readonly __brand: "UserId" } es una intersección: un valor tiene que ser un string y además tener una propiedad __brand de tipo "UserId". Ningún string real tiene esa propiedad, así que ningún string normal se le puede asignar:

// This does not compile: a plain string, and a different brand, are both rejected
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const orderId = "ord_7" as OrderId;
loadUser("u_42");
loadUser(orderId);

index.ts(10,10): error TS2345: Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type '{ readonly __brand: "UserId"; }'.
index.ts(11,10): error TS2345: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
  Type 'OrderId' is not assignable to type '{ readonly __brand: "UserId"; }'.
    Types of property '__brand' are incompatible.
      Type '"OrderId"' is not assignable to type '"UserId"'.

La dirección que importa sigue funcionando: un UserId es un string, así que puedes pasarlo a cualquier cosa que reciba un string, llamar a .startsWith() sobre él o meterlo en una plantilla. La marca solo bloquea la entrada.

Funciones constructoras que validan

La aserción as UserId es la única forma de entrar, y una aserción no comprueba nada. Ponla en una función que valide la entrada, y así sabes que todo valor con marca del programa ha pasado esa comprobación:

type Email = string & { readonly __brand: "Email" };

function toEmail(input: string): Email {
  const trimmed = input.trim().toLowerCase();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(trimmed)) {
    throw new Error(`not an email: ${input}`);
  }
  return trimmed as Email; // the only "as Email" in the codebase
}

function sendWelcome(to: Email) {
  console.log("sending to", to);
}

sendWelcome(toEmail("  Ada@Example.com ")); // sending to ada@example.com

try {
  sendWelcome(toEmail("ada at example"));
} catch (e) {
  console.log((e as Error).message); // not an email: ada at example
}

sendWelcome nunca vuelve a comprobar su entrada, porque el tipo de su parámetro dice que la comprobación ya se hizo. Es la idea de «parse, don't validate»: comprueba en la frontera y lleva la prueba en el tipo. Un type guard también sirve como constructor si prefieres un booleano a una excepción: function isEmail(s: string): s is Email.

Un helper genérico Brand

Escribir la intersección a mano para cada tipo se vuelve repetitivo. Un genérico pequeño lo hace una sola vez:

type Brand<T, Name extends string> = T & { readonly __brand: Name };

type ProductId = Brand<string, "ProductId">;
type Cents = Brand<number, "Cents">;

const cents = (n: number): Cents => {
  if (!Number.isInteger(n)) throw new Error("cents must be whole");
  return n as Cents;
};

function price(id: ProductId, amount: Cents): string {
  return `${id}: $${(amount / 100).toFixed(2)}`;
}

console.log(price("p_1" as ProductId, cents(1999))); // p_1: $19.99

Marcar un número funciona igual que marcar un string. Fíjate en que amount / 100 es un number normal: la aritmética sobre un número con marca da un resultado sin marca, como se explica más abajo.

Marcas con unique symbol

Un nombre de propiedad string como __brand parece una propiedad real: userId.__brand pasa la comprobación como "UserId" pero es undefined en ejecución, y dos librerías podrían elegir el mismo nombre. Una clave unique symbol evita las dos cosas:

declare const brand: unique symbol;

type Brand<T, Name extends string> = T & { readonly [brand]: Name };

type Meters = Brand<number, "Meters">;
type Feet = Brand<number, "Feet">;

function toMeters(feet: Feet): Meters {
  return (feet * 0.3048) as Meters;
}

const height = 10 as Feet;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048

// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

declare const brand: unique symbol declara un símbolo que solo existe para el comprobador de tipos; la palabra clave declare significa que no se genera JavaScript para él. Como el símbolo no se exporta de su módulo, el código de otros archivos ni siquiera puede nombrar la propiedad de la marca, así que fuera de ese módulo las únicas formas de obtener un Meters son las funciones que exportes o una aserción as Meters.

Las marcas no cuestan nada en ejecución

La salida compilada no contiene ni rastro de la marca. Estas son las líneas generadas para el ejemplo de Meters, debajo de la cabecera de módulo que añade el compilador: el declare, los dos type aliases y todos los as han desaparecido, y la llamada suprimida de la última línea se sigue ejecutando.

function toMeters(feet) {
    return (feet * 0.3048);
}
const height = 10;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048
// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

Un valor con marca es el primitivo tal cual: typeof da "string" o "number", JSON.stringify lo escribe como siempre y las comparaciones funcionan igual que antes. La otra cara es que no se comprueba nada en ejecución salvo lo que compruebe tu función constructora. Los datos que se leen de JSON, de una base de datos o de una URL llegan como string, y solo pasan a ser un UserId cuando los pasas por esa función.

La aritmética y los métodos pierden la marca

Las operaciones sobre un valor con marca devuelven el tipo base, porque la marca no forma parte de lo que producen + o .slice():

type Cents = number & { readonly __brand: "Cents" };

const a = 500 as Cents;
const b = 250 as Cents;

const sum = a + b;           // number, not Cents
const total: Cents = a + b;  // error TS2322: Type 'number' is not assignable to type 'Cents'
const fixed = (a + b) as Cents; // re-brand when the result is still valid

Normalmente es lo que quieres: sumar dos importes en céntimos da céntimos, pero multiplicar céntimos por céntimos no, y solo tú sabes qué operaciones conservan el significado. Escribe helpers pequeños como addCents(a: Cents, b: Cents): Cents para las operaciones que necesite tu código.

Cuándo usar branded types

Usa marcas donde confundir dos valores del mismo tipo primitivo sea un riesgo real y el compilador no pueda ayudarte de otra forma:

No las uses para valores que nunca se confunden ni para tipos objeto que ya tienen formas distintas. Las librerías de validación pueden producir branded types a partir de un esquema: en Zod, z.string().brand<"UserId">() da un esquema cuyo parse devuelve un UserId con marca, lo que te ahorra escribir las funciones constructoras a mano.