TypeScript 17 🔷 Exhaustiveness Checking and never - KandZ

The never type is the empty type — a type with no values. Nothing is assignable to it, and it’s assignable to everything. That sounds useless until you realize what it enables: exhaustiveness checking. When you handle every branch of a union, TypeScript narrows the remaining type to never — and if you didn’t handle every branch, the remaining type is whatever you missed. By assigning that remainder to a never variable, you force the compiler to prove you handled everything. It’s the compiler as a checklist.

Key point: never means “no possible value.” After a switch covers all branches of a union, the remaining type is never. If a branch is missing, the remaining type is the missing branch — not never — and assigning it to a never variable fails. That failure is the exhaustiveness check. assertNever wraps this into a one-line helper.

What `never` is

never is the bottom type — the subtype of every type. It has no instances. No value is a never.

let x: never;

x = 1;          // ❌
x = 'a';        // ❌
x = null;       // ❌
x = undefined;  // ❌
// Nothing can be assigned to `never`.

Two things make never useful:

Assignable to everything — never can be assigned to any type
Nothing assignable to it — no value qualifies as never

Where never appears:

Function return types — a function that never returns
Exhaustiveness checks — the leftover after all cases
Impossible type combinations — string & number is never
After infinite loops — the code below is unreachable

function fail(message: string): never {
  throw new Error(message);
}

fail never returns — it always throws. Its return type is never.

Why an empty type exists: Type theory needs a bottom — a type that’s a subtype of every other. It represents “impossible” and “unreachable.” In TypeScript, that bottom is never, and it’s the foundation for exhaustiveness checking, unreachable-code analysis, and error types like Result.

`never` in function returns

A function returning never never completes — it throws or loops forever.

function fail(msg: string): never {
  throw new Error(msg);
}

function infinite(): never {
  while (true) {}
}

Why this matters: A function that returns never is compatible with every signature. A callback that must return string can be given a never-returning function — the compiler knows it never returns, so no return value is needed.

const parse: (s: string) => number = fail;  // ✅ — never is assignable to number

In practice, never return types mark functions that can’t complete normally.

Unreachable code analysis:

function f(x: string | number): string {
  if (typeof x === 'string') return x;
  if (typeof x === 'number') return `${x}`;

  // After both branches, x is `never` — nothing left
  const _exhaustive: never = x;
  return _exhaustive;
}

After handling both branches, x is never. That’s the compiler’s proof that every case is covered.

Why never return types matter: A function that throws is different from one that returns. When TypeScript knows a function never returns, it can eliminate code that follows a call, understand unreachable branches, and accept the function where a stricter signature is expected. It’s a small, precise annotation that makes control flow analysis sharper.

Exhaustiveness — the core idea

Take a discriminated union, switch on the discriminant, and check that the remaining type is never.

type Status = 'idle' | 'loading' | 'ready' | 'error';

function message(s: Status): string {
  switch (s) {
    case 'idle': return 'Waiting';
    case 'loading': return 'Loading...';
    case 'ready': return 'Ready';
    case 'error': return 'Failed';
  }
}

After all four cases, TypeScript knows s can’t be anything else. The function always returns — every branch is covered. This compiles cleanly.

Now remove one case:

function message(s: Status): string {
  switch (s) {
    case 'idle': return 'Waiting';
    case 'loading': return 'Loading...';
    case 'ready': return 'Ready';
    // ❌ 'error' not handled
  }
  // TypeScript: not all code paths return a value
}

TypeScript catches the missing case. Without a default or a final return, the function’s return type is violated.

The default case makes the check explicit:

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

function message(s: Status): string {
  switch (s) {
    case 'idle': return 'Waiting';
    case 'loading': return 'Loading...';
    case 'ready': return 'Ready';
    case 'error': return 'Failed';
    default: return assertNever(s);
  }
}

In the default branch, s is never — every case is handled. If you add a new status and forget to update the switch, s isn’t never in default, and assertNever(s) fails to compile. That failure is the check.

Why the default is better than relying on the return-type check: It gives a precise error message and catches missing cases even when the function doesn’t need to return a value.

