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.
function assertNever(x: never): never { throw new Error(`Unexpected: ${JSON.stringify(x)}`); }
Try it
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.
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.
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
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
assertNeversurfaces these early. - Statements versus expressions.
switchin a function with a return type is already checked. Thenevertrick helps most in functions that returnvoidor build objects. defaulthides new cases. Adefaultthat does something real silently accepts new variants. Prefer listing cases explicitly and reservedefaultforassertNever.noFallthroughCasesInSwitchis a separate option about missingbreak. It does not check coverage.- Enums. Union enums narrow like literal unions.
const enumand numeric enums with computed members do not narrow as precisely. - Generic code. Inside a generic function, a value of type
Tis not narrowed toneverby checks on its parts; narrow a local copy of the concrete type instead.