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.