re:re:actable
Урок 013 минуты чтения

Discriminated union, дискриминатор и exhaustive check

На этой странице
Кратко

Discriminated union (размеченное объединение) — union объектных типов, у которых есть общее поле-дискриминатор с литеральным значением: type, kind, status. Проверив это поле (switch, if), TypeScript точно знает, какой вариант перед ним, и дает доступ к его специфичным полям. Вместе с проверкой полноты через never это самый надежный способ моделировать состояния, события и результаты.

Вопрос

Что такое discriminated union и discriminant property? Как сделать exhaustive check через never?

Базовая схема

type RequestState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: User[] }
  | { status: "error"; message: string };
 
function render(state: RequestState) {
  switch (state.status) {
    case "idle":
      return "Нажмите «Загрузить»";
    case "loading":
      return "Загрузка...";
    case "success":
      return state.data.map((u) => u.name).join(", "); // data доступна только здесь
    case "error":
      return `Ошибка: ${state.message}`;
  }
}

Дискриминатор

Требования к полю-дискриминатору:

  • есть во всех вариантах union;
  • имеет литеральный тип ("success", true, 404), а не string;
  • значения не повторяются между вариантами.
type Good = { kind: "user"; name: string } | { kind: "bot"; version: number };
type Bad = { kind: string; name: string } | { kind: string; version: number }; // сужение не сработает
 
type Result<T> = { ok: true; value: T } | { ok: false; error: Error }; // boolean-литералы тоже работают

Почему лучше набора опциональных полей

// плохо: разрешены невозможные комбинации
type StateBad = {
  isLoading: boolean;
  data?: User[];
  error?: string;
};
const weird: StateBad = { isLoading: true, data: [], error: "?" }; // компилируется
 
// хорошо: каждое состояние описано явно
type StateGood =
  | { status: "loading" }
  | { status: "success"; data: User[] }
  | { status: "error"; error: string };

Принцип «делать невозможные состояния невыразимыми» (make impossible states unrepresentable).

Exhaustive check

function assertNever(value: never): never {
  throw new Error(`Необработанный вариант: ${JSON.stringify(value)}`);
}
 
function getIcon(state: RequestState) {
  switch (state.status) {
    case "idle": return "⏸";
    case "loading": return "⏳";
    case "success": return "✅";
    case "error": return "❌";
    default: return assertNever(state); // state: never
  }
}

Если добавить вариант { status: "cancelled" }, в default тип станет не never, и компилятор укажет на необработанный случай. Альтернатива — явный тип возврата функции и включенный noImplicitReturns: TypeScript сообщит, что не все ветки возвращают значение.

Где применяется

  • состояния запросов и UI (idle/loading/success/error);
  • actions в редьюсерах ({ type: "add"; payload } | { type: "remove"; id });
  • события и сообщения WebSocket;
  • результаты операций (Result<T, E>);
  • варианты пропсов компонента (variant: "link" требует href).
type Action =
  | { type: "add"; item: Todo }
  | { type: "toggle"; id: string }
  | { type: "clear" };
 
function reducer(state: Todo[], action: Action): Todo[] {
  switch (action.type) {
    case "add": return [...state, action.item];
    case "toggle": return state.map((t) => (t.id === action.id ? { ...t, done: !t.done } : t));
    case "clear": return [];
  }
}

Что важно помнить

  • Деструктуризация до проверки ломает сужение: const { status, data } = state — data недоступна; сужайте объект целиком (TS 4.6+ сужает деструктурированные поля, если они const).
  • Дискриминатор удобно извлекать типом: RequestState["status"] — union всех значений.
  • Extract<RequestState, { status: "success" }> достает конкретный вариант.
  • Zod поддерживает z.discriminatedUnion("status", [...]) для валидации таких данных в runtime.

Мини-шпаргалка

  • Union объектов + общее литеральное поле.
  • switch (x.kind) — точное сужение в каждой ветке.
  • Дискриминатор: во всех вариантах, литерал, уникален.
  • Exhaustive check: default: assertNever(x).
  • Невозможные состояния — невыразимы.

Документация

TypeScript Handbook: Discriminated unions, TypeScript Handbook: Exhaustiveness checking.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам