Дистрибутивные условные типы

Правило, сформулированное точно

Почему это важно? Потому что каждый утилитный тип для работы с объединениями — Exclude, Extract, Filter — работает именно благодаря этому правилу, а каждый неверный IsNever или IsString ломается из-за него. Когда проверяемый в условии тип — это голый параметр типа (T extends ..., где T стоит сам по себе, ни во что не обёрнутый) и T инстанцирован объединением, условие распределяется: оно применяется к каждому члену объединения по отдельности, а результаты объединяются обратно.

type ToArray<T> = T extends unknown ? T[] : never;

type A = ToArray<string | number>;
//   ^? type A = string[] | number[]
//   НЕ (string | number)[]  — дистрибуция сначала разбила объединение

Компилятор переписывает ToArray<string | number> как ToArray<string> | ToArray<number> = string[] | number[]. Проверка выполняется раз на каждый член.

Отключение: оберните параметр

Дистрибуция срабатывает только для голого параметра. Оберните его в одноэлементный кортеж — и объединение проверяется как единое целое:

type IsString<T> = [T] extends [string] ? true : false;

type B = IsString<string | number>;
//   ^? type B = false   ("string | number" не присваивается string — проверено целиком)

// Без обёртки дистрибуция даёт неожиданное объединение:
type IsStringNaked<T> = T extends string ? true : false;
type C = IsStringNaked<string | number>;
//   ^? type C = boolean   (true | false — распределено: string->true, number->false)

Заметьте, C — это boolean. Это true | false — дистрибуция дала true для члена string и false для члена number, затем объединила их. Это самый частый сюрприз дистрибуции: предикат, который должен ответить «да или нет про тип целиком», вместо этого отвечает по членам и схлопывается в boolean.

never — это пустое объединение

never — это тип с нулём членов, пустое объединение. Дистрибуция условия над нулём членов даёт нуль результатов, а объединение ничего — это never:

type Wrap<T> = T extends unknown ? T[] : never;

type D = Wrap<never>;
//   ^? type D = never   (НЕ never[] — не было членов для обхода)

Это знаменитая ловушка «условие над never даёт never». Wrap<never> — это не never[]; условие вообще не выполняется, потому что распределять не над чем. Чтобы заставить вычисление, когда вы действительно хотите проверить на never, отключите дистрибуцию:

type IsNever<T> = [T] extends [never] ? true : false;

type E = IsNever<never>;
//   ^? type E = true    (обёрнуто: пустое объединение присваивается [never])

Пересборка стандартной библиотеки через дистрибуцию

Exclude и Extract — чистая дистрибуция, по три токена каждый:

type MyExclude<T, U> = T extends U ? never : T;   // выкинуть члены T, присваиваемые U
type MyExtract<T, U> = T extends U ? T : never;   // оставить члены T, присваиваемые U
type MyNonNullable<T> = T extends null | undefined ? never : T;

type F = MyExclude<"a" | "b" | "c", "a">;
//   ^? type F = "b" | "c"
//   распределено: "a"->never, "b"->"b", "c"->"c"; never выпадает из объединения

Ключевая мысль: дистрибуция отображает каждый член либо в себя, либо в never, а never исчезает при объединении (X | never = X). Это и есть весь механизм фильтрации объединения — отобразите ненужные члены в never, и они пропадут. Общий фильтр строится так же:

type FilterByKind<T, K> = T extends { kind: K } ? T : never;
type Events = { kind: "click"; x: number } | { kind: "key"; code: string };
type G = FilterByKind<Events, "click">;
//   ^? type G = { kind: "click"; x: number }