Условные типы и распределение по объединению

Вид поля формы известен заранее: "checkbox", "text", "number". А тип значения от него зависит — у флажка это boolean, у остальных string. Раньше такую связь пришлось бы описывать двумя отдельными типами и следить за ней глазами. Условный тип записывает её одной строкой.

// вид поля формы известен заранее, а тип его значения пусть вычислит компилятор
type FieldValue<T> = T extends "checkbox" ? boolean : string;
const flag: FieldValue<"checkbox"> = true;
const login: FieldValue<"text"> = "Рико";
const broken: FieldValue<"checkbox"> = "да";
console.log(flag, login, broken);

Диагностика одна, на пятой строке: Тип "string" не может быть назначен для типа "boolean". Компилятор подставил "checkbox" вместо T, проверил условие, взял ветку «да» и получил boolean — строке там места нет. Две строки выше прошли молча: у флажка ветка «да» и правда дала boolean, а у FieldValue<"text"> условие ложно — там string.

Синтаксис буквально повторяет тернарный оператор из части I, только вопрос задаётся не о значении, а о типе. T extends U ? X : Y читается как «если T годится на место U, то X, иначе Y». Вся работа происходит на этапе проверки: до браузера не доезжает ни условие, ни ветки. Поэтому на запуске и напечаталось да — ошибку мы проигнорировали, а строка так и осталась строкой.

Отсюда неудобство, с которым придётся жить всю главу: вычисленный тип негде посмотреть, console.log печатает значения. Зато о нём можно спросить — присвоить заведомо чужое значение и прочитать ответ в диагностике. Этим приёмом пользуется вся статья.

type IsString<T> = T extends string ? "да" : "нет";
// вычисленный тип на экране не появится — спросим о нём компилятор, присвоив значение
const a: IsString<"круг"> = "нет";
const b: IsString<number> = "нет";
console.log(a, b);

Третья строка ошиблась намеренно, и компилятор проговорился: Тип ""нет"" не может быть назначен для типа ""да"". Значит, IsString<"круг"> вычислился в "да": литерал "круг" годится на место string, сработала первая ветка. А четвёртая строка прошла без единого слова — и это тоже ответ: IsString<number> действительно "нет".

Тип нельзя напечатать, но можно вытянуть из ошибки: присвойте значение, которое точно не подойдёт, — и компилятор назовёт ожидаемый тип целиком.

Слово extends сбивает с толку: в классах оно означает наследование. В условном типе вопрос другой и уже знакомый по статье про структурную типизацию — можно ли поставить значение типа T туда, где ждут U. Происхождение и имя типа роли не играют, лишние поля тоже не мешают.

type HasId<T> = T extends { id: number } ? "есть id" : "нет id";
type User = { id: number; name: string };
const user: HasId<User> = "нет id";
const anon: HasId<{ name: string }> = "нет id";
console.log(user, anon);

User ни от кого не наследуется и никакого { id: number } в глаза не видел, но подставить его туда, где ждут объект с числовым id, можно — значит, условие истинно. Ошибка на третьей строке это и подтверждает: Тип ""нет id"" не может быть назначен для типа ""есть id"". Объект с одним name проверку не прошёл, и четвёртая строка молчит: там честное "нет id".

Ветки условного типа — обычные типы, поэтому в ветку «иначе» можно вложить следующее условие. Получается цепочка, которая читается как if / else if.

// вложенные условные типы читаются сверху вниз, как цепочка if / else if
type Kind<T> = T extends string
  ? "строка"
  : T extends number
    ? "число"
    : T extends boolean
      ? "флаг"
      : "другое";
const k1: Kind<"круг"> = "строка";
const k2: Kind<42> = "число";
const k3: Kind<Date> = "другое";
const k4: Kind<true> = "другое";
console.log(k1, k2, k3, k4);

Три первых подстановки в порядке, ошибка на последней: Тип ""другое"" не может быть назначен для типа ""флаг"". Тип true до ветки «другое» не добрался — раньше сработала проверка extends boolean, ведь true годится на место boolean. А Date прошёл всю цепочку и вышел «другим»: это объект, ни под один примитив он не подходит.

