TypeScript Branded Types: nominale Typisierung mit Beispielen

TypeScript vergleicht Typen nach ihrer Form, also sind zwei Aliase von string austauschbar. Ein Branded Type fügt eine Markierung hinzu, die nur im Typsystem existiert, string & { readonly __brand: "UserId" }, und macht eine UserId damit inkompatibel mit einem einfachen String und mit jedem anderen Brand:

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)

Zur Laufzeit ist userId einfach der String "u_42". Der Brand ist ein Etikett beim Kompilieren, und seine einzige Aufgabe ist es, zu verhindern, dass IDs, Einheiten und validierte Strings verwechselt werden.

Das Problem: Aliase sind nur Namen

Ein Type Alias erzeugt keinen neuen Typ. Er gibt einem bestehenden Typ einen zweiten Namen, und der Compiler behandelt beide Namen als dasselbe:

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)

Das ist strukturelle Typisierung: TypeScript prüft, ob die Form passt, und string passt zu string. Bei Objekten unterscheiden sich die Formen meist; bei IDs, E-Mail-Adressen, Währungen und Einheiten nie. Brands lösen genau diesen einen Fall.

Wie der Brand funktioniert

string & { readonly __brand: "UserId" } ist eine Intersection: Ein Wert muss ein String sein und zusätzlich eine Eigenschaft __brand vom Typ "UserId" haben. Kein echter String hat diese Eigenschaft, also lässt sich kein einfacher String zuweisen:

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

Die Richtung, auf die es ankommt, funktioniert weiterhin: Eine UserId ist ein String, also kannst du sie an alles übergeben, was einen String nimmt, .startsWith() darauf aufrufen oder sie in ein Template setzen. Der Brand versperrt nur den Weg hinein.

Konstruktorfunktionen, die validieren

Die Assertion as UserId ist der einzige Weg hinein, und eine Assertion prüft nichts. Setze sie in eine Funktion, die die Eingabe validiert, dann ist von jedem gebrandeten Wert im Programm bekannt, dass er diese Prüfung bestanden hat:

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 prüft seine Eingabe nie wieder, weil sein Parametertyp sagt, dass die Prüfung schon passiert ist. Das ist die Idee "parse, don't validate": an der Grenze prüfen, dann den Nachweis im Typ weitertragen. Ein Type Guard eignet sich ebenfalls als Konstruktor, wenn dir ein Boolean lieber ist als eine Exception: function isEmail(s: string): s is Email.

Ein generischer Brand-Helfer

Die Intersection für jeden Typ von Hand zu schreiben, wird schnell eintönig. Ein kleines Generic erledigt das einmal:

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

Eine Zahl zu branden funktioniert genauso wie einen String zu branden. Beachte, dass amount / 100 ein einfaches number ist: Arithmetik mit einer gebrandeten Zahl ergibt ein Ergebnis ohne Brand, dazu weiter unten mehr.

Brands mit unique symbol

Ein String-Eigenschaftsname wie __brand sieht aus wie eine echte Eigenschaft: userId.__brand besteht die Typprüfung als "UserId", ist zur Laufzeit aber undefined, und zwei Bibliotheken könnten denselben Namen wählen. Ein Schlüssel vom Typ unique symbol vermeidet beides:

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 deklariert ein Symbol, das nur für den Type Checker existiert; das Schlüsselwort declare bedeutet, dass dafür kein JavaScript erzeugt wird. Weil das Symbol nicht aus seinem Modul exportiert wird, kann Code in anderen Dateien die Brand-Eigenschaft nicht einmal benennen. Außerhalb dieses Moduls kommst du also nur über die exportierten Funktionen oder über eine Assertion as Meters an ein Meters.

Brands kosten zur Laufzeit nichts

Die kompilierte Ausgabe enthält keine Spur des Brands. Das sind die Zeilen, die für das Meters-Beispiel erzeugt werden, unterhalb des Modul-Headers, den der Compiler hinzufügt: Das declare, beide Type Aliases und jedes as sind verschwunden, und der unterdrückte Aufruf in der letzten Zeile läuft trotzdem.

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

Ein gebrandeter Wert ist der einfache primitive Wert: typeof ergibt "string" oder "number", JSON.stringify schreibt ihn wie gewohnt, und Vergleiche funktionieren wie vorher. Die Kehrseite: Zur Laufzeit wird nichts geprüft, außer deine Konstruktorfunktion prüft es. Daten aus JSON, einer Datenbank oder einer URL kommen als string an und werden erst zu einer UserId, wenn du sie durch diese Funktion schickst.

Arithmetik und Methoden verlieren den Brand

Operationen auf einem gebrandeten Wert geben den Basistyp zurück, weil der Brand nicht zu dem gehört, was + oder .slice() erzeugen:

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

Meist ist das genau richtig: Zwei Beträge in Cent zu addieren, ergibt Cent, Cent mal Cent aber nicht, und nur du weißt, welche Operationen die Bedeutung erhalten. Schreibe kleine Helfer wie addCents(a: Cents, b: Cents): Cents für die Operationen, die dein Code braucht.

Wann Branded Types sinnvoll sind

Nutze Brands dort, wo die Verwechslung zweier Werte desselben primitiven Typs ein echtes Risiko ist und der Compiler sonst nicht helfen kann:

Lass sie weg bei Werten, die nie verwechselt werden, und bei Objekttypen, die sich in ihrer Form schon unterscheiden. Validierungsbibliotheken können Branded Types aus einem Schema erzeugen: In Zod liefert z.string().brand<"UserId">() ein Schema, dessen parse eine gebrandete UserId zurückgibt, und das erspart dir die Konstruktorfunktionen von Hand.