Что такое discriminated union? Приведите реальный пример.

Что такое discriminated union

Discriminated union (размеченное объединение) — это union-тип, у всех вариантов которого есть общее поле с literal-типом. TypeScript использует это поле как дискриминант: в switch или if по дискриминанту компилятор сужает тип до конкретного варианта и даёт доступ только к его полям.

Три условия для корректного discriminated union:

1. Каждый вариант — отдельный объектный тип.
2. У всех вариантов одно поле с уникальным literal-типом (string, number, boolean).
3. Union собирается через |.

Пример — состояние асинхронного запроса

type FetchState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string; retryAfter?: number };

function renderJobList(state: FetchState<Job[]>): string {
  switch (state.status) {
    case 'idle':    return '<p>Нажмите «Найти»</p>';
    case 'loading': return '<p>Загрузка...</p>';
    case 'success': return state.data.map(j => j.title).join(', ');
    case 'error':   return `<p>Ошибка: ${state.message}</p>`;
    default: {
      // Exhaustive check: если добавить новый статус и забыть case,
      // TypeScript укажет на ошибку здесь, а не в runtime
      const _never: never = state;
      throw new Error(`Unhandled state: ${JSON.stringify(_never)}`);
    }
  }
}

Пример — WebSocket-события

type WsMessage =
  | { type: 'job_created'; payload: Job }
  | { type: 'job_updated'; payload: Partial<Job>; id: string }
  | { type: 'ping' };

function handleMessage(msg: WsMessage) {
  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
    return;
  }
  if (msg.type === 'job_created') {
    store.addJob(msg.payload); // TypeScript знает: payload — Job
    return;
  }
  store.updateJob(msg.id, msg.payload); // payload — Partial<Job>
}

Exhaustive check без switch

function assertNever(x: never): never {
  throw new Error(`Unexpected value: ${JSON.stringify(x)}`);
}

function getLabel(state: FetchState<unknown>): string {
  if (state.status === 'idle')    return 'Idle';
  if (state.status === 'loading') return 'Loading';
  if (state.status === 'success') return 'Done';
  if (state.status === 'error')   return state.message;
  return assertNever(state); // TS error, если забыт вариант
}

Подводные камни

• Дискриминант должен быть literal-типом — если использовать string вместо 'success', TypeScript не сможет сузить тип и потеряет всю пользу.
• Забытый default + never — без exhaustive check добавление нового варианта не вызовет ошибку компиляции; баг обнаружится только в runtime.
• Общие поля с разными типами — если поле с одним именем присутствует в нескольких вариантах с разными типами, после сужения TypeScript даст тип-пересечение, что может удивить.
• Вложенные union без дискриминанта — если один из вариантов сам является union без дискриминанта, сужение перестаёт работать предсказуемо.
• Сериализация/десериализация — данные из API приходят как unknown; без runtime-валидации (zod, io-ts) TypeScript не гарантирует, что поле status действительно соответствует одному из literal-значений.
• Производительность при большом числе вариантов — union из 30+ вариантов заметно замедляет type checking; в таких случаях стоит рассмотреть discriminated union с числовым кодом или разбить на вложенные union.

• Смешивать «discriminated union» с похожим механизмом без критерия выбора.
• Игнорировать риск: неверно оценить границы применения темы «discriminated union» и получить хрупкое решение.
• Показывать только синтаксис и не объяснять поведение в runtime или сборке.

• Объясняет моделирование вариантов состояния по общему literal-полю.
• Показывает на примере, как работает: общее поле-дискриминант позволяет TypeScript сузить union в switch и проверить exhaustive handling через never.
• Называет production-нюанс и граничный случай для темы «discriminated union».