Порядок веток важен так же, как порядок if / else if: сработает первое подошедшее условие, а не самое точное.

type IsString<T> = T extends string ? "да" : "нет";
const wide: IsString<any> = "может быть";
console.log(wide);

Пока в условный тип подставляли по одному типу, всё было предсказуемо. Подставим объединение — и результат перестанет совпадать с интуицией. Вот тип, который заворачивает что угодно в массив: условие T extends unknown истинно всегда, ветка «иначе» недостижима, работает только первая.

// «заверни тип в массив»: условие всегда истинно, интересна только ветка «да»
type ToArray<T> = T extends unknown ? T[] : never;
const mixed: ToArray<string | number> = [1, "два"];
console.log(mixed);

Массив с числом и строкой — самое естественное содержимое для ToArray<string | number>, но компилятор его не принял. Диагностика вложенная, из тех, что разбирались в статье про чтение ошибок, и верхняя её строка объясняет всё: Тип "(string | number)[]" не может быть назначен для типа "string[] | number[]". Ожидался не «массив строк-или-чисел», а «или массив строк, или массив чисел» — два разных типа на выбор.

Проверим догадку: если тип и правда такой, каждый из двух массивов по отдельности должен пройти.

type ToArray<T> = T extends unknown ? T[] : never;
const nums: ToArray<string | number> = [1, 2];
const words: ToArray<string | number> = ["раз", "два"];
console.log(nums, words);

Ни одной диагностики. Значит, компилятор поступил так: разложил объединение на члены, применил условие к каждому — string дал string[], number дал number[] — и собрал результаты обратно объединением. Это и называется распределением условного типа по объединению.

Разбегается не объединение само по себе: Array<string | number> остаётся одним массивом. Распределение — поведение именно условного типа.

Правило одно, и оно узкое: распределение случается, только если слева от extends стоит голый параметр типа — сам T, без обёрток, — и подставили в него объединение. Стоит записать то же объединение прямо в условии, и никакого перебора не будет.

type Check<T> = T extends string ? "да" : "нет";
type Direct = (string | number) extends string ? "да" : "нет";
const throughParam: Check<string | number> = "может быть";
const direct: Direct = "да";
console.log(throughParam, direct);

Две ошибки, и обе по делу. Третья строка: Тип ""может быть"" не может быть назначен для типа ""да" | "нет"". — через параметр условие разбежалось и вернуло оба ответа сразу. Четвёртая: Тип ""да"" не может быть назначен для типа ""нет"". — Direct оказался просто "нет", потому что объединение целиком на место string не годится: числа туда не пускают.

Отсюда и способ выключить распределение — сделать так, чтобы слева стоял не голый параметр. Обычно обе стороны заворачивают в кортеж из одного элемента.

// обе стороны в квадратных скобках: слева уже не голый T, а кортеж из одного элемента
type Boxed<T> = [T] extends [unknown] ? T[] : never;
const mixed: Boxed<string | number> = [1, "два"];
console.log(mixed);

Ошибки нет: Boxed<string | number> — это (string | number)[], ровно то, чего мы хотели с самого начала. Квадратные скобки тут не заклинание: [T] — уже не голый параметр, перебирать компилятору нечего, и он один раз проверяет кортеж против кортежа.

У правила есть следствие, на которое натыкаются все. Тип never — это объединение без единого члена, и распределять по нему нечего: ни одна ветка не выполнится ни разу, а результатом станет тот же never. Заодно это обещанное исключение из «условие T extends unknown истинно всегда»: истинность тут даже не проверяют — проверять не на чем.

type ToArray<T> = T extends unknown ? T[] : never;
type Boxed<T> = [T] extends [unknown] ? T[] : never;
const empty: ToArray<never> = [];
const boxed: Boxed<never> = [];
console.log(empty, boxed);