Why exhaustiveness matters: Every union has a fixed set of branches. When you add one, every consumer must handle it. Without exhaustiveness checking, missed cases become silent bugs — a missing handler, a broken state. With it, the compiler forces you to update every switch. That’s the difference between hoping you updated everything and knowing it.

The `assertNever` helper

assertNever is a one-line function that turns exhaustiveness into a compile-time check.

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

What it does:

Accepts only a never
If the argument isn’t never, the call fails to compile
If the argument is never, the function throws at runtime — but it should never be reached

How to use it:

type Event =
  | { kind: 'click'; x: number; y: number }
  | { kind: 'keydown'; key: string }
  | { kind: 'scroll'; offset: number };

function handle(e: Event): void {
  switch (e.kind) {
    case 'click': use(e.x, e.y); break;
    case 'keydown': use(e.key); break;
    case 'scroll': use(e.offset); break;
    default: return assertNever(e);
  }
}

Adding a new kind:

type Event =
  | { kind: 'click'; x: number; y: number }
  | { kind: 'keydown'; key: string }
  | { kind: 'scroll'; offset: number }
  | { kind: 'hover'; target: string };

Now handle fails to compile — e in the default branch is { kind: 'hover'; target: string }, not never. You must add a case for hover.

Variants of assertNever:

// Minimal
function assertNever(x: never): never {
  throw new Error(`Unexpected: ${x}`);
}

// With JSON for better debug
function assertNever(x: never): never {
  throw new Error(`Unhandled: ${JSON.stringify(x)}`);
}

// Inline (no helper)
default: {
  const _: never = e;
  throw new Error('Unreachable');
}

The inline version does the same thing: assigns e to a never variable. If e isn’t never, the assignment fails.

Why a named helper: Reusable, self-documenting, and gives a clear runtime error if somehow reached. The name assertNever reads as “this should be impossible.”

Why assertNever is idiomatic: It combines a compile-time check (the argument must be never) with a runtime safeguard (it throws if reached). If the union is fully handled, the branch is unreachable — the throw never fires. If somehow the code reaches it due to a bug or a missing case that slipped through, it throws with a useful message. Best of both worlds.

Exhaustiveness patterns

Several patterns enforce exhaustiveness. Pick the one that fits.

Pattern 1 — assertNever in default:

switch (value.kind) {
  case 'a': return handleA(value);
  case 'b': return handleB(value);
  default: return assertNever(value);
}

Most common. Precise errors.

Pattern 2 — inline never assignment:

switch (value.kind) {
  case 'a': return handleA(value);
  case 'b': return handleB(value);
  default: {
    const _exhaustive: never = value;
    throw new Error(`Unhandled: ${JSON.stringify(value)}`);
  }
}

No helper needed. The _exhaustive variable is never used — it exists only for the type check.

Pattern 3 — exhaustive if chain:

function handle(x: 'a' | 'b' | 'c'): string {
  if (x === 'a') return 'A';
  if (x === 'b') return 'B';
  if (x === 'c') return 'C';
  return assertNever(x);  // x is never here
}

Works when the conditions eliminate all branches. Less common than switch.

Pattern 4 — function with never return:

function handle(e: Event): string {
  switch (e.kind) {
    case 'a': return 'a';
    case 'b': return 'b';
  }
  // ❌ missing return for the default — but if all cases return,
  // TypeScript sees the function always returns and is happy.
}

If every branch returns and none fall through, no default is needed — the function’s return type is satisfied.

Pattern 5 — mapped type exhaustiveness:

type Handlers = {
  [K in Event['kind']]: (e: Extract<Event, { kind: K }>) => void;
};

const handlers: Handlers = {
  click: e => use(e.x, e.y),
  keydown: e => use(e.key),
  scroll: e => use(e.offset)
  // ❌ missing key → compile error
};

A mapped type over the discriminant forces an entry for each kind. This is the most robust pattern for dispatch tables.

Which pattern to use:

Situation	Pattern
Switch over discriminated union	`assertNever` in default
No helper import	inline `never` assignment
Simple literal union	if chain + `assertNever`
Every branch returns	no default needed
Dispatch table	mapped type over discriminant

