Exclude وExtract وNonNullable في TypeScript: شرح وأمثلة

يحذف Exclude<T, U> أعضاء من نوع union، ويُبقي 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";

مثل كل أنواع الأدوات، هذه موجودة وقت الترجمة فقط. يرفض المترجم السطر الأخير؛ أما 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، فالـ intersection معه يحذفهما بالضبط.

كيف تُبنى

Exclude وExtract نوعان شرطيان من سطر واحد في المكتبة القياسية:

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

عندما يكون T من نوع union، يُطبَّق النوع الشرطي على كل عضو منفصلًا (يتوزع)، وتختفي الأعضاء 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 أي نوع، فالخطأ الإملائي لا يحذف شيئًا ولا يثير أي خطأ. إضافة قيد تجعل المترجم يتحقق من أن ما تستبعده موجود فعلًا في 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).