← Back to glossary

Exhaustive Checks with never

TypeScript Intermediate

debt(d1/e1/b3/t3)

d1 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'caught instantly (compiler/syntax error)' (d1). When assertNever is correctly placed in a switch default and a new union variant is added without handling it, TypeScript emits a compile-time type error immediately — no specialist tool needed, no runtime required.

e1 Effort Remediation debt — work required to fix once spotted

Closest to 'one-line patch or single-call swap' (e1). The quick_fix confirms the remedy is a single reusable helper 'assertNever(x: never): never' dropped into switch defaults — a one-line addition per switch case.

b3 Burden Structural debt — long-term weight of choosing wrong

Closest to 'localised tax' (b3). The pattern must be applied at every switch/if-else that handles a union, imposing a small per-site discipline. However, it's a lightweight helper with no cross-cutting architectural weight; it doesn't shape the rest of the codebase.

t3 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'minor surprise (one edge case)' (t3). The misconception field notes that developers wrongly believe never checks only work with discriminated unions, when they work with any narrowable union. The common_mistakes also highlight the subtle issue that assertNever must have a 'never' return type — both are minor but real surprises rather than catastrophic ones.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-11 · reviewed by human

Also Known As

exhaustive switch never check exhaustive union assertNever

TL;DR

Using the 'never' type in a default branch to make TypeScript error at compile time if a union type is not fully handled — ensures every new variant of a type forces a matching handler to be written.

Explanation

TypeScript narrows union types as control flow progresses through if/switch statements. After all known members are handled, the remaining type is 'never' — the empty type that has no values. Assigning that remaining value to a 'never' variable compiles fine if all cases are covered, but errors if any case was missed (because something non-never would be assigned to a never slot). This is the exhaustive check pattern. It catches the most common union-evolution bug: a new member is added to a union type, but the switch statement handling it is not updated — TypeScript immediately errors at every switch that lacks the new case.

Common Misconception

✗ The never check only works with discriminated unions. It works with any union that TypeScript can narrow through control flow — string literals, numeric literals, boolean, null/undefined unions.

Why It Matters

Union types grow over time — new payment methods, new event types, new error codes. Without exhaustive checks, adding a new variant silently falls through to an unhandled default. With exhaustive checks, every switch that handles the union gets a compile error until it is updated. This makes it structurally impossible to forget a case.

Common Mistakes

Using 'default: break' without a never check — this silently swallows unhandled cases with no compile-time warning.
Not returning from assertNever — it must be typed as 'never' return type; otherwise TypeScript allows it in the default and the exhaustiveness is lost.
Forgetting exhaustive checks in if-else chains — switch is the most common place but 'if/else if' on a union also benefits from a trailing else that calls assertNever.
Using assertNever in runtime-only code where the union may be extended by third parties — exhaustive checks are appropriate for closed unions you control, not open unions.

Code Examples

✗ Vulnerable

// ❌ No exhaustive check — new union member silently unhandled
type Status = 'active' | 'inactive' | 'suspended';

function getLabel(status: Status): string {
    switch (status) {
        case 'active':   return 'Active';
        case 'inactive': return 'Inactive';
        // 'suspended' added to the union — no error here
        // Returns undefined at runtime
    }
}

✓ Fixed

// ✅ Exhaustive check — new member forces update
function assertNever(x: never): never {
    throw new Error(`Unhandled case: ${JSON.stringify(x)}`);
}

type Status = 'active' | 'inactive' | 'suspended';

function getLabel(status: Status): string {
    switch (status) {
        case 'active':    return 'Active';
        case 'inactive':  return 'Inactive';
        case 'suspended': return 'Suspended';
        default: return assertNever(status);
        // Add 'banned' to Status → compile error here until handled
    }
}

// Inline never check (no helper)
switch (action.type) {
    case 'A': /* ... */ break;
    case 'B': /* ... */ break;
    default:
        const _: never = action; // Error if any case missing
}

References

https://www.typescriptlang.org/docs/handbook/2/narrowing.html#the-never-type