Размеченные объединения в TypeScript (tagged unions)

Размеченное объединение (его также называют tagged union) это объединение объектных типов, у которых есть одно общее свойство, тег, с разным литеральным значением в каждом члене. Проверка тега сообщает TypeScript, какой член перед вами, и остальные свойства этого члена становятся доступны.

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

Внутри case "circle" чтение shape.width было бы ошибкой компиляции, потому что у члена-круга нет width. Тег это обычные данные: во время выполнения это просто строковое свойство, а switch это обычный JavaScript.

Что делает объединение размеченным

Сужение по тегу работает, когда выполняются три условия:

1. Каждый член это объектный тип.
2. У каждого члена есть свойство с одинаковым именем (дискриминант). Имя выбираете вы: часто используют kind, type, status и tag.
3. В каждом члене это свойство имеет литеральный тип: строковый, числовой или логический литерал либо 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 };

Если один из членов объявляет тег как обычный string, а не литерал, сравнение тега перестаёт сужать объединение, и свойства конкретных членов остаются недоступны (TS2339).

Сужение по тегу

Любая понятная TypeScript проверка тега сужает объект: switch, if/else, === и !==, даже деструктурированный тег, если он объявлен как 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
}

Проверка наличия свойства через "radius" in shape тоже сужает тип, но сравнение тега читается понятнее и делает возможной исчерпывающую проверку.

Исчерпывающие проверки

Главная польза приёма проявляется, когда объединение растёт. С явным типом возврата и без default TypeScript знает, что switch должен покрыть каждый тег, поэтому новый член без своего case это ошибка компиляции:

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

Это сообщение не говорит, какой вариант пропущен. Вспомогательная функция assertNever говорит, а ещё выбрасывает исключение во время выполнения, если данные извне (JSON, старый клиент) несут тег, которого по типам быть не может:

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

Добавьте пятый статус без case, и строка assertNever(state) сообщит Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', назвав член. Подробнее на странице never.

Невозможные состояния становятся невозможными

RequestState выше заменяет распространённую, более слабую структуру:

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

С необязательными полями «загрузка с данными и ошибкой» проходит проверку типов, и каждому читателю приходится гадать, какие сочетания реально возможны. С размеченным объединением data существует только в состоянии success, а error только в error, поэтому код, читающий state.data, должен сначала доказать, что он в состоянии success. Сам тип документирует допустимые состояния.

Моделирование результатов: успех или ошибка

Для «сработало или нет» достаточно логического тега. Этот тип Result это распространённая альтернатива выбрасыванию исключений при ожидаемых ошибках вроде неверного ввода:

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

Вызывающий код не может прочитать result.value, не проверив сначала result.ok, а именно эту проверку легко забыть с исключениями или с возвратом null.

Конечные автоматы и редьюсеры

Два размеченных объединения, одно для состояний и одно для действий, описывают конечный автомат. Редьюсер делает switch по действию и возвращает следующее состояние; компилятор проверяет, что каждый возвращаемый объект это допустимое состояние:

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" } компилируется только потому, что state сначала сужен до члена playing, и копия несёт track и position. Возврат одного { name: "paused" } был бы ошибкой: состоянию паузы нужен трек. Ту же структуру используют редьюсеры Redux и useReducer в React.

Ловушка расширения типа

Тег должен оставаться литеральным типом. У объекта, собранного в переменную без аннотации, тег расширяется до string, и тогда он не подходит ни под один член:

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

Правило, лежащее в основе (изменяемые свойства расширяются), объясняется на странице литеральные типы.