Exclude, Extract и NonNullable в TypeScript: объяснение

Exclude<T, U> удаляет члены из типа объединения, Extract<T, U> оставляет только подходящие члены, а NonNullable<T> удаляет null и undefined. Все три фильтруют объединения; свойства объектов они не трогают.

type Status = "draft" | "review" | "published" | "archived";

type Visible = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Editable = Extract<Status, "draft" | "review">;   // "draft" | "review"

const shown: Visible[] = ["review", "published"];
const editing: Editable = "draft";
console.log(shown, editing); // [ 'review', 'published' ] draft

// @ts-expect-error: Type '"draft"' is not assignable to type 'Visible'.
const bad: Visible = "draft";

Как и любые служебные типы, они существуют только при компиляции. Последнюю строку отвергает компилятор; выполняющийся JavaScript понятия не имеет, что такое Visible.

Exclude, Extract и NonNullable коротко

Ключевые слова здесь «присваиваемые в U». U не обязан быть списком точных членов; это может быть более широкий тип, под который подходят несколько членов:

type Input = string | number | boolean | (() => void) | null;

type Primitive = Exclude<Input, (() => void) | null>; // string | number | boolean
type Callable = Extract<Input, (...args: never[]) => unknown>; // () => void
type Present = NonNullable<Input>; // string | number | boolean | (() => void)

const values: Primitive[] = ["a", 1, true];
const run: Callable = () => console.log("called");
const p: Present = 42;

run();
console.log(values, p); // [ 'a', 1, true ] 42

Выбор членов объединения по структуре

Для размеченного объединения Extract с частичной структурой вытаскивает варианты, у которых она есть. Это обычный способ назвать один вариант объединения, которое писали не вы:

type AppEvent =
    | { type: "click"; x: number; y: number }
    | { type: "key"; key: string }
    | { type: "scroll"; delta: number };

type ClickEvent = Extract<AppEvent, { type: "click" }>;
type NonClickEvent = Exclude<AppEvent, { type: "click" }>;

function handleClick(e: ClickEvent): string {
    return `click at ${e.x},${e.y}`; // x and y are available
}

function describe(e: NonClickEvent): string {
    return e.type === "key" ? `key ${e.key}` : `scroll ${e.delta}`;
}

console.log(handleClick({ type: "click", x: 10, y: 20 })); // click at 10,20
console.log(describe({ type: "key", key: "Enter" }));      // key Enter

Структура { type: "click" } является надтипом только варианта click, поэтому Extract оставляет именно его. Структура, подходящая под несколько вариантов (скажем, { x: number }, если бы она была у двух), оставляет их все.

NonNullable

NonNullable<T> это версия проверки !== null && !== undefined для типов. Он появляется, когда тип выводится из чего-то необязательного:

type User = { name: string; manager?: { name: string } | null };

type Manager = NonNullable<User["manager"]>; // { name: string }

function managerName(m: Manager): string {
    return m.name; // no null check needed
}

const u: User = { name: "Ada", manager: { name: "Grace" } };
if (u.manager) {
    console.log(managerName(u.manager)); // Grace
}

// Filtering null and undefined out of an array, with a matching type:
const raw: Array<string | null | undefined> = ["a", null, "b", undefined];
const clean = raw.filter((s): s is NonNullable<typeof s> => s != null);
console.log(clean); // [ 'a', 'b' ]

User["manager"] это { name: string } | null | undefined (? добавляет undefined), а NonNullable убирает оба. Начиная с TypeScript 5.5 компилятор выводит этот предикат и сам, так что raw.filter((s) => s != null) уже имеет тип string[]; явный s is NonNullable<typeof s> делает намерение видимым и работает в более старых версиях. Его определение type NonNullable<T> = T & {}: пустой объектный тип {} принимает любое значение, кроме null и undefined, поэтому пересечение с ним убирает ровно их.

Как они построены

Exclude и Extract это однострочные условные типы в стандартной библиотеке:

type Exclude<T, U> = T extends U ? never : T;
type Extract<T, U> = T extends U ? T : never;

Когда T это объединение, условный тип применяется к каждому члену отдельно (распределяется), а члены never исчезают из результата. Поэтому Exclude<"a" | "b", "a"> превращается в ("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b"), то есть в never | "b", то есть в "b". Распределение подробно разобрано на странице условные типы.

Exclude и Omit, Extract и Pick

Названия легко перепутать, потому что обе пары что-то «убирают» или «оставляют». Разница в том, с чем они работают:

Использовать Exclude для объектного типа это частая оплошность, и она проходит молча:

type Account = { id: number; email: string; password: string };

type Wrong = Exclude<Account, "password">; // still Account: not a union of "password"
type Right = Omit<Account, "password">;    // { id: number; email: string }

const safe: Right = { id: 1, email: "ada@example.com" };
const oops: Wrong = { id: 1, email: "ada@example.com", password: "hunter2" };
console.log(Object.keys(safe), Object.keys(oops));
// [ 'id', 'email' ] [ 'id', 'email', 'password' ]

Account не присваивается в "password", поэтому Exclude оставляет его целиком. Сам Omit построен из Exclude, применённого к ключам: Omit<T, K> это Pick<T, Exclude<keyof T, K>>. Подробнее в разделе Omit.

Более строгий Exclude

Второй параметр Exclude принимает любой тип, поэтому опечатка ничего не удаляет и не вызывает ошибки. Ограничение заставляет компилятор проверять, что исключаемое действительно входит в объединение:

// This does not compile: "drafft" is not a Status.
type Status = "draft" | "published" | "archived";

type StrictExclude<T, U extends T> = Exclude<T, U>;

type Loose = Exclude<Status, "drafft">;        // silently Status, unchanged
type Strict = StrictExclude<Status, "drafft">; // error

const s: Strict = "published";
console.log(s);

index.ts(7,37): error TS2344: Type '"drafft"' does not satisfy the constraint 'Status'.

Исправьте написание, и код компилируется, а Strict равен "published" | "archived". Тот же приём работает для Extract и для строгого Omit (K extends keyof T).