Branded types em TypeScript: tipagem nominal com exemplos

O TypeScript compara tipos pelo formato, então dois aliases de string são intercambiáveis. Um branded type acrescenta uma etiqueta que existe só no sistema de tipos, string & { readonly __brand: "UserId" }, o que torna um UserId incompatível com uma string simples e com todas as outras brands:

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)

Em tempo de execução, userId é só a string "u_42". A brand é um rótulo de tempo de compilação, e a única função dela é impedir que IDs, unidades e strings validadas sejam misturados.

O problema: aliases são só nomes

Um type alias não cria um tipo novo. Ele dá um segundo nome a um tipo que já existe, e o compilador trata os dois nomes como a mesma coisa:

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)

Isso é tipagem estrutural: o TypeScript verifica se o formato encaixa, e string encaixa em string. Para objetos, os formatos costumam ser diferentes; para IDs, emails, moedas e unidades, nunca são. As brands resolvem esse caso específico.

Como a brand funciona

string & { readonly __brand: "UserId" } é uma interseção: o valor precisa ser uma string e também ter uma propriedade __brand do tipo "UserId". Nenhuma string real tem essa propriedade, então nenhuma string simples é atribuível a ele:

// 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"'.

A direção que importa continua funcionando: um UserId é uma string, então você pode passá-lo para qualquer coisa que receba uma string, chamar .startsWith() nele ou colocá-lo em um template. A brand só bloqueia a entrada.

Funções construtoras que validam

A assertion as UserId é a única porta de entrada, e uma assertion não verifica nada. Coloque-a em uma única função que valida a entrada, e aí todo valor com brand no programa terá passado por essa verificação:

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 verifica a entrada de novo, porque o tipo do parâmetro diz que a verificação já aconteceu. Essa é a ideia de "parse, don't validate": verifique na fronteira e depois carregue a prova no tipo. Um type guard também serve de construtor quando você prefere um boolean a uma exceção: function isEmail(s: string): s is Email.

Um helper Brand genérico

Escrever a interseção à mão para cada tipo fica repetitivo. Um pequeno generic faz isso uma vez só:

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

Aplicar brand a um número funciona do mesmo jeito que a uma string. Repare que amount / 100 é um number simples: aritmética sobre um número com brand dá um resultado sem brand, como mostrado mais abaixo.

Brands com unique symbol

Um nome de propriedade string como __brand parece uma propriedade de verdade: userId.__brand passa na verificação de tipos como "UserId", mas é undefined em tempo de execução, e duas bibliotecas podem escolher o mesmo nome. Uma chave unique symbol evita os dois problemas:

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 um symbol que existe só para o verificador de tipos; a palavra-chave declare faz com que nenhum JavaScript seja gerado para ele. Como o symbol não é exportado do módulo, código em outros arquivos nem consegue dar nome à propriedade da brand, então fora desse módulo os únicos jeitos de obter um Meters são as funções que você exporta ou uma assertion as Meters.

Brands não custam nada em tempo de execução

A saída compilada não tem nenhum vestígio da brand. Estas são as linhas geradas para o exemplo de Meters, abaixo do cabeçalho de módulo que o compilador adiciona: o declare, os dois type aliases e todos os as sumiram, e a chamada suprimida na última linha ainda é executada.

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);

Um valor com brand é o primitivo simples: typeof dá "string" ou "number", JSON.stringify o escreve como sempre e as comparações funcionam como antes. O outro lado é que nada é verificado em tempo de execução, a menos que a sua função construtora verifique. Dados lidos de JSON, de um banco de dados ou de uma URL chegam como string, e só viram um UserId quando você os passa por essa função.

Aritmética e métodos perdem a brand

Operações sobre um valor com brand retornam o tipo base, porque a brand não faz parte do que + ou .slice() produzem:

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 é isso que você quer: somar dois valores em centavos dá centavos, mas multiplicar centavos por centavos não dá, e só você sabe quais operações mantêm o significado. Escreva pequenos helpers como addCents(a: Cents, b: Cents): Cents para as operações de que o seu código precisa.

Quando usar branded types

Use brands quando confundir dois valores do mesmo tipo primitivo é um risco real e o compilador não tem outro jeito de ajudar:

Dispense-as para valores que nunca são confundidos e para tipos de objeto que já têm formatos diferentes. Bibliotecas de validação podem produzir branded types a partir de um schema: no Zod, z.string().brand<"UserId">() dá um schema cujo parse retorna um UserId com brand, o que evita escrever as funções construtoras à mão.