Why multiple patterns: Different situations favor different shapes. A switch with assertNever is standard. A dispatch table using a mapped type is more concise for handlers. Pick the one that reads clearest for the code you’re writing.

`never` and unreachable code

never also marks code that can’t be reached.

function f(x: 'a' | 'b'): string {
  if (x === 'a') return 'A';
  if (x === 'b') return 'B';

  // x is never here — this is unreachable
  return x;
}

TypeScript narrows x to never after both branches. The final return x returns a never — which is assignable to string but never actually executes.

Unreachable code detection:

function g(): void {
  return;
  console.log('never runs');  // ❌ unreachable
}

TypeScript flags unreachable code after return, throw, or an infinite loop.

never after throw:

function h(x: string): string {
  if (!x) throw new Error('empty');
  // x is string here — `throw` returns never, so the branch doesn't continue
  return x;
}

throw returns never, so the if branch terminates. The code after is reachable with x narrowed.

Infinite loop:

function loop(): never {
  while (true) {}
  console.log('never runs');  // ❌
}

The loop never exits, so the code after is unreachable, and the function returns never.

Why unreachable-code detection matters: Dead code hides bugs and confusion. If TypeScript can prove a branch is unreachable, the compiler flags it. That’s especially useful after refactors — code that used to be reachable but no longer is gets caught.

`never` in types

never isn’t only for function returns. It appears in type-level operations too.

Empty intersections:

type Impossible = string & number;  // never

A value can’t be both a string and a number — the intersection is empty.

never in unions:

type A = string | never;  // string

never is the identity for union — adding it changes nothing.

never in conditional types:

type IsString<T> = T extends string ? true : false;

type A = IsString<string>;  // true
type B = IsString<number>;  // false

// For never:
type C = IsString<never>;   // never (special case — never distributes oddly)

never distributes through conditional types in a special way — it produces never. This is a subtle behavior that catches people out.

Filtering with never:

type NonNullish<T> = T extends null | undefined ? never : T;

type A = NonNullish<string | null>;  // string
type B = NonNullish<number | undefined>;  // number

Removing a case from a union by mapping it to never.

never in mapped types:

type OptionalKeys<T> = {
  [K in keyof T]: T[K] extends undefined ? never : K;
}[keyof T];

Extracting keys whose values include undefined.

Why never appears in types: It’s the identity for union, the absorbing element for intersection, and the “filter this out” marker in conditional types. It’s TypeScript’s way of saying “no value” at every level — values, functions, and types.

Why never distribution matters: Conditional types distribute over unions. When the input is never — the empty union — the distribution produces never. This is often a source of subtle bugs in advanced type code. Guard against it with [T] extends [never] when needed.

Exhaustiveness across functions

Exhaustiveness works inside a single function scope. Across function boundaries, you need predicates or a shared helper.

Inside one function:

function handle(e: Event): void {
  switch (e.kind) {
    case 'a': break;
    case 'b': break;
    default: assertNever(e);
  }
}

Narrowing is tracked in the same scope.

Across functions with a shared handler map:

const handlers: {
  [K in Event['kind']]: (e: Extract<Event, { kind: K }>) => void;
} = {
  click: e => use(e.x, e.y),
  keydown: e => use(e.key),
  scroll: e => use(e.offset)
};

A mapped type forces every key. Missing one is a compile error at the map’s declaration, not at the call site.

Inside a callback:

events.forEach(e => {
  switch (e.kind) {
    case 'a': break;
    case 'b': break;
    default: assertNever(e);
  }
});

Narrowing works inside the callback because it’s the same switch statement.

In a reducer:

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'ADD': return add(state, action.item);
    case 'REMOVE': return remove(state, action.id);
    case 'CLEAR': return initial;
    default: return assertNever(action);
  }
}

Reducers are the classic example — every action type must be handled.

Why function boundaries matter: Narrowing is scope-local. Inside a callback or a separate function, the compiler can’t carry over what it proved elsewhere. Exhaustiveness via assertNever works because the switch and the check are in the same scope. For shared dispatch, use a mapped-type handler map to enforce completeness at the declaration.

A full example

A state machine with exhaustive transitions.

// ============================================
// TYPES
// ============================================

