Unions discriminées en TypeScript : les tagged unions expliquées

Une union discriminée (aussi appelée tagged union) est une union de types objet qui ont tous une propriété en commun, l'étiquette, avec une valeur littérale différente dans chaque membre. Vérifier l'étiquette indique à TypeScript quel membre vous avez, et les autres propriétés de ce membre deviennent disponibles.

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

Dans case "circle", lire shape.width serait une erreur de compilation, car le membre cercle n'a pas de width. L'étiquette est une donnée ordinaire : à l'exécution, c'est juste une propriété de type chaîne, et le switch est du JavaScript pur.

Ce qui rend une union discriminée

Le narrowing sur l'étiquette fonctionne quand trois conditions sont réunies :

1. Chaque membre est un type objet.
2. Chaque membre a la même propriété (le discriminant). Le nom est à votre choix : kind, type, status et tag sont courants.
3. Dans chaque membre, cette propriété a un type littéral : un littéral de chaîne, de nombre ou de booléen, ou 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 };

Si un membre déclare l'étiquette comme simple string au lieu d'un littéral, comparer l'étiquette n'affine plus l'union, et les propriétés propres à chaque membre restent hors de portée (TS2339).

Affiner sur l'étiquette

Toute vérification sur l'étiquette que TypeScript comprend affine l'objet : switch, if/else, === et !==, et même une étiquette déstructurée tant qu'elle est const :

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
}

Vérifier la présence d'une propriété avec "radius" in shape affine aussi, mais comparer une étiquette se lit plus clairement et rend possible la vérification exhaustive.

Vérifications exhaustives

Le plus grand avantage du motif apparaît quand l'union grandit. Avec un type de retour explicite et sans default, TypeScript sait que le switch doit couvrir chaque étiquette : un nouveau membre sans cas est donc une erreur de compilation.

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

Ce message ne dit pas quel cas manque. Le helper assertNever le dit, et il lève aussi une exception à l'exécution si des données extérieures (JSON, un client plus ancien) portent une étiquette que les types déclarent impossible :

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

Ajoutez un cinquième statut sans cas et la ligne assertNever(state) signale Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', en nommant le membre. Plus de détails sur la page never.

Rendre impossibles les états impossibles

Le RequestState ci-dessus remplace une forme courante et plus faible :

// 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" };

Avec des champs optionnels, « en chargement avec des données et une erreur » passe la vérification des types, et chaque lecteur doit deviner quelles combinaisons peuvent réellement se produire. Avec l'union discriminée, data n'existe que dans l'état success et error que dans error : le code qui lit state.data doit donc d'abord prouver qu'il est dans l'état success. Le type documente lui-même les états valides.

Modéliser des résultats : succès ou échec

Une étiquette booléenne suffit pour « ça a marché ou pas ». Ce type Result est une alternative courante aux exceptions pour les échecs attendus, comme une entrée invalide :

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

L'appelant ne peut pas lire result.value sans vérifier d'abord result.ok, et c'est exactement la vérification qu'on oublie facilement avec les exceptions ou les retours null.

Machines à états et reducers

Deux unions discriminées, l'une pour les états et l'autre pour les actions, décrivent une machine à états. Un reducer fait un switch sur l'action et renvoie l'état suivant ; le compilateur vérifie que chaque objet renvoyé est un état valide :

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" } ne compile que parce que state a d'abord été affiné vers le membre de lecture, si bien que la copie emporte track et position. Renvoyer { name: "paused" } seul serait une erreur : un état en pause a besoin d'un morceau. C'est la même forme qu'utilisent les reducers Redux et useReducer dans React.

Le piège de l'élargissement

L'étiquette doit rester un type littéral. Un objet construit dans une variable sans annotation voit son étiquette élargie en string, et il ne correspond alors plus à aucun membre :

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

La règle sous-jacente, selon laquelle les propriétés modifiables s'élargissent, est expliquée sur la page types littéraux.