Exclude, Extract ו-NonNullable ב-TypeScript: הסבר

Exclude<T, U> מסיר איברים מ-union type, Extract<T, U> משאיר רק את האיברים שמתאימים, ו-NonNullable<T> מסיר null ו-undefined. שלושתם מסננים unions; הם לא נוגעים במאפיינים של אובייקטים.

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

כמו כל utility type, הם קיימים רק בזמן קומפילציה. השורה האחרונה נדחית על ידי הקומפיילר; ל-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

בחירת איברי union לפי מבנה

ב-discriminated union, Extract עם מבנה חלקי שולף את הווריאנטים שיש להם אותו. זו הדרך הרגילה לתת שם לווריאנט אחד של union שלא כתבתם בעצמכם:

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" } הוא supertype רק של הווריאנט של 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 הקומפיילר גם מסיק את ה-predicate הזה בעצמו, ולכן ל-raw.filter((s) => s != null) כבר יש את הטיפוס string[]; ה-s is NonNullable<typeof s> המפורש משאיר את הכוונה גלויה ועובד בגרסאות ישנות יותר. ההגדרה שלו היא type NonNullable<T> = T & {}: טיפוס האובייקט הריק {} מקבל כל ערך חוץ מ-null ו-undefined, ולכן חיתוך איתו מסיר בדיוק אותם.

איך הם בנויים

Exclude ו-Extract הם conditional types של שורה אחת בספרייה הסטנדרטית:

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

כש-T הוא union, conditional type מופעל על כל איבר בנפרד (הוא מתפזר), ואיברי never נעלמים מהתוצאה. לכן Exclude<"a" | "b", "a"> הופך ל-("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b"), שהוא never | "b", שהוא "b". העמוד על conditional types מסביר את הפיזור לעומק.

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 מקבל כל טיפוס, ולכן שגיאת כתיב לא מסירה כלום ולא מעלה שגיאה. הוספת אילוץ גורמת לקומפיילר לבדוק שמה שאתם מסירים באמת נמצא ב-union:

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