type State =
  | { status: 'idle' }
  | { status: 'loading'; startedAt: Date }
  | { status: 'success'; data: string }
  | { status: 'error'; message: string; retryCount: number };

type Event =
  | { kind: 'START' }
  | { kind: 'RESOLVE'; data: string }
  | { kind: 'REJECT'; message: string }
  | { kind: 'RESET' };

// ============================================
// ASSERT NEVER
// ============================================

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

// ============================================
// TRANSITION
// ============================================

function transition(state: State, event: Event): State {
  switch (state.status) {
    case 'idle':
      if (event.kind === 'START') {
        return { status: 'loading', startedAt: new Date() };
      }
      return state;

    case 'loading':
      if (event.kind === 'RESOLVE') {
        return { status: 'success', data: event.data };
      }
      if (event.kind === 'REJECT') {
        return { status: 'error', message: event.message, retryCount: 0 };
      }
      return state;

    case 'success':
      if (event.kind === 'RESET') return { status: 'idle' };
      return state;

    case 'error':
      if (event.kind === 'RESET') return { status: 'idle' };
      if (event.kind === 'START') {
        return { status: 'loading', startedAt: new Date() };
      }
      return state;

    default:
      return assertNever(state);
  }
}

// ============================================
// DESCRIBE
// ============================================

function describe(state: State): string {
  switch (state.status) {
    case 'idle': return 'Ready';
    case 'loading': return `Loading since ${state.startedAt.toISOString()}`;
    case 'success': return `Loaded: ${state.data}`;
    case 'error': return `Error: ${state.message} (retries: ${state.retryCount})`;
    default: return assertNever(state);
  }
}

// ============================================
// USAGE
// ============================================

let state: State = { status: 'idle' };
console.log(describe(state));

state = transition(state, { kind: 'START' });
console.log(describe(state));

state = transition(state, { kind: 'RESOLVE', data: 'hello' });
console.log(describe(state));

state = transition(state, { kind: 'RESET' });
console.log(describe(state));

Every transition and description is exhaustively handled. Adding a new state to the union triggers compile errors in both functions.

What this shows:

Two exhaustive functions over the same union
Nested narrowing — status first, then event kind
assertNever in default branches
TypeScript catches missing cases

Why this pattern matters: State machines are everywhere — network requests, form wizards, game logic, UI modes. Discriminated unions model them, and exhaustiveness ensures every state is handled. Adding a new state is a compile-time event: the compiler lists every place that needs updating.

Complete Example Session

# ============================================
# PART 1: BASIC EXHAUSTIVENESS
# ============================================

cat > exhaustive.ts << 'EOF'
type Status = 'idle' | 'loading' | 'ready' | 'error';

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

function message(s: Status): string {
  switch (s) {
    case 'idle': return 'Waiting';
    case 'loading': return 'Loading...';
    case 'ready': return 'Ready';
    case 'error': return 'Failed';
    default: return assertNever(s);
  }
}

console.log(message('idle'));
console.log(message('ready'));
EOF

npx tsc --noEmit exhaustive.ts
# (no errors)

# ============================================
# PART 2: TRIGGER EXHAUSTIVENESS ERROR
# ============================================

cat > missing.ts << 'EOF'
type Status = 'idle' | 'loading' | 'ready' | 'error';

function assertNever(x: never): never { throw x; }

function message(s: Status): string {
  switch (s) {
    case 'idle': return 'Waiting';
    case 'loading': return 'Loading...';
    case 'ready': return 'Ready';
    // ❌ 'error' not handled
    default: return assertNever(s);
  }
}
EOF

npx tsc --noEmit missing.ts
# [ missing.ts:11:32 - Argument of type '"error"' is not assignable to parameter of type 'never'. ]

rm missing.ts

# ============================================
# PART 3: DISCRIMINATED UNION EXHAUSTIVENESS
# ============================================

cat > du.ts << 'EOF'
type Event =
  | { kind: 'click'; x: number; y: number }
  | { kind: 'keydown'; key: string }
  | { kind: 'scroll'; offset: number };

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

function handle(e: Event): string {
  switch (e.kind) {
    case 'click': return `${e.x},${e.y}`;
    case 'keydown': return e.key;
    case 'scroll': return `${e.offset}`;
    default: return assertNever(e);
  }
}

