実行できるTypeScriptドキュメント: Exclude と Extract

Q: TypeScriptの Exclude は何をしますか？

Exclude は、ユニオン型 T から U に代入できるメンバーをすべて取り除きます。Exclude は "b" | "c" です。複数のメンバーを取り除くには、U にユニオン型を渡します: Exclude 。

Q: Exclude と Extract の違いは何ですか？

正反対です。Exclude は T のメンバーのうち U に代入できないものを残し、Extract は代入できるものだけを残します。同じ T と U なら、2つの結果を合わせると T になります。

Q: Exclude と Omit の違いは何ですか？

Exclude はユニオン型に対して働き、ユニオン型のメンバーを取り除きます。Omit はオブジェクト型に対して働き、プロパティを取り除きます。Exclude は意味のあることをせず（User を返します）、Omit はそのプロパティのないオブジェクト型を返します。Omit は Exclude をもとに作られていて、keyof T からキーを除外しています。

Q: TypeScriptの NonNullable は何をしますか？

NonNullable は型から null と undefined を取り除きます: NonNullable は string です。{} は null と undefined 以外のすべての値を受け付けるので、T & {} として定義されています。

Q: 存在しないメンバーを指定しても Exclude がエラーにならないのはなぜですか？

2番目の型パラメーターに制約がないので、どんな型でも受け付け、Exclude のような打ち間違いは黙って何も取り除きません。より厳密な版 type StrictExclude = Exclude を定義すれば、U が T の一部であることをコンパイラーがチェックします。

Exclude<T, U> はユニオン型からメンバーを取り除き、Extract<T, U> は一致するメンバーだけを残し、NonNullable<T> は null と undefined を取り除きます。3つともユニオン型を絞り込むもので、オブジェクトのプロパティには触れません。

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 の一覧

型	残すもの	例	結果
`Exclude<T, U>`	`U` に代入できない `T` のメンバー	`Exclude<"a" \| "b" \| "c", "a">`	`"b" \| "c"`
`Extract<T, U>`	`U` に代入できる `T` のメンバー	`Extract<"a" \| "b" \| "c", "a" \| "z">`	`"a"`
`NonNullable<T>`	`null` と `undefined` 以外のすべて	`NonNullable<string \| null \| undefined>`	`string`

大事なのは「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 を使うと、その形を持つバリアントを取り出せます。自分で書いていないユニオン型の1つのバリアントに名前を付けるときの定番の方法です:

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" } はクリックのバリアントだけのスーパータイプなので、Extract が残すのはそれだけです。複数のバリアントに一致する形（たとえば2つのバリアントが { 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 以外のすべての値を受け付けるので、それとの交差型を取るとちょうどその2つが取り除かれます。

定義のしくみ

Exclude と Extract は、標準ライブラリでは1行の条件型です:

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<T, U>`	ユニオン型	ユニオン型のメンバー	`Exclude<"a" \| "b", "a">` → `"b"`
`Extract<T, U>`	ユニオン型	ユニオン型のメンバー	`Extract<"a" \| "b", "a">` → `"a"`
`Omit<T, K>`	オブジェクト型	プロパティ	`Omit<User, "password">`
`Pick<T, K>`	オブジェクト型	プロパティ	`Pick<User, "name">`

オブジェクト型に 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 の2番目の型パラメーターはどんな型でも受け付けるので、打ち間違えても何も取り除かれず、エラーも出ません。制約を加えれば、除外するものが本当にユニオン型に含まれているかをコンパイラーがチェックします:

// 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）にも使えます。

よくある質問

TypeScriptの Exclude は何をしますか？

Exclude<T, U> は、ユニオン型 T から U に代入できるメンバーをすべて取り除きます。Exclude<"a" | "b" | "c", "a"> は "b" | "c" です。複数のメンバーを取り除くには、U にユニオン型を渡します: Exclude<T, "a" | "b">。

Exclude と Extract の違いは何ですか？

正反対です。Exclude<T, U> は T のメンバーのうち U に代入できないものを残し、Extract<T, U> は代入できるものだけを残します。同じ T と U なら、2つの結果を合わせると T になります。

Exclude と Omit の違いは何ですか？

Exclude はユニオン型に対して働き、ユニオン型のメンバーを取り除きます。Omit はオブジェクト型に対して働き、プロパティを取り除きます。Exclude<User, "password"> は意味のあることをせず（User を返します）、Omit<User, "password"> はそのプロパティのないオブジェクト型を返します。Omit は Exclude をもとに作られていて、keyof T からキーを除外しています。

TypeScriptの NonNullable は何をしますか？

NonNullable<T> は型から null と undefined を取り除きます: NonNullable<string | null | undefined> は string です。{} は null と undefined 以外のすべての値を受け付けるので、T & {} として定義されています。

存在しないメンバーを指定しても Exclude がエラーにならないのはなぜですか？

2番目の型パラメーターに制約がないので、どんな型でも受け付け、Exclude<Status, "drafft"> のような打ち間違いは黙って何も取り除きません。より厳密な版 type StrictExclude<T, U extends T> = Exclude<T, U> を定義すれば、U が T の一部であることをコンパイラーがチェックします。