Discriminated unions em TypeScript: tagged unions explicadas

Uma discriminated union (também chamada de tagged union) é uma union de tipos de objeto que têm todos uma propriedade em comum, a tag, com um valor literal diferente em cada membro. Verificar a tag diz ao TypeScript qual membro você tem, e as outras propriedades desse membro ficam disponíveis.

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", ler shape.width seria um erro de compilação, porque o membro círculo não tem width. A tag é um dado comum: em tempo de execução é só uma propriedade string, e o switch é JavaScript puro.

O que torna uma union discriminada

O narrowing pela tag funciona quando três condições valem:

1. Todo membro é um tipo de objeto.
2. Todo membro tem a mesma propriedade (o discriminante). O nome fica a seu critério: kind, type, status e tag são comuns.
3. Em cada membro, essa propriedade tem um literal type: um literal de string, number ou boolean, 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 };

Se um membro declara a tag como string simples em vez de um literal, comparar a tag deixa de estreitar a union, e as propriedades específicas de cada membro ficam inacessíveis (TS2339).

Narrowing pela tag

Qualquer verificação que o TypeScript entenda sobre a tag estreita o objeto: switch, if/else, === e !==, e até uma tag desestruturada, desde que seja 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
}

Verificar uma propriedade com "radius" in shape também faz narrowing, mas comparar uma tag é mais claro de ler e torna possível a verificação exaustiva.

Verificações exaustivas

O maior benefício do padrão aparece quando a union cresce. Com um tipo de retorno explícito e sem default, o TypeScript sabe que o switch precisa cobrir todas as tags, então um membro novo sem case é erro de compilação:

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

Essa mensagem não diz qual caso está faltando. O helper assertNever diz, e também lança um erro em tempo de execução se dados de fora (JSON, um cliente antigo) trouxerem uma tag que os tipos dizem não poder 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?)

Adicione um quinto status sem case e a linha assertNever(state) mostra Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', indicando o membro. Mais sobre isso na página sobre never.

Tornando impossíveis os estados impossíveis

O RequestState acima substitui um formato comum e mais fraco:

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

Com campos opcionais, "carregando com dados e com erro" passa na verificação de tipos, e todo leitor precisa adivinhar quais combinações podem acontecer de verdade. Com a discriminated union, data só existe no estado success e error só no error, então código que lê state.data precisa antes provar que está no estado success. O próprio tipo documenta os estados válidos.

Modelando resultados: sucesso ou falha

Uma tag boolean basta para "deu certo ou não deu". Este tipo Result é uma alternativa comum a lançar exceções para falhas esperadas, como uma 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

Quem chama não consegue ler result.value sem antes verificar result.ok, que é exatamente a verificação fácil de esquecer com exceções ou com retornos null.

Máquinas de estado e reducers

Duas discriminated unions, uma para os estados e outra para as ações, descrevem uma máquina de estados. Um reducer faz switch sobre a ação e retorna o próximo estado; o compilador verifica que cada objeto retornado é um 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" } só compila porque state foi estreitado antes para o membro playing, então a cópia leva track e position. Retornar só { name: "paused" } seria um erro: um estado pausado precisa de uma faixa. É o mesmo formato que os reducers do Redux e o useReducer do React usam.

A armadilha do widening

A tag precisa continuar sendo um literal type. Um objeto montado em uma variável sem anotação tem a tag alargada para string, e aí não corresponde a nenhum membro:

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

A regra por trás disso, de que propriedades mutáveis são alargadas, é explicada na página sobre literal types.