TypeScript Discriminated Unions: Tagged Unions erklärt

Eine Discriminated Union (auch Tagged Union genannt) ist eine Union aus Objekttypen, die alle eine gemeinsame Eigenschaft haben, das Tag, mit einem anderen Literalwert in jedem Member. Die Prüfung des Tags sagt TypeScript, welchen Member du hast, und die übrigen Eigenschaften dieses Members werden verfügbar.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2; // shape is the circle member here
    case "rect":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
  }
}

const shapes: Shape[] = [
  { kind: "circle", radius: 1 },
  { kind: "rect", width: 2, height: 3 },
  { kind: "triangle", base: 4, height: 5 },
];

for (const s of shapes) console.log(s.kind, area(s).toFixed(2));
// circle 3.14
// rect 6.00
// triangle 10.00

In case "circle" wäre das Lesen von shape.width ein Compilerfehler, weil der Kreis-Member kein width hat. Das Tag sind gewöhnliche Daten: Zur Laufzeit ist es einfach eine String-Eigenschaft, und der switch ist reines JavaScript.

Was eine Union zur Discriminated Union macht

Narrowing über das Tag funktioniert, wenn drei Bedingungen erfüllt sind:

1. Jeder Member ist ein Objekttyp.
2. Jeder Member hat denselben Eigenschaftsnamen (die Diskriminante). Der Name ist dir überlassen: kind, type, status und tag sind verbreitet.
3. In jedem Member hat diese Eigenschaft einen Literaltyp: ein String, Zahl oder Boolean-Literal oder null/undefined.

type UiEvent =
  | { type: "click"; x: number; y: number }
  | { type: "keypress"; key: string }
  | { type: "scroll"; delta: number };

type ApiResponse =
  | { ok: true; data: string }    // boolean literal tags
  | { ok: false; error: string };

type Message =
  | { version: 1; text: string }  // number literal tags
  | { version: 2; text: string; lang: string };

Deklariert ein Member das Tag als einfaches string statt als Literal, engt der Vergleich des Tags die Union nicht mehr ein, und die Eigenschaften der einzelnen Member bleiben unerreichbar (TS2339).

Narrowing über das Tag

Jede Prüfung auf das Tag, die TypeScript versteht, engt das Objekt ein: switch, if/else, === und !==, sogar ein per Destructuring gelesenes Tag, solange es eine const ist:

function describe(e: UiEvent): string {
  if (e.type === "click") return `click at ${e.x},${e.y}`;

  const { type } = e;        // destructured tags narrow too
  if (type === "keypress") return `key ${e.key}`;

  return `scroll by ${e.delta}`; // only "scroll" is left
}

Auch die Prüfung auf eine Eigenschaft mit "radius" in shape engt ein, aber der Vergleich eines Tags liest sich klarer und macht die Vollständigkeitsprüfung möglich.

Vollständigkeitsprüfungen

Der größte Vorteil des Musters zeigt sich, wenn die Union wächst. Mit ausdrücklichem Rückgabetyp und ohne default weiß TypeScript, dass der switch jedes Tag abdecken muss, ein neuer Member ohne case ist also ein Compilerfehler:

// This does not compile: the "square" case is missing
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "square"; size: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
  }
}

console.log(area({ kind: "square", size: 2 }));

index.ts(7,30): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.

Diese Meldung sagt nicht, welcher Fall fehlt. Die Hilfsfunktion assertNever tut es, und sie wirft außerdem zur Laufzeit, wenn Daten von außen (JSON, ein älterer Client) ein Tag tragen, das laut Typen nicht existieren kann:

type RequestState<T> =
  | { status: "idle" }
  | { status: "loading"; startedAt: number }
  | { status: "success"; data: T }
  | { status: "error"; error: string; retryable: boolean };

function assertNever(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}

function render(state: RequestState<string[]>): string {
  switch (state.status) {
    case "idle":
      return "Press load";
    case "loading":
      return `Loading since t=${state.startedAt}`;
    case "success":
      return `Loaded ${state.data.length} items: ${state.data.join(", ")}`;
    case "error":
      return `Failed: ${state.error}${state.retryable ? " (retry?)" : ""}`;
    default:
      return assertNever(state); // state is never here
  }
}

const states: RequestState<string[]>[] = [
  { status: "idle" },
  { status: "loading", startedAt: 1200 },
  { status: "success", data: ["a", "b"] },
  { status: "error", error: "timeout", retryable: true },
];

for (const s of states) console.log(render(s));
// Press load
// Loading since t=1200
// Loaded 2 items: a, b
// Failed: timeout (retry?)

