Penjelasan Exclude, Extract, dan NonNullable di TypeScript

Exclude<T, U> membuang anggota dari sebuah union type, Extract<T, U> hanya menyimpan anggota yang cocok, dan NonNullable<T> membuang null dan undefined. Ketiganya menyaring union; tidak ada yang menyentuh property objek.

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";

Seperti setiap utility type, ketiganya hanya ada saat kompilasi. Baris terakhir ditolak oleh compiler; JavaScript yang dijalankan sama sekali tidak tahu apa itu Visible.

Sekilas Exclude, Extract, dan NonNullable

"Bisa diberikan ke U" adalah frasa kuncinya. U tidak harus berupa daftar anggota yang persis; ia bisa berupa tipe yang lebih lebar yang cocok dengan beberapa anggota:

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

Memilih Anggota Union Berdasarkan Bentuk

Pada discriminated union, Extract dengan bentuk parsial mengambil varian yang punya bentuk itu. Inilah cara yang biasa untuk menamai satu varian dari union yang tidak kamu tulis sendiri:

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

Bentuk { type: "click" } adalah supertype dari varian click saja, jadi varian itulah yang disimpan Extract. Bentuk yang cocok dengan beberapa varian (misalnya { x: number } kalau ada dua varian yang memilikinya) menyimpan semuanya.

NonNullable

NonNullable<T> adalah versi tipe dari pemeriksaan !== null && !== undefined. Tipe ini muncul saat kamu menurunkan tipe dari sesuatu yang opsional:

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"] adalah { name: string } | null | undefined (tanda ? menambahkan undefined), dan NonNullable membuang keduanya. Sejak TypeScript 5.5, compiler juga menyimpulkan predicate itu sendiri, jadi raw.filter((s) => s != null) sudah bertipe string[]; s is NonNullable<typeof s> yang eksplisit membuat maksudnya tetap terlihat dan berfungsi di versi yang lebih lama. Definisinya adalah type NonNullable<T> = T & {}: object type kosong {} menerima setiap nilai kecuali null dan undefined, jadi meng-intersect dengannya membuang persis kedua nilai itu.

Cara Ketiganya Dibangun

Exclude dan Extract adalah conditional type satu baris di library standar:

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

Ketika T adalah union, conditional type diterapkan ke setiap anggota secara terpisah (terdistribusi), dan anggota never menghilang dari hasilnya. Jadi Exclude<"a" | "b", "a"> menjadi ("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b"), yaitu never | "b", yaitu "b". Halaman conditional type membahas distribusi secara mendetail.

Exclude vs Omit, Extract vs Pick

Namanya mudah tertukar karena kedua pasangan sama-sama "membuang" atau "menyimpan" sesuatu. Perbedaannya ada pada apa yang dikerjakan:

Memakai Exclude pada object type adalah kekeliruan yang umum, dan kegagalannya tidak terlihat:

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 tidak bisa diberikan ke "password", jadi Exclude menyimpannya utuh. Omit sendiri dibangun dari Exclude yang diterapkan pada key: Omit<T, K> adalah Pick<T, Exclude<keyof T, K>>. Lihat Omit untuk penjelasan lebih lanjut.

Exclude yang Lebih Ketat

Parameter kedua Exclude menerima tipe apa pun, jadi salah ketik tidak membuang apa pun dan tidak memunculkan error. Menambahkan constraint membuat compiler memeriksa bahwa yang kamu exclude benar-benar ada di union itu:

// 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'.

Perbaiki ejaannya dan kodenya bisa dikompilasi, dengan Strict sama dengan "published" | "archived". Trik yang sama berlaku untuk Extract dan untuk Omit yang ketat (K extends keyof T).