Discriminated union in TypeScript: le unioni con tag spiegate

Una discriminated union (detta anche tagged union) è una union di tipi oggetto che hanno tutti una proprietà in comune, il tag, con un valore letterale diverso in ogni membro. Controllare il tag dice a TypeScript quale membro hai, e le altre proprietà di quel membro diventano disponibili.

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 case "circle", leggere shape.width sarebbe un errore di compilazione, perché il membro cerchio non ha width. Il tag è un dato normale: a runtime è solo una proprietà stringa, e lo switch è JavaScript semplice.

Cosa rende discriminata una union

Il restringimento sul tag funziona quando valgono tre condizioni:

1. Ogni membro è un tipo oggetto.
2. Ogni membro ha lo stesso nome di proprietà (il discriminante). Il nome lo scegli tu: kind, type, status e tag sono comuni.
3. In ogni membro, quella proprietà ha un tipo letterale: un letterale stringa, numerico o booleano, oppure 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 un membro dichiara il tag come semplice string invece che come letterale, confrontare il tag non restringe più la union, e le proprietà specifiche dei membri restano irraggiungibili (TS2339).

Restringere sul tag

Qualsiasi controllo sul tag che TypeScript capisce restringe l'oggetto: switch, if/else, === e !==, perfino un tag destrutturato purché sia un 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
}

Anche controllare una proprietà con "radius" in shape restringe, ma confrontare un tag è più chiaro da leggere e rende possibile il controllo di esaustività.

Controlli di esaustività

Il vantaggio più grande del pattern emerge quando la union cresce. Con un tipo di ritorno esplicito e nessun default, TypeScript sa che lo switch deve coprire ogni tag, quindi un nuovo membro senza il suo caso è un errore di compilazione:

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

Quel messaggio non dice quale caso manca. L'helper assertNever sì, e lancia anche un errore a runtime se dati dall'esterno (JSON, un client più vecchio) portano un tag che secondo i tipi non può esistere:

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

Aggiungi un quinto stato senza il suo caso e la riga assertNever(state) segnala Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', nominando il membro. Altro su questo nella pagina su never.

Rendere impossibili gli stati impossibili

RequestState qui sopra sostituisce una forma comune e più debole:

// 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 i campi facoltativi, "in caricamento con dati e un errore" supera il controllo dei tipi, e chi legge deve indovinare quali combinazioni possono accadere davvero. Con la discriminated union, data esiste solo nello stato success ed error solo in error, quindi il codice che legge state.data deve prima dimostrare di essere nello stato success. Il tipo stesso documenta gli stati validi.

Modellare i risultati: successo o fallimento

Un tag booleano basta per "ha funzionato o no". Questo tipo Result è un'alternativa comune al lancio di eccezioni per fallimenti previsti come un input non valido:

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

Chi chiama non può leggere result.value senza controllare prima result.ok, che è proprio il controllo facile da dimenticare con le eccezioni o con i ritorni null.

Macchine a stati e reducer

Due discriminated union, una per gli stati e una per le azioni, descrivono una macchina a stati. Un reducer fa lo switch sull'azione e restituisce lo stato successivo; il compilatore verifica che ogni oggetto restituito sia uno stato valido:

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 perché state era stato prima ristretto al membro in riproduzione, quindi la copia porta con sé track e position. Restituire solo { name: "paused" } sarebbe un errore: uno stato in pausa ha bisogno di una traccia. È la stessa forma usata dai reducer di Redux e da useReducer in React.

La trappola dell'allargamento

Il tag deve restare un tipo letterale. Un oggetto costruito in una variabile senza annotazione ha il tag allargato a string, e a quel punto non corrisponde a nessun 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

La regola di fondo, cioè che le proprietà modificabili vengono allargate, è spiegata nella pagina sui tipi letterali.