Размеченные объединения

Паттерн: общий литеральный тег

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

type Result =
  | { kind: "ok"; data: string }
  | { kind: "error"; message: string }
  | { kind: "loading" };

function render(r: Result): string {
  switch (r.kind) {
    case "ok":
      return r.data;
      //     ^? (parameter) r: { kind: "ok"; data: string }
    case "error":
      return r.message;
      //     ^? r: { kind: "error"; message: string }
    case "loading":
      return "…";
  }
}

В каждом case r сужен до единственного члена, чей kind совпадает с литералом, поэтому r.data доступен в "ok", а r.message — в "error", и больше нигде. Это заменяет восьмикомбинационную булеву кашу из Hook тремя взаимоисключающими, полностью типизированными состояниями. Недопустимые состояния (data при ошибке) теперь непредставимы.

Требования для работы сужения

Проверяющий распознаёт размеченное объединение, только когда:

1. Дискриминант — литеральный тип, а не расширенный примитив. kind: "ok" работает; kind: string — нет. (Вспомните расширение let/const из урока про сужение — копирование тега в let это ломает.)
2. Каждый член объявляет дискриминант с отдельным литералом. Если два члена делят kind: "ok", проверяющий не различит их и сольёт их поля.
3. Вы ветвитесь по самому дискриминанту (r.kind), а не по производному значению.

// Сломано: расширенный дискриминант
type Bad = { kind: string; data: string } | { kind: string; err: string };
declare const b: Bad;
if (b.kind === "data") {
  b.data;
  // Error: Property 'data' does not exist on type 'Bad'.
  //   — kind это `string`, не литерал, поэтому сужения не происходит
}

Исчерпание через assertNever

Настоящая сила — ловить пропущенные случаи на компиляции. Когда каждый вариант обработан, значение в ветке default имеет тип never. Хелпер, принимающий только never, тогда вызывает ошибку компиляции в тот момент, когда добавлен новый вариант, но оставлен необработанным:

function assertNever(x: never): never {
  throw new Error("Unexpected variant: " + JSON.stringify(x));
}

function render(r: Result): string {
  switch (r.kind) {
    case "ok": return r.data;
    case "error": return r.message;
    case "loading": return "…";
    default: return assertNever(r);
    //                          ^? r: never  — сегодня всё в порядке
  }
}

Теперь добавьте четвёртый вариант { kind: "retrying"; attempt: number } в Result и не трогайте render. Ветка default больше не видит never — она видит { kind: "retrying"; attempt: number }:

// Error: Argument of type '{ kind: "retrying"; attempt: number; }'
//   is not assignable to parameter of type 'never'.

Каждый switch, забывший новый случай, загорается красным по всей кодовой базе. Это самое ценное свойство размеченных объединений для сеньорской работы: система типов превращает «найти все места, которые надо обновить» из ручного grep в гарантированную ошибку компиляции.

Почему это лучше булевых флагов и in

Модель булевых флагов (loading, error, data независимы) допускает 2^n комбинаций, большинство из которых недопустимы. Модель in-защитника из прошлого урока работает, но хрупка при пересечении ключей. Тег-дискриминант однозначен, самодокументируем и — что важнее всего — проверяем на исчерпание. Это каноническая форма для: ответов API (ok/error), экшенов Redux/редьюсера (поле type), стейт-машин UI/сети (idle/loading/success/failure), узлов AST и токенов парсера.

// Экшен в стиле Redux — дискриминант по соглашению `type`
type Action =
  | { type: "increment"; by: number }
  | { type: "reset" };

function reduce(state: number, a: Action): number {
  switch (a.type) {
    case "increment": return state + a.by;
    case "reset": return 0;
    default: return assertNever(a);
  }
}