Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Exhaustiveness checking in TypeScript

Reference for exhaustiveness checking in TypeScript: the never trick, assertNever helpers, switch return checks, satisfies never and noImplicitReturns.

Exhaustiveness checking means making the compiler prove that you handled every member of a union. After all cases are narrowed away, the value that remains has the type never. If you assign that value to something of type never, the code compiles only when no case is missing. Add a new variant later and every unfinished switch turns into a compile error.

This is one of the most valuable habits when working with discriminated unions and literal unions, because it turns "I forgot a case" from a run-time bug into a build failure.

TypeScript
function assertNever(x: never): never {
  throw new Error(`Unexpected: ${JSON.stringify(x)}`);
}

Try it

TypeScript The assertNever pattern

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript A missing case is a compile error

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Without a default: noImplicitReturns style

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
const _exhaustive: never = value;
function assertNever(x: never): never { throw new Error("unreachable"); }
default: return assertNever(value);
Technique How it works
Assign to never const x: never = value; errors if value can still be anything.
assertNever(x) A function taking never fails to compile when called with a non-never argument, and throws at run time as a safety net.
No default If every case returns, the compiler knows the end is unreachable. With strict, a missing case reports TS2366 ("Function lacks ending return statement and return type does not include 'undefined'.").
satisfies never value satisfies never checks the same thing as an expression.

Edge cases:

  • Exhaustiveness works with literal unions, enums, discriminated unions and boolean (true | false).
  • The error from a missing case points at the assignment and names the leftover type, for example "Type '"yellow"' is not assignable to type 'never'".

Usage notes

  • Keep the safety net at run time. TypeScript types disappear after compilation, and data from outside (JSON, an old client) can hold values the type does not know. A throwing assertNever surfaces these early.
  • Statements versus expressions. switch in a function with a return type is already checked. The never trick helps most in functions that return void or build objects.
  • default hides new cases. A default that does something real silently accepts new variants. Prefer listing cases explicitly and reserve default for assertNever.
  • noFallthroughCasesInSwitch is a separate option about missing break. It does not check coverage.
  • Enums. Union enums narrow like literal unions. const enum and numeric enums with computed members do not narrow as precisely.
  • Generic code. Inside a generic function, a value of type T is not narrowed to never by checks on its parts; narrow a local copy of the concrete type instead.