console.log(handle({ kind: 'click', x: 1, y: 2 }));
EOF

npx tsc --noEmit du.ts
# (no errors)

# ============================================
# PART 4: NEVER IN RETURN TYPES
# ============================================

cat > never-return.ts << 'EOF'
function fail(msg: string): never {
  throw new Error(msg);
}

function infinite(): never {
  while (true) {}
}

// never is assignable to any type
const f: (s: string) => number = fail;

function handle(x: string | number): string {
  if (typeof x === 'string') return x;
  if (typeof x === 'number') return `${x}`;
  const _exhaustive: never = x;
  return _exhaustive;
}

console.log(handle('hi'), handle(42));
EOF

npx tsc --noEmit never-return.ts
# (no errors)

# ============================================
# PART 5: STATE MACHINE
# ============================================

cat > machine.ts << 'EOF'
type State =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string }
  | { status: 'error'; message: string };

function assertNever(x: never): never { throw x; }

function describe(s: State): string {
  switch (s.status) {
    case 'idle': return 'Ready';
    case 'loading': return 'Loading...';
    case 'success': return `Data: ${s.data}`;
    case 'error': return `Error: ${s.message}`;
    default: return assertNever(s);
  }
}

const states: State[] = [
  { status: 'idle' },
  { status: 'loading' },
  { status: 'success', data: 'hello' },
  { status: 'error', message: 'oops' }
];

for (const s of states) console.log(describe(s));
EOF

npx tsc --noEmit machine.ts
# (no errors)

# ============================================
# PART 6: MAPPED TYPE EXHAUSTIVENESS
# ============================================

cat > mapped.ts << 'EOF'
type Event =
  | { kind: 'click'; x: number; y: number }
  | { kind: 'keydown'; key: string };

type Handlers = {
  [K in Event['kind']]: (e: Extract<Event, { kind: K }>) => void;
};

const handlers: Handlers = {
  click: e => console.log(e.x, e.y),
  keydown: e => console.log(e.key)
  // ❌ missing 'keydown' would be a compile error
};

handlers.click({ kind: 'click', x: 1, y: 2 });
handlers.keydown({ kind: 'keydown', key: 'Enter' });
EOF

npx tsc --noEmit mapped.ts
# (no errors)

# ============================================
# PART 7: COMPILE AND RUN
# ============================================

npx tsc exhaustive.ts du.ts never-return.ts machine.ts mapped.ts
node exhaustive.js
# [ Waiting ]
# [ Ready ]

node du.js
# [ 1,2 ]

node never-return.js
# [ hi 42 ]

node machine.js
# [ Ready ]
# [ Loading... ]
# [ Data: hello ]
# [ Error: oops ]

node mapped.js
# [ 1 2 ]
# [ Enter ]

Quick Reference

`never` Facts

Fact	Meaning
Empty type	No values
Bottom type	Subtype of everything
Assignable to	Any type
Assignable from	Nothing
Union identity	`A \| never` = `A`
Intersection absorbing	`A & never` = `never`

Where `never` Appears

Context	Example
Function return	`function f(): never`
Impossible intersection	`string & number`
Exhaustiveness	After all cases
Unreachable code	After `return`/`throw`
Conditional filter	`T extends X ? never : T`

`assertNever`

Step	Code
Definition	`function assertNever(x: never): never { throw x; }`
Usage	`default: return assertNever(x);`
Trigger	Add a new union branch
Error	“Argument of type ‘X’ is not assignable to ‘never'”

Exhaustiveness Patterns

Pattern	Example
`assertNever`	`default: return assertNever(x);`
Inline never	`const _: never = x;`
If chain	`if (a) return; if (b) return; assertNever(x);`
All branches return	No default needed
Mapped type	`{ [K in T['kind']]: Handler }`

`assertNever` Variants

Style	Code
Minimal	`throw new Error('unreachable')`
With JSON	`throw new Error(JSON.stringify(x))`
Inline	`const _: never = x; throw new Error(...)`
Named parameter	`function assertNever(x: never): never`

Union Elimination

