TypeScript Exclude、Extract 与 NonNullable 详解

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）。