Füge einen fünften Status ohne case hinzu, und die Zeile assertNever(state) meldet Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never' und nennt dabei den Member. Mehr dazu auf der Seite zu never.

Unmögliche Zustände unmöglich machen

RequestState oben ersetzt eine verbreitete, schwächere Form:

// Every combination is allowed, including nonsense
type LooseState<T> = {
  loading: boolean;
  data?: T;
  error?: string;
};

const nonsense: LooseState<string[]> = { loading: true, data: ["a"], error: "timeout" };

Mit optionalen Feldern besteht „lädt, mit Daten und einem Fehler“ die Typprüfung, und jeder Leser muss raten, welche Kombinationen wirklich vorkommen. Mit der Discriminated Union existiert data nur im Zustand success und error nur in error, also muss Code, der state.data liest, zuerst beweisen, dass er im Zustand success ist. Der Typ selbst dokumentiert die gültigen Zustände.

Ergebnisse modellieren: Erfolg oder Fehlschlag

Ein Boolean-Tag reicht für „hat funktioniert oder nicht“. Dieser Typ Result ist eine verbreitete Alternative zum Werfen von Exceptions bei erwarteten Fehlschlägen wie ungültigen Eingaben:

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parsePort(text: string): Result<number> {
  const n = Number(text);
  if (!Number.isInteger(n)) return { ok: false, error: `"${text}" is not a whole number` };
  if (n < 1 || n > 65535) return { ok: false, error: `${n} is out of range` };
  return { ok: true, value: n };
}

for (const input of ["8080", "http", "70000"]) {
  const result = parsePort(input);
  if (result.ok) {
    console.log("port", result.value);   // result.value exists only here
  } else {
    console.log("error:", result.error); // result.error exists only here
  }
}
// port 8080
// error: "http" is not a whole number
// error: 70000 is out of range

Der Aufrufer kann result.value nicht lesen, ohne vorher result.ok zu prüfen, und genau diese Prüfung vergisst man bei Exceptions oder Rückgaben von null leicht.

Zustandsautomaten und Reducer

Zwei Discriminated Unions, eine für Zustände und eine für Aktionen, beschreiben einen Zustandsautomaten. Ein Reducer macht einen switch über die Aktion und gibt den nächsten Zustand zurück; der Compiler prüft, dass jedes zurückgegebene Objekt ein gültiger Zustand ist:

type State =
  | { name: "idle" }
  | { name: "playing"; track: string; position: number }
  | { name: "paused"; track: string; position: number };

type Action =
  | { type: "play"; track: string }
  | { type: "pause" }
  | { type: "resume" }
  | { type: "stop" };

function reduce(state: State, action: Action): State {
  switch (action.type) {
    case "play":
      return { name: "playing", track: action.track, position: 0 };
    case "pause":
      return state.name === "playing" ? { ...state, name: "paused" } : state;
    case "resume":
      return state.name === "paused" ? { ...state, name: "playing" } : state;
    case "stop":
      return { name: "idle" };
  }
}

const actions: Action[] = [{ type: "play", track: "Intro" }, { type: "pause" }, { type: "resume" }, { type: "stop" }];

let state: State = { name: "idle" };
for (const a of actions) {
  state = reduce(state, a);
  console.log(a.type.padEnd(6), "->", state.name);
}
// play   -> playing
// pause  -> paused
// resume -> playing
// stop   -> idle

{ ...state, name: "paused" } kompiliert nur, weil state vorher auf den Member für die Wiedergabe eingeengt wurde, sodass die Kopie track und position mitbringt. Nur { name: "paused" } zurückzugeben wäre ein Fehler: Ein pausierter Zustand braucht einen Track. Das ist dieselbe Form, die Reducer in Redux und useReducer in React verwenden.

Die Falle beim Widening

Das Tag muss ein Literaltyp bleiben. Bei einem Objekt, das ohne Annotation in einer Variablen aufgebaut wird, wird das Tag zu string erweitert, und dann passt es zu keinem Member:

type Shape = { kind: "circle"; radius: number } | { kind: "rect"; width: number; height: number };
declare function area(shape: Shape): number;

const c = { kind: "circle", radius: 2 }; // kind: string
area(c);
// error TS2345: Argument of type '{ kind: string; radius: number; }' is not assignable to parameter of type 'Shape'.

const ok1: Shape = { kind: "circle", radius: 2 };        // annotate the variable
const ok2 = { kind: "circle", radius: 2 } as const;      // or keep the literal with as const
area({ kind: "circle", radius: 2 });                     // or build it where Shape is expected

Die zugrunde liegende Regel, dass veränderbare Eigenschaften erweitert werden, wird auf der Seite zu Literaltypen erklärt.