Exclude, Extract, and NonNullable

Exclude, Extract, and NonNullable for filtering unions, including distributive conditionals and the compiled definition of NonNullable.

テーマページの本文は現在英語です。

Exclude, Extract, and NonNullable operate on unions, not on the keys of an object (that is Omit or Pick). They are distributive conditional types: the check is applied to each member of a union and the results are collected.

NonNullable is documented as excluding null and undefined. Since TypeScript 4.8 its definition is T & {}, which removes null and undefined from a union such as string | null | undefined. These helpers still do no runtime checking.

Examples were checked with TypeScript 5.9.3 using tsc --strict. See the TypeScript handbook for the complete utility-type catalog.

TypeScript reference overview →

API index

APISummary
Exclude, Extract, NonNullableFilter a union by assignability, or remove null and undefined. These are type-level operations; they do not inspect a runtime value.

Exclude, Extract, and NonNullable

Exclude<T, U> keeps the members of T that are not assignable to U. Extract<T, U> keeps the members that are assignable to U. On a discriminated union, Extract<Result, { kind: "ok" }> keeps the success variant and its value field.

A conditional type written as T extends U ? X : Y distributes over a bare type parameter T when T is a union. That is why Exclude<"a" | "b" | null, null> becomes "a" | "b", rather than never or the whole union.

Exclude, Extract, NonNullable

type Exclude<T, U> = T extends U ? never : T;
type Extract<T, U> = T extends U ? T : never;
type NonNullable<T> = T & {};

Filter a union by assignability, or remove null and undefined. These are type-level operations; they do not inspect a runtime value.

Type parameterDescription
TUsually a union type to filter. For Extract with a discriminated union, T is the whole union and U is a pattern such as { kind: "ok" }.
UThe members to drop (Exclude) or keep (Extract).

Produces: A union of the remaining members, or never if none remain. NonNullable<string | null | undefined> is string.

Type errors

  • type error — Assigning an excluded member, such as null to Exclude<Status, null | undefined>, is a type error. Extract rejects members that were not kept.
  • The signatures are from TypeScript 5.9.3. Exclude and Extract arrived in 2.8. NonNullable was redefined as T & {} in 4.8.
  • Extract on a discriminated union is a type-level counterpart to the runtime kind check in the overview result-type recipe. The type still does not throw if a runtime object has the wrong shape.
typescript
type Status = "ready" | "pending" | "done" | null | undefined;
type Present = Exclude<Status, null | undefined>;
type Finished = Extract<Status, "ready" | "done" | null>;
type Value = NonNullable<Status>;

const present: Present = "ready";
// @ts-expect-error null was excluded
const absent: Present = null;

const finished: Finished = "done";
// @ts-expect-error pending is not in the extracted union
const pending: Finished = "pending";

const value: Value = "ready";
// @ts-expect-error NonNullable removes null and undefined
const missing: Value = undefined;

type Result =
  | { kind: "ok"; value: number }
  | { kind: "error"; message: string };
type Ok = Extract<Result, { kind: "ok" }>;
const ok: Ok = { kind: "ok", value: 12 };
console.log(present, finished, value, ok.value);

Expected output

ready done ready 12

Related: Use a result type for success and failure, Official Exclude, Official Extract, Official NonNullable

Official documentation →