Before	After eliminating
`'a' \| 'b' \| 'c'`	`'b' \| 'c'` (matched `'a'`)
`'b' \| 'c'`	`'c'` (matched `'b'`)
`'c'`	`never` (matched `'c'`)

Common Discriminants for Exhaustiveness

Field	Example
`kind`	Shapes, events
`type`	Redux actions
`status`	Request states
`state`	Form/machine states
`ok`	Result success/failure

`never` Distribution

Input	Conditional
`never`	`never` (special)
`string \| number`	Distributes over each
Guard against	`[T] extends [never]`

Return Type Rules

Return	Meaning
`void`	No meaningful return
`undefined`	Returns `undefined`
`never`	Never returns (throws/loops)
`T`	Returns `T`

Mapped Type Exhaustiveness

Step	Code
Base type	`type Event = { kind: 'a' \| 'b' }`
Handler map	`{ [K in Event['kind']]: (e) => void }`
Implementation	All keys required
Missing key	Compile error at declaration

Error Messages

Error	Cause
`Argument of type 'X' is not assignable to 'never'`	Missing exhaustiveness
`Not all code paths return a value`	Missing branch
`Unreachable code detected`	Code after `return`/`throw`
`Property 'x' does not exist`	Wrong narrowed branch

Best Practices

✅ Do This:

// Define assertNever once
function assertNever(x: never): never {
  throw new Error(`Unhandled: ${JSON.stringify(x)}`);
}                                                            // ✅

// Use it in every exhaustive switch
switch (e.kind) {
  case 'a': return handleA(e);
  case 'b': return handleB(e);
  default: return assertNever(e);
}                                                            // ✅

// Use never for throw-only functions
function fail(msg: string): never { throw new Error(msg); }  // ✅

// Use `never` for impossible intersections
type Impossible = string & number;                           // ✅ = never

// Use mapped types for handler exhaustiveness
type Handlers = {
  [K in Event['kind']]: (e: Extract<Event, { kind: K }>) => void;
};                                                           // ✅

// Test by adding a new union branch
// Every switch should fail to compile until updated          // ✅

// Use inline never when you don't want a helper
default: {
  const _: never = x;
  throw new Error('unreachable');
}                                                            // ✅

❌ Don’t Do This:

// Don't skip the default
switch (x.kind) {
  case 'a': break;
  case 'b': break;
  // ❌ silent miss
}                                                            // ❌

// Don't throw a generic error without assertion
default: throw new Error('unreachable');                     // ⚠️  no compile-time check

// Don't use `as never` to silence errors
default: assertNever(x as never);                            // ❌ hides real issues

// Don't use `any` in default
default: { const _: any = x; }                               // ❌ no check

// Don't ignore exhaustiveness for critical paths
// Reducers, parsers, state machines need it                 // ❌

// Don't type throwing functions as void
function fail(): void { throw new Error(); }                 // ⚠️  never is more precise

// Don't confuse never with void in returns
function f(): never { return; }                              // ❌ error

// Don't rely on implicit exhaustiveness
// Always add a default with assertNever                     // ✅

Common Pitfalls

Pitfall	Problem	Solution
Missing `default`	Silent miss	Add `assertNever`
`default: break`	No check	Use `assertNever`
`as never` to silence	Hides bugs	Fix the missing case
Forgetting `assertNever`	No compile-time check	Use it everywhere
`void` return for throws	Less precise	Use `never`
`never` in conditional	Distributive surprise	Guard with `[T] extends [never]`
Missing return in one branch	Return type error	Add the branch
Adding union branch	Only some code catches it	Use mapped-type dispatch

Real-World Examples

1. Define `assertNever`

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

2. Exhaustive switch

switch (x.kind) {
  case 'a': return a;
  case 'b': return b;
  default: return assertNever(x);
}

3. Inline never check

default: {
  const _: never = x;
  throw new Error('unreachable');
}

4. Function that never returns

function fail(msg: string): never { throw new Error(msg); }

5. Infinite loop

function loop(): never { while (true) {} }

6. Impossible intersection

type Empty = string & number;  // never

7. Union identity

type A = string | never;  // string

8. Filter nullish with never

