Exclude, Extract et NonNullable en TypeScript expliqués

Exclude<T, U> retire des membres d'un type union, Extract<T, U> ne garde que les membres qui correspondent, et NonNullable<T> retire null et undefined. Tous trois filtrent des unions ; ils ne touchent pas aux propriétés des objets.

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

Comme tous les utility types, ils n'existent qu'à la compilation. La dernière ligne est refusée par le compilateur ; le JavaScript exécuté ignore tout de Visible.

Exclude, Extract et NonNullable en un coup d'œil

« Affectable à U » est l'expression clé. U n'a pas besoin d'être une liste de membres exacts ; ce peut être un type plus large auquel plusieurs membres correspondent :

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

Sélectionner des membres d'une union par leur forme

Sur une union discriminée, Extract avec une forme partielle récupère les variantes qui ont cette forme. C'est la façon habituelle de nommer une variante d'une union que vous n'avez pas écrite vous-même :

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

La forme { type: "click" } est un supertype de la seule variante click, c'est donc celle que Extract garde. Une forme qui correspond à plusieurs variantes (par exemple { x: number } si deux d'entre elles l'avaient) les garde toutes.

NonNullable

NonNullable<T> est la version type d'une vérification !== null && !== undefined. On le rencontre quand on dérive un type de quelque chose d'optionnel :

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"] vaut { name: string } | null | undefined (le ? ajoute undefined), et NonNullable retire les deux. Depuis TypeScript 5.5, le compilateur infère aussi ce prédicat tout seul, donc raw.filter((s) => s != null) est déjà typé string[] ; le s is NonNullable<typeof s> explicite rend l'intention visible et fonctionne dans les versions plus anciennes. Sa définition est type NonNullable<T> = T & {} : le type objet vide {} accepte toutes les valeurs sauf null et undefined, donc l'intersection avec lui retire exactement ces deux-là.

Comment ils sont construits

Exclude et Extract sont des types conditionnels d'une ligne dans la bibliothèque standard :

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

Quand T est une union, un type conditionnel est appliqué à chaque membre séparément (il se distribue), et les membres never disparaissent du résultat. Ainsi Exclude<"a" | "b", "a"> devient ("a" extends "a" ? never : "a") | ("b" extends "a" ? never : "b"), soit never | "b", soit "b". La page sur les types conditionnels détaille la distribution.

Exclude vs Omit, Extract vs Pick

Les noms se confondent facilement, car les deux paires « retirent » ou « gardent » quelque chose. La différence tient à ce sur quoi ils agissent :

Utiliser Exclude sur un type objet est une erreur courante, et elle passe inaperçue :

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 n'est pas affectable à "password", donc Exclude le garde en entier. Omit lui-même est construit à partir de Exclude appliqué aux clés : Omit<T, K> vaut Pick<T, Exclude<keyof T, K>>. Voir Omit pour plus de détails.

Un Exclude plus strict

Le second paramètre de Exclude accepte n'importe quel type, donc une faute de frappe ne retire rien et ne lève aucune erreur. Ajouter une contrainte oblige le compilateur à vérifier que ce que vous excluez fait vraiment partie de l'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'.

Corrigez l'orthographe et le code compile, avec Strict égal à "published" | "archived". La même astuce fonctionne pour Extract et pour un Omit strict (K extends keyof T).