Третья строка: Тип "never[]" не может быть назначен для типа "never". — ToArray<never> схлопнулся в never, и присвоить ему нельзя вообще ничего, даже пустой массив. Четвёртая молчит: у Boxed распределение выключено, условие проверилось один раз и честно дало never[].

Распределение — не курьёз для собеседований. На нём стоят две утилиты стандартной библиотеки, которые пригождаются в обычном коде постоянно: вычесть из объединения лишнее и оставить только нужное. Третьей в этом ряду обычно называют NonNullable — она убирает null и undefined, — но записана она иначе, и к этому мы вернёмся.

type Method = "GET" | "POST" | "PUT" | "DELETE";
// готовые утилиты стандартной библиотеки: вычесть из объединения и оставить нужное
const mutating: Exclude<Method, "GET"> = "GET";
const safe: Extract<Method, "GET" | "HEAD"> = "POST";
const sure: NonNullable<string | null | undefined> = null;
console.log(mutating, safe, sure);

Три диагностики подряд, и каждая показывает вычисленный тип. Exclude<Method, "GET"> оставил "POST" | "PUT" | "DELETE" — из объединения вычли один член. Extract<Method, "GET" | "HEAD"> дал "GET": остаётся пересечение, а "HEAD" в Method не нашёлся и просто пропал. NonNullable убрал null и undefined — тот самый разговор из статьи про strictNullChecks, только теперь на уровне типов.

Внутри у Exclude и Extract нет ничего, кроме условного типа с распределением: каждая пишется в одну строку, и вы уже умеете такие писать. Напишем заодно и свой NonNullable — тем же приёмом.

// в каждой строке — один условный тип с распределением, больше ничего
type MyExclude<T, U> = T extends U ? never : T;
type MyNonNullable<T> = T extends null | undefined ? never : T;
type Method = "GET" | "POST" | "PUT" | "DELETE";
const mutating: MyExclude<Method, "GET" | "DELETE"> = "GET";
const sure: MyNonNullable<string | number | null> = null;
console.log(mutating, sure);

MyExclude проверяет каждый член отдельно: подошёл под U — заменяем его на never, не подошёл — оставляем как есть. Дальше срабатывает свойство never, из-за которого он и кажется странным типом: в объединении он исчезает, потому что не описывает ни одного значения. Из never | "POST" | "PUT" | never остаётся "POST" | "PUT" — это и подтвердила ошибка на пятой строке.

С MyNonNullable та же история: распределение проверяет каждый член и выкидывает пустые. Работает — а вот NonNullable из библиотеки устроен не так. До TypeScript 4.8 он был ровно такой строкой, а теперь записан без всякого условия: type NonNullable<T> = T & {};. Пересечение с {} ничего не добавляет тому, что и так не пустое, а null и undefined в него не влезают и из объединения пропадают: NonNullable<string | null | undefined> компилятор показывает просто как string. Условие и распределение тут не нужны вовсе — полезное напоминание, что одну и ту же задачу система типов часто решает двумя разными записями.

Тот же приём работает не только со строками. Если объединение состоит из объектов, Extract вытаскивает из него нужный вариант по образцу.

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "rect"; w: number; h: number };
// из объединения объектов остаётся ровно тот вариант, который подошёл под образец
const circle: Extract<Shape, { kind: "circle" }> = { kind: "circle", r: 2 };
const wrong: Extract<Shape, { kind: "circle" }> = { kind: "rect", w: 1, h: 2 };
console.log(circle.r, wrong.kind);

Образец здесь — { kind: "circle" }: под него годится только первый член объединения, второй отсеялся в never и исчез. Зато у переменной circle теперь доступно поле r, которого у прямоугольника нет: компилятор знает, что вариант остался ровно один. Шестая строка ошибается ожидаемо — Тип ""rect"" не может быть назначен для типа ""circle"".

type Res<T> = T extends string ? string : number;
function make<T>(value: T): Res<T> {
  return "текст";
}
console.log(make("раз"), make(1));