Uniones discriminadas en TypeScript: tagged unions explicadas

Una unión discriminada (también llamada tagged union) es una unión de tipos objeto que tienen en común una propiedad, la etiqueta, con un valor literal distinto en cada miembro. Comprobar la etiqueta le dice a TypeScript qué miembro tienes, y las demás propiedades de ese miembro pasan a estar 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

Dentro de case "circle", leer shape.width sería un error de compilación, porque el miembro círculo no tiene width. La etiqueta son datos normales: en tiempo de ejecución es solo una propiedad string, y el switch es JavaScript normal.

Qué hace que una unión sea discriminada

El estrechamiento por la etiqueta funciona cuando se cumplen tres condiciones:

1. Todos los miembros son tipos objeto.
2. Todos los miembros tienen el mismo nombre de propiedad (el discriminante). El nombre lo eliges tú: kind, type, status y tag son habituales.
3. En cada miembro, esa propiedad tiene un tipo literal: un literal string, number o boolean, o 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 miembro declara la etiqueta como string a secas en lugar de un literal, comparar la etiqueta deja de estrechar la unión, y las propiedades específicas de cada miembro quedan fuera de alcance (TS2339).

Estrechar por la etiqueta

Cualquier comprobación sobre la etiqueta que TypeScript entienda estrecha el objeto: switch, if/else, === y !==, incluso una etiqueta desestructurada siempre que sea una 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
}

Comprobar una propiedad con "radius" in shape también estrecha, pero comparar una etiqueta se lee mejor y hace posible la comprobación exhaustiva.

Comprobaciones exhaustivas

La mayor ventaja del patrón aparece cuando la unión crece. Con un tipo de retorno explícito y sin default, TypeScript sabe que el switch debe cubrir todas las etiquetas, así que un miembro nuevo sin su case es un error de compilación:

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

Ese mensaje no dice qué case falta. La función auxiliar assertNever sí, y además lanza un error en tiempo de ejecución si datos de fuera (JSON, un cliente antiguo) traen una etiqueta que según los tipos no puede existir:

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

Añade un quinto status sin su case y la línea assertNever(state) informa Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', nombrando el miembro. Hay más sobre esto en la página de never.

Hacer imposibles los estados imposibles

El RequestState de arriba sustituye a una forma habitual y más débil:

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

Con campos opcionales, «cargando, con datos y con un error» pasa la comprobación de tipos, y cada lector tiene que adivinar qué combinaciones pueden darse de verdad. Con la unión discriminada, data solo existe en el estado success y error solo en error, así que el código que lee state.data tiene que demostrar antes que está en el estado success. El propio tipo documenta los estados válidos.

Modelar resultados: éxito o fallo

Una etiqueta booleana basta para «funcionó o no funcionó». Este tipo Result es una alternativa habitual a lanzar excepciones para fallos esperados, como una entrada inválida:

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

Quien llama no puede leer result.value sin comprobar antes result.ok, que es justo la comprobación que es fácil olvidar con excepciones o con retornos null.

Máquinas de estados y reducers

Dos uniones discriminadas, una para los estados y otra para las acciones, describen una máquina de estados. Un reducer hace switch sobre la acción y devuelve el siguiente estado; el compilador comprueba que cada objeto devuelto es un estado válido:

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" } compila solo porque state se estrechó antes al miembro playing, así que la copia lleva track y position. Devolver { name: "paused" } a secas sería un error: un estado en pausa necesita una pista. Es la misma forma que usan los reducers de Redux y useReducer en React.

La trampa del ensanchamiento

La etiqueta tiene que seguir siendo un tipo literal. En un objeto construido en una variable sin anotación, la etiqueta se ensancha a string, y entonces no encaja con ningún miembro:

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 regla de fondo, que las propiedades mutables se ensanchan, se explica en la página de tipos literales.