TypeScript Exclude, Extract ve NonNullable Nedir?

Exclude<T, U> bir union tipinden üye çıkarır, Extract<T, U> yalnızca eşleşen üyeleri tutar, NonNullable<T> ise null ve undefined değerlerini çıkarır. Üçü de union'ları filtreler; nesne özelliklerine dokunmazlar.

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

Her utility type gibi bunlar da yalnızca derleme zamanında vardır. Son satırı derleyici reddeder; çalışan JavaScript'in Visible tipinin ne olduğundan haberi yoktur.

Bir Bakışta Exclude, Extract ve NonNullable

Anahtar ifade "U tipine atanabilir" ifadesidir. U tam üyelerden oluşan bir liste olmak zorunda değildir; birkaç üyenin uyduğu daha geniş bir tip olabilir:

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 Üyelerini Şekle Göre Seçmek

Bir discriminated union üzerinde, kısmi bir şekille kullanılan Extract o şekle sahip varyantları çeker. Kendiniz yazmadığınız bir union'ın bir varyantını adlandırmanın olağan yolu budur:

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" } şekli yalnızca click varyantının bir üst tipidir, bu yüzden Extract onu tutar. Birkaç varyantla eşleşen bir şekil (örneğin ikisinde de varsa { x: number }) hepsini tutar.

NonNullable

NonNullable<T>, bir !== null && !== undefined kontrolünün tip sürümüdür. İsteğe bağlı bir şeyden tip türettiğinizde karşınıza çıkar:

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"] tipi { name: string } | null | undefined olur (? işareti undefined ekler) ve NonNullable ikisini de çıkarır. TypeScript 5.5'ten beri derleyici bu predicate'i kendi başına da çıkarır, yani raw.filter((s) => s != null) zaten string[] olarak tiplenir; açık s is NonNullable<typeof s> niyeti görünür tutar ve eski sürümlerde de çalışır. Tanımı type NonNullable<T> = T & {} şeklindedir: boş nesne tipi {}, null ve undefined dışındaki her değeri kabul eder, bu yüzden onunla kesiştirmek tam olarak bu ikisini çıkarır.

Nasıl Kurulurlar

Exclude ve Extract, standart kütüphanede tek satırlık conditional type'lardır:

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

T bir union olduğunda conditional type her üyeye ayrı ayrı uygulanır (dağılır) ve never üyeler sonuçtan kaybolur. Böylece Exclude<"a" | "b", "a"> önce ("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b") olur, bu da never | "b", yani "b" demektir. Dağılmayı conditional types sayfası ayrıntılı ele alır.

Exclude ile Omit, Extract ile Pick

Adlar kolayca karışır, çünkü iki çift de bir şeyi "çıkarır" ya da "tutar". Fark, üzerinde çalıştıkları şeydedir:

Exclude tipini bir nesne tipi üzerinde kullanmak yaygın bir hatadır ve sessizce başarısız olur:

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" tipine atanamaz, bu yüzden Exclude onu olduğu gibi tutar. Omit'in kendisi anahtarlara uygulanan Exclude ile kurulmuştur: Omit<T, K>, Pick<T, Exclude<keyof T, K>> tipidir. Daha fazlası için Omit sayfasına bakın.

Daha Katı Bir Exclude

Exclude tipinin ikinci parametresi her tipi kabul eder, bu yüzden bir yazım hatası hiçbir şey çıkarmaz ve hata da vermez. Bir kısıtlama eklemek, derleyicinin exclude ettiğiniz şeyin gerçekten union'da olduğunu kontrol etmesini sağlar:

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

Yazımı düzeltin, derlenir ve Strict tipi "published" | "archived" olur. Aynı yöntem Extract için ve katı bir Omit (K extends keyof T) için de çalışır.