type NonNullish<T> = T extends null | undefined ? never : T;

9. Exhaustive reducer

switch (action.type) {
  case 'ADD': return add(state, action.item);
  case 'REMOVE': return remove(state, action.id);
  case 'CLEAR': return initial;
  default: return assertNever(action);
}

10. Mapped-type handlers

type Handlers = {
  [K in Event['kind']]: (e: Extract<Event, { kind: K }>) => void;
};

11. Handle all states

switch (state.status) {
  case 'idle': ...
  case 'loading': ...
  case 'success': ...
  case 'error': ...
  default: return assertNever(state);
}

12. Unreachable code detection

return;
console.log('x');  // ❌ unreachable

13. `never` in catch

catch (e) {
  if (e instanceof Error) handleError(e);
  else throw e;  // e might be never here
}

14. Guard against never distribution

type Safe<T> = [T] extends [never] ? 'empty' : 'has-value';

15. Exhaustive if chain

if (x === 'a') return 1;
if (x === 'b') return 2;
if (x === 'c') return 3;
return assertNever(x);

16. Add variant → compile error

type Status = 'idle' | 'loading' | 'ready' | 'error' | 'cancelled';
// Now every switch fails to compile until updated

17. Throw-only helper

function invariant(cond: boolean, msg: string): asserts cond {
  if (!cond) throw new Error(msg);
}

18. Exhaustive dispatch

function dispatch(cmd: Command): void {
  switch (cmd.kind) {
    case 'create': return create(cmd);
    case 'update': return update(cmd);
    case 'delete': return remove(cmd);
    default: return assertNever(cmd);
  }
}

19. State machine transition

function nextState(s: State, e: Event): State {
  switch (s.status) {
    // all cases
    default: return assertNever(s);
  }
}

20. Typescript catches missing branch

// Adding { kind: 'hover' } to Event makes every
// exhaustive switch fail with a precise error.

Visual: Exhaustiveness Flow

┌──────────────────────────────────────────────┐
│  type Status = 'a' | 'b' | 'c'               │
│                                              │
│  function f(s: Status) {                     │
│    switch (s) {                              │
│      case 'a': ...   → s: 'a'                │
│      case 'b': ...   → s: 'b'                │
│      case 'c': ...   → s: 'c'                │
│      default:        → s: never              │
│    }                                         │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘

Visual: Adding a Variant

┌──────────────────────────────────────────────┐
│  Before:                                     │
│  type Status = 'a' | 'b' | 'c'               │
│                                              │
│  switch (s) { case 'a': case 'b': case 'c': }│
│  → compiles                                  │
│                                              │
└──────────────────────────────────────────────┘
                  │
                  │  add 'd'
                  ▼
┌──────────────────────────────────────────────┐
│  After:                                      │
│  type Status = 'a' | 'b' | 'c' | 'd'         │
│                                              │
│  switch (s) { case 'a': case 'b': case 'c': }│
│  → ❌ 'd' not assignable to never            │
│                                              │
└──────────────────────────────────────────────┘

Visual: `never` in Function Returns

┌──────────────────────────────────────────────┐
│  function f(): never { throw new Error(); }  │
│                                              │
│  → never returns                             │
│  → assignable to any signature               │
│  → code after call is unreachable            │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  function f(): void { }                      │
│                                              │
│  → returns undefined                         │
│  → NOT assignable where never is expected    │
│                                              │
└──────────────────────────────────────────────┘

Visual: `never` in Types

┌──────────────────────────────────────────────┐
│  string & number    → never                  │
│  string | never     → string                 │
│  never | never      → never                  │
│  never[]            → never[]                │
│  Array<never>       → never[]                │
│  Partial<never>     → {}                     │
│                                              │
└──────────────────────────────────────────────┘

Visual: assertNever Variants

┌──────────────────────────────────────────────┐
│  Named helper                                │
│                                              │
│  function assertNever(x: never): never {     │
│    throw new Error(JSON.stringify(x));       │
│  }                                           │
│                                              │
│  default: return assertNever(x);             │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  Inline                                      │
│                                              │
│  default: {                                  │
│    const _exhaustive: never = x;             │
│    throw new Error('unreachable');           │
│  }                                           │
│                                              │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  If chain                                    │
│                                              │
│  if (x === 'a') return 1;                    │
│  if (x === 'b') return 2;                    │
│  return assertNever(x);                      │
│                                              │
└──────────────────────────────────────────────┘

Visual: Mapped-Type Exhaustiveness

┌──────────────────────────────────────────────┐
│  type Event =                                │
│    | { kind: 'click'; x: number; y: number } │
│    | { kind: 'keydown'; key: string };       │
│                                              │
│  type Handlers = {                           │
│    [K in Event['kind']]:                     │
│      (e: Extract<Event, { kind: K }>) => void│
│  };                                          │
│                                              │
│  const handlers: Handlers = {                │
│    click: e => ...,                          │
│    keydown: e => ...                         │
│  };                                          │
│                                              │
│  Missing 'keydown' → compile error           │
│                                              │
└──────────────────────────────────────────────┘

Visual: Where `never` Appears

┌──────────────────────────────────────────────┐
│  Value level                                 │
│  ─ function returns never                    │
│  ─ unreachable code                          │
│  ─ after exhaustiveness                      │
│                                              │
│  Type level                                  │
│  ─ impossible intersections                  │
│  ─ union identity                            │
│  ─ conditional filter                        │
│  ─ distributive special case                 │
│                                              │
└──────────────────────────────────────────────┘

Visual: Reducer Exhaustiveness

┌──────────────────────────────────────────────┐
│  function reducer(state, action) {           │
│    switch (action.type) {                    │
│      case 'ADD':    return add(...);         │
│      case 'REMOVE': return remove(...);      │
│      case 'CLEAR':  return initial;          │
│      default:       return assertNever(action);│
│    }                                         │
│  }                                           │
│                                              │
│  Add action → compile error here             │
│                                              │
└──────────────────────────────────────────────┘

Visual: Never in Conditional Types

┌──────────────────────────────────────────────┐
│  type NonNullish<T> =                        │
│    T extends null | undefined ? never : T;   │
│                                              │
│  NonNullish<string | null>          → string │
│  NonNullish<number | undefined>     → number │
│  NonNullish<null | undefined>       → never  │
│  NonNullish<never>                  → never  │
│                                              │
└──────────────────────────────────────────────┘

Visual: Check for Exhaustiveness

┌──────────────────────────────────────────────┐
│  All branches handled?                       │
│       │                                      │
│       ├── Yes ──► default: never             │
│       │            (no error)                │
│       │                                      │
│       └── No  ──► default: remaining-type    │
│                    ❌ not assignable to never │
│                                              │
└──────────────────────────────────────────────┘

Summary

Concept	Meaning
`never`	Empty type — no values
Bottom type	Subtype of every type
Function return	`never` = never returns
Exhaustiveness	`never` after all cases
`assertNever`	Helper that enforces exhaustiveness
Union identity	`A \| never` = `A`
Intersection absorbing	`A & never` = `never`
Distributive	`never` distributes to `never`
Unreachable	Code after throw/return is never

Key takeaways:

never is the empty type — no value belongs to it, and it’s assignable to everything
Functions that throw or loop forever return never
After a switch handles every branch of a union, the remaining type is never
assertNever turns exhaustiveness into a compile-time check — assign the remainder to a never parameter
Adding a new variant to a union triggers compile errors in every exhaustive switch — a free checklist
Inline const _: never = x works without a helper
Mapped types over a discriminant force an entry per variant
never appears in impossible intersections, conditional filters, and unreachable code
Distribution through conditional types has special behavior — guard with [T] extends [never]
Use never, not void, for functions that never return — more precise, more useful
Don’t silence errors with as never — fix the missing case
Exhaustiveness works within a function scope — use mapped-type handlers for cross-function dispatch

Remember: never is the empty type, and its greatest use is proving your code handles everything. After a switch over a union, the compiler narrows the remainder to never — and if it isn’t never, you missed a case. That’s the whole trick: assertNever forces the compiler to check. Add a new variant and every switch fails to compile until updated. It’s the single most useful pattern for keeping discriminated unions, state machines, and reducers correct as they evolve.

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!

What never is

never in function returns