15.2 Exhaustiveness: never as a Checklist — The Complete TypeScript Course

Exhaustiveness means every member of a union has been handled. In TypeScript, never turns that promise into a compiler checklist: add a new variant, and the checker points at the places that forgot it.

You saw the basic const unhandled: never = value pattern in 4.3 and Project 1. This lesson hardens it into the version you use in real code: an assertNever helper, repeated affected sites, and exhaustive maps when a switch would only be a lookup table.

The `assertNever` helper

never is the empty set: no value can have that type. If a value reaches a line that accepts only never, TypeScript knows some union member escaped your checks.

The small helper is usually named assertNever. It accepts a never value and throws if runtime ever reaches it. The throw matters: if your JavaScript is called with impossible data anyway, the program fails loudly instead of returning a fake fallback.

typescript — playgroundtype-checked

function assertNever(value: never): never {
throw new Error("Unhandled variant: " + JSON.stringify(value));
}

type CheckoutState =
| { status: "empty" }
| { status: "editing"; itemCount: number }
| { status: "submitting"; requestId: string }
| { status: "complete"; receiptId: string }
| { status: "failed"; message: string }
// break it: uncomment the next line, then hit Run
// | { status: "review"; reviewer: string };

function checkoutLabel(state: CheckoutState): string {
switch (state.status) {
  case "empty":
    return "Cart is empty";
  case "editing":
    return "Cart has " + state.itemCount + " item(s)";
  case "submitting":
    return "Submitting " + state.requestId;
  case "complete":
    return "Receipt " + state.receiptId;
  case "failed":
    return "Failed: " + state.message;
  default:
    return assertNever(state);
}
}

console.log(checkoutLabel({ status: "empty" }));
console.log(checkoutLabel({ status: "editing", itemCount: 3 }));
console.log(checkoutLabel({ status: "complete", receiptId: "r-42" }));

⌘/Ctrl + Enter to run

→ Cart is empty
→ Cart has 3 item(s)
→ Receipt r-42

When every case is handled, the default branch sees state as never, so the helper call is allowed. Uncomment the "review" member and the helper call becomes the error site: state is no longer impossible there. The fix is not to change assertNever; the fix is to add the missing case "review".

This is better than a default string like "Unknown status". A fallback hides the missing case. assertNever makes the missing case a compile-time task.

One new variant, several precise errors

The professional payoff appears when the same union feeds more than one decision. A checkout event may need a user-facing label, an analytics metric, and a severity. If you add a new event, all three places must stay synchronized.

typescript — playgroundtype-checked

function assertNever(value: never): never {
throw new Error("Unhandled event: " + JSON.stringify(value));
}

type CheckoutEvent =
| { type: "cart_opened"; cartId: string }
| { type: "item_added"; sku: string; quantity: number }
| { type: "payment_failed"; reason: string }
// break it: uncomment the next line, then hit Run
// | { type: "coupon_applied"; code: string; centsOff: number };

function eventTitle(event: CheckoutEvent): string {
switch (event.type) {
  case "cart_opened":
    return "Cart " + event.cartId + " opened";
  case "item_added":
    return event.quantity + " x " + event.sku + " added";
  case "payment_failed":
    return "Payment failed: " + event.reason;
  default:
    return assertNever(event);
}
}

function eventMetric(event: CheckoutEvent): string {
switch (event.type) {
  case "cart_opened":
    return "checkout.cart_opened";
  case "item_added":
    return "checkout.item_added";
  case "payment_failed":
    return "checkout.payment_failed";
  default:
    return assertNever(event);
}
}

function eventSeverity(event: CheckoutEvent): "info" | "warning" {
switch (event.type) {
  case "cart_opened":
  case "item_added":
    return "info";
  case "payment_failed":
    return "warning";
  default:
    return assertNever(event);
}
}

const events: CheckoutEvent[] = [
{ type: "cart_opened", cartId: "c-1" },
{ type: "item_added", sku: "TS-101", quantity: 2 },
{ type: "payment_failed", reason: "card declined" },
];

for (const event of events) {
console.log(eventSeverity(event) + " " + eventMetric(event) + " - " + eventTitle(event));
}

⌘/Ctrl + Enter to run

→ info checkout.cart_opened - Cart c-1 opened
→ info checkout.item_added - 2 x TS-101 added
→ warning checkout.payment_failed - Payment failed: card declined

Without assertNever, adding "coupon_applied" might compile while returning a vague fallback, logging the wrong metric, or choosing the wrong severity. With it, the affected sites fail immediately and locally.

Exhaustive maps for table-shaped decisions

A switch is best when each case runs different logic. If the decision is just "for every status, look up a label" or "for every status, look up a formatter," an exhaustive Record is often cleaner.

Record<Status, string> means every Status key must exist and every value must be a string. The key union becomes the checklist.

typescript — playgroundtype-checked

type Campaign = {
id: string;
title: string;
status: CampaignStatus;
};

const statusLabel: Record<CampaignStatus, string> = {
draft: "Draft",
scheduled: "Scheduled",
sent: "Sent",
failed: "Failed",
};

const statusTone: Record<CampaignStatus, "neutral" | "active" | "success" | "danger"> = {
draft: "neutral",
scheduled: "active",
sent: "success",
failed: "danger",
};

const statusAction: Record<CampaignStatus, (campaign: Campaign) => string> = {
draft: (campaign) => "Edit " + campaign.title,
scheduled: (campaign) => "Reschedule " + campaign.title,
sent: (campaign) => "View report for " + campaign.title,
failed: (campaign) => "Retry " + campaign.title,
};

function campaignRow(campaign: Campaign): string {
return (
  statusLabel[campaign.status] +
  " [" +
  statusTone[campaign.status] +
  "] - " +
  statusAction[campaign.status](campaign)
);
}

const campaigns: Campaign[] = [
{ id: "c-1", title: "Welcome series", status: "draft" },
{ id: "c-2", title: "Launch reminder", status: "scheduled" },
{ id: "c-3", title: "Course update", status: "sent" },
];

for (const campaign of campaigns) {
console.log(campaignRow(campaign));
}

⌘/Ctrl + Enter to run

→ Draft [neutral] - Edit Welcome series
→ Scheduled [active] - Reschedule Launch reminder
→ Sent [success] - View report for Course update

Uncomment "paused" and the maps become the affected sites. That is exactly what you want: a new status needs a label, a tone, and an action. A plain object typed as Record<string, string> would not give you that checklist because "every string" is too wide to enumerate.

Use this version when the logic is data-shaped. If each case needs its own branching, validation, or side effects, use a switch with assertNever.

Keep the checklist close to the union

Exhaustiveness only helps if the union is the source of truth. Do not write a broad string status and then hope every status map stays complete. Keep the status as a literal union, or derive it from a trusted as const list when a runtime list is already the source of truth.

The rule is simple:

Use a discriminated union plus assertNever for variant-specific logic.
Use Record<Union, Value> for variant-specific lookup tables.
Add new variants by changing the union first, then follow the checker errors.

Next lesson moves from impossible variants to missing values: strictNullChecks, optional chaining, nullish coalescing, and the habits that keep null from turning into surprise crashes.

Checkpoint

Answer all three to mark this lesson complete

Exhaustiveness: never as a Checklist

The assertNever helper

One new variant, several precise errors

Exhaustive maps for table-shaped decisions

Keep the checklist close to the union

Checkpoint ✦

The `assertNever` helper

Checkpoint