Unie dyskryminowane w TypeScript: tagged unions wyjaśnione

Unia dyskryminowana (nazywana też tagged union) to unia typów obiektowych, które mają jedną wspólną właściwość, znacznik, z inną wartością literałową w każdym członie. Sprawdzenie znacznika mówi TypeScriptowi, z którym członem masz do czynienia, a pozostałe właściwości tego członu stają się dostępne.

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

Wewnątrz case "circle" odczyt shape.width byłby błędem kompilacji, bo człon koła nie ma width. Znacznik to zwykłe dane: w czasie działania to po prostu właściwość z napisem, a switch to zwykły JavaScript.

Co sprawia, że unia jest dyskryminowana

Zawężanie po znaczniku działa, gdy spełnione są trzy warunki:

1. Każdy człon jest typem obiektowym.
2. Każdy człon ma tę samą nazwę właściwości (dyskryminator). Nazwę wybierasz sam: popularne są kind, type, status i tag.
3. W każdym członie ta właściwość ma typ literałowy: literał napisowy, liczbowy albo logiczny, lub 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 };

Jeśli jeden człon zadeklaruje znacznik jako zwykły string zamiast literału, porównanie znacznika przestaje zawężać unię, a właściwości konkretnych członów pozostają niedostępne (TS2339).

Zawężanie po znaczniku

Każde sprawdzenie znacznika zrozumiałe dla TypeScriptu zawęża obiekt: switch, if/else, === i !==, a nawet znacznik wyciągnięty przez destrukturyzację, o ile jest 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
}

Sprawdzenie właściwości przez "radius" in shape też zawęża, ale porównanie znacznika jest czytelniejsze i umożliwia sprawdzanie wyczerpujące.

Sprawdzenia wyczerpujące

Największą korzyść z tego wzorca widać, gdy unia rośnie. Przy jawnym typie zwracanym i bez default TypeScript wie, że switch musi obsłużyć każdy znacznik, więc nowy człon bez swojego case to błąd kompilacji:

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

Ten komunikat nie mówi, którego przypadku brakuje. Pomocnik assertNever to robi, a do tego rzuca wyjątek w czasie działania, gdy dane z zewnątrz (JSON, starszy klient) niosą znacznik, który według typów nie może istnieć:

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

Dodaj piąty status bez case, a linia z assertNever(state) zgłosi Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', podając nazwę członu. Więcej o tym na stronie o never.

Niemożliwe stany naprawdę niemożliwe

Powyższy RequestState zastępuje popularny, słabszy kształt:

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

Przy opcjonalnych polach „ładowanie z danymi i z błędem” przechodzi sprawdzanie typów, a każdy czytelnik musi zgadywać, które kombinacje naprawdę mogą wystąpić. W unii dyskryminowanej data istnieje tylko w stanie success, a error tylko w error, więc kod, który odczytuje state.data, musi najpierw udowodnić, że jest w stanie success. Sam typ dokumentuje poprawne stany.

Modelowanie wyników: sukces albo porażka

Znacznik logiczny wystarczy dla „zadziałało albo nie”. Ten typ Result to popularna alternatywa dla rzucania wyjątków przy spodziewanych porażkach, takich jak nieprawidłowe dane wejściowe:

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

Wywołujący nie może odczytać result.value bez wcześniejszego sprawdzenia result.ok, a właśnie o tym sprawdzeniu łatwo zapomnieć przy wyjątkach albo zwracaniu null.

Maszyny stanów i reducery

Dwie unie dyskryminowane, jedna dla stanów i jedna dla akcji, opisują maszynę stanów. Reducer wykonuje switch po akcji i zwraca następny stan; kompilator sprawdza, czy każdy zwracany obiekt jest poprawnym stanem:

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" } kompiluje się tylko dlatego, że state zostało wcześniej zawężone do członu odtwarzania, więc kopia zawiera track i position. Zwrócenie samego { name: "paused" } byłoby błędem: stan wstrzymania wymaga utworu. To ten sam kształt, którego używają reducery Reduxa i useReducer w React.

Pułapka poszerzania

Znacznik musi pozostać typem literałowym. Obiekt zbudowany w zmiennej bez adnotacji ma znacznik poszerzony do string i nie pasuje wtedy do żadnego członu:

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

Regułę, która za tym stoi, czyli poszerzanie zmiennych właściwości, wyjaśnia strona o typach literałowych.