TypeScript Exclude, Extract und NonNullable erklärt

Exclude<T, U> entfernt Member aus einem Union-Typ, Extract<T, U> behält nur die passenden Member, und NonNullable<T> entfernt null und undefined. Alle drei filtern Unions; Objekteigenschaften rühren sie nicht an.

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

Wie jeder Utility Type existieren sie nur beim Kompilieren. Die letzte Zeile lehnt der Compiler ab; das JavaScript, das läuft, hat keine Ahnung, was Visible ist.

Exclude, Extract und NonNullable im Überblick

„U zuweisbar“ ist die entscheidende Formulierung. U muss keine Liste exakter Member sein; es kann ein weiterer Typ sein, zu dem mehrere Member passen:

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-Member nach ihrer Form auswählen

Bei einer Discriminated Union holt Extract mit einer Teilform die Varianten heraus, die sie haben. So benennt man üblicherweise eine Variante einer Union, die man nicht selbst geschrieben hat:

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

Die Form { type: "click" } ist nur ein Obertyp der Click-Variante, also behält Extract genau diese. Eine Form, die zu mehreren Varianten passt (etwa { x: number }, wenn zwei es hätten), behält alle.

NonNullable

NonNullable<T> ist die Typversion einer Prüfung !== null && !== undefined. Es taucht auf, wenn du einen Typ aus etwas Optionalem ableitest:

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"] ist { name: string } | null | undefined (das ? fügt undefined hinzu), und NonNullable entfernt beides. Seit TypeScript 5.5 leitet der Compiler dieses Predicate auch selbst ab, also ist raw.filter((s) => s != null) bereits als string[] typisiert; das ausdrückliche s is NonNullable<typeof s> hält die Absicht sichtbar und funktioniert in älteren Versionen. Die Definition ist type NonNullable<T> = T & {}: Der leere Objekttyp {} akzeptiert jeden Wert außer null und undefined, die Schnittmenge damit entfernt also genau diese.

Wie sie gebaut sind

Exclude und Extract sind einzeilige Conditional Types in der Standardbibliothek:

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

Ist T eine Union, wird ein Conditional Type auf jeden Member einzeln angewendet (er distribuiert), und Member mit never verschwinden aus dem Ergebnis. Also wird Exclude<"a" | "b", "a"> zu ("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b"), also never | "b", also "b". Die Seite zu Conditional Types behandelt die Distribution im Detail.

Exclude vs Omit, Extract vs Pick

Die Namen verwechselt man leicht, weil beide Paare etwas „entfernen“ oder „behalten“. Der Unterschied ist, worauf sie arbeiten:

Exclude auf einen Objekttyp anzuwenden ist ein häufiger Ausrutscher, und er scheitert still:

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 ist "password" nicht zuweisbar, also behält Exclude es vollständig. Omit selbst ist aus Exclude auf den Schlüsseln gebaut: Omit<T, K> ist Pick<T, Exclude<keyof T, K>>. Mehr dazu unter Omit.

Ein strengeres Exclude

Der zweite Parameter von Exclude akzeptiert jeden Typ, ein Tippfehler entfernt also nichts und löst keinen Fehler aus. Ein Constraint lässt den Compiler prüfen, dass das Ausgeschlossene wirklich in der Union liegt:

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

Korrigiere die Schreibweise, dann kompiliert es, und Strict ist gleich "published" | "archived". Derselbe Trick funktioniert für Extract und für ein strenges Omit (K extends keyof T).