Exhaustiveness checking

A new order status that one switch forgot

A shop shows each order with a short label, like "On its way". A function picks the label with a switch. Then the team adds a new status, "cancelled", and nobody remembers this function:

function statusLabel(status) {
  switch (status) {
    case "placed":
      return "We got your order";
    case "shipped":
      return "On its way";
    case "delivered":
      return "At your door";
  }
}

console.log(statusLabel("cancelled"));

Lines 3 to 8 handle three statuses. Line 12 asks for the label of a cancelled order. No case matches, so the function reaches its end without a return and gives back undefined. The page prints undefined where the label should be, and nothing warns you.

In TypeScript you can ask the compiler to check that a switch handles every status. This is called exhaustiveness checking: "exhaustive" means "nothing left out". Here is the same function with the check added:

1type OrderStatus = "placed" | "shipped" | "delivered" | "cancelled";2 3function statusLabel(status: OrderStatus) {4  switch (status) {5    case "placed":6      return "We got your order";7    case "shipped":8      return "On its way";9    case "delivered":10      return "At your door";11    default:12      const unhandled: never = status;13      throw new Error(`Unknown status: ${unhandled}`);14  }15}16 17console.log(statusLabel("cancelled"));

Line 1 is a union type: OrderStatus can be exactly one of four texts, and | means "or". Line 3 says status is an OrderStatus. Lines 11 to 13 are new. Line 12 puts status into a variable whose type is never. never is the type with no values: nothing is allowed to go in it.

Each case takes one status away. Whatever no case handled reaches default, and here that's "cancelled". TypeScript marks line 12, on purpose here, because it's the forgotten case:

• Type '"cancelled"' is not assignable to type 'never' means "the value "cancelled" can still get here, and nothing is allowed here". The message names the case you forgot.
• If you run the code anyway, line 13 throws Error: Unknown status: cancelled instead of showing undefined.

never in the default branch

never is the type with no values. No text, number, or object fits in it, so storing anything in a never variable is an error:

1const unhandled: never = "placed";

Line 1 tries to store "placed" in unhandled, and TypeScript says Type '"placed"' is not assignable to type 'never'. That's the error on purpose. So when is never useful? When a value has been checked so many times that no possibility is left.

TypeScript follows your checks. Inside case "placed":, it knows status is "placed", and after that case it knows status is something else. This is narrowing: the type gets smaller as your code checks it. When every case is handled, nothing is left:

1type OrderStatus = "placed" | "shipped" | "delivered";2 3function statusLabel(status: OrderStatus) {4  switch (status) {5    case "placed":6      return "We got your order";7    case "shipped":8      return "On its way";9    case "delivered":10      return "At your door";11    default:12      const unhandled: never = status;13      //                       ^?14      throw new Error(`Unknown status: ${unhandled}`);15  }16}17 18console.log(statusLabel("shipped"));

Line 1 lists three statuses, and lines 5 to 10 handle all three. The query on line 13 points at status on line 12 and shows (parameter) status: never ("parameter" because status is the function's parameter). Nothing can reach default, so storing status in a never is fine, and there are no errors. Line 18 prints On its way.

Now take cases away and watch what reaches default. Each button adds or removes one case:

1type OrderStatus = "placed" | "shipped" | "delivered";2 3function statusLabel(status: OrderStatus) {4  switch (status) {5    case "placed":6      return "We got your order";7    case "shipped":8      return "On its way";9    case "delivered":10      return "At your door";11    default:12      const unhandled: never = status;13      //                       ^?14      throw new Error(`Unknown status: ${unhandled}`);15  }16}

Turn off case "shipped". The code gets two lines shorter, so the never line moves up to line 10, and the query under it shows "shipped": the one status no case handles. TypeScript marks line 10. Turn off a second case and the message lists both leftovers, like '"shipped" | "delivered"'. Turn off all three and the whole OrderStatus type reaches default. Turn them back on and the error goes away.

assertNever: one helper for every switch

Writing const unhandled: never = status; in every switch gets repetitive. Most projects write a small helper once, called assertNever, and call it from every default:

1type OrderStatus = "placed" | "shipped" | "delivered" | "cancelled";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function statusLabel(status: OrderStatus) {8  switch (status) {9    case "placed":10      return "We got your order";11    case "shipped":12      return "On its way";13    case "delivered":14      return "At your door";15    default:16      return assertNever(status);17  }18}

Lines 3 to 5 are the helper. Its parameter value has the type never, so the only thing you may pass it is a value with nothing left. Its return type is never too, which means "this function never returns": line 4 always throws an error. Line 16 calls it from default.

Line 1 lists "cancelled", but no case handles it, so it reaches line 16. TypeScript marks that line, on purpose: Argument of type '"cancelled"' is not assignable to parameter of type 'never'. An argument is a value you pass to a function, so this means "you're passing "cancelled" to a function that accepts nothing". Add the case and the error goes away.

The helper works the same for a union of objects with a shared kind field, like the request states of a page that loads data:

1type RequestState =2  | { kind: "loading" }3  | { kind: "success"; items: string[] }4  | { kind: "error"; message: string };5 6function assertNever(value: never): never {7  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);8}9 10function render(state: RequestState) {11  switch (state.kind) {12    case "loading":13      return "Loading...";14    case "success":15      return `${state.items.length} items`;16    default:17      return assertNever(state);18  }19}

Lines 1 to 4 describe three states: loading, success with a list of items, and error with a message. Line 11 switches on state.kind, and each case narrows the whole state object. There's no case for "error", so line 17 gets an error on purpose. This time the message names the whole leftover object type: Argument of type '{ kind: "error"; message: string; }' is not assignable to parameter of type 'never'.

assertNever also helps while the page runs. Types are removed before the code runs, so data from outside, like a server reply read with JSON.parse, can hold a value your type doesn't list:

1type OrderStatus = "placed" | "shipped" | "delivered";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function statusLabel(status: OrderStatus) {8  switch (status) {9    case "placed":10      return "We got your order";11    case "shipped":12      return "On its way";13    case "delivered":14      return "At your door";15    default:16      return assertNever(status);17  }18}19 20const order: { status: OrderStatus } = JSON.parse('{ "status": "returned" }');21try {22  console.log(statusLabel(order.status));23} catch (error) {24  console.log(String(error));25}

Every status has a case, so TypeScript reports nothing. Line 20 reads an order from a server reply and says its status is an OrderStatus. TypeScript trusts that, because JSON.parse gives back any, which it never checks. But the reply says "returned". No case matches, so line 16 calls assertNever, which throws. The try and catch on lines 21 to 25 catch the error, and line 24 prints Error: Unhandled value: "returned". A clear error is much easier to find than a label that quietly says undefined.

Adding a case safely

A real app has many switches over the same type: one picks the label, another the color, another the icon. When you add a status, the hard part is finding them all. With a check in each default, TypeScript finds them for you. Step through adding "cancelled":

1type OrderStatus = "placed" | "shipped" | "delivered";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function statusLabel(status: OrderStatus) {8  switch (status) {9    case "placed": return "We got your order";10    case "shipped": return "On its way";11    case "delivered": return "At your door";12    default: return assertNever(status);13  }14}15 16function statusColor(status: OrderStatus) {17  switch (status) {18    case "placed": return "blue";19    case "shipped": return "orange";20    case "delivered": return "green";21    default: return assertNever(status);22  }23}

Step 1 has no errors. Step 2 changes only line 1, and TypeScript marks line 12 in statusLabel and line 21 in statusColor: a to-do list of every switch that needs the new case. Step 3 adds the case to statusLabel on line 12, and one error is left, in statusColor. Step 4 adds it there too, and the errors are gone. Without the checks, step 2 would have no errors at all, and both functions would quietly give back undefined for a cancelled order.

Exhaustive return types

A switch that returns a value can be checked without any default at all. First, see what TypeScript works out when a case is missing and the function has no return type written:

1type Shipping = "standard" | "express" | "pickup";2 3function deliveryDays(method: Shipping) {4  switch (method) {5    case "standard":6      return 5;7    case "express":8      return 1;9  }10}11 12let days = deliveryDays("pickup");13//  ^?14console.log(days);

Line 1 lists three ways to ship. Lines 5 to 8 handle two of them, and nothing handles "pickup". Line 12 asks for the pickup days, and the query on line 13 shows let days: number | undefined: TypeScript saw that the function can end without a return, so it can give back undefined. There's no error, and line 14 prints undefined.

Now write the return type you mean, : number, after the parameters. This is called a return type annotation:

1type Shipping = "standard" | "express" | "pickup";2 3function deliveryDays(method: Shipping): number {4  switch (method) {5    case "standard":6      return 5;7    case "express":8      return 1;9  }10}

Line 3 promises a number. With no case for "pickup", the function can still reach its end without returning, so TypeScript marks line 3, on purpose: Function lacks ending return statement and return type does not include 'undefined'. In plain words: "some path through this function returns nothing, and number doesn't allow that". Add case "pickup": return 0; and the error goes away. Exercise 6 asks you to do it.

The table below compares the ways to end a switch. Read each row as: this ending, what TypeScript says when a status has no case, and what happens if a value the type doesn't list arrives while the page runs.

Every payment method at checkout

A checkout page shows a short summary of how the shopper is paying. Each payment method carries different details, so the payment is a union of objects with a shared method field:

1type Payment =2  | { method: "card"; last4: string }3  | { method: "paypal"; email: string }4  | { method: "giftCard"; balance: number };5 6function assertNever(value: never): never {7  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);8}9 10function paymentSummary(payment: Payment) {11  switch (payment.method) {12    case "card":13      return `Card ending ${payment.last4}`;14    case "paypal":15      return `PayPal (${payment.email})`;16    case "giftCard":17      return `Gift card, $${payment.balance} left`;18    default:19      return assertNever(payment);20  }21}22 23console.log(paymentSummary({ method: "card", last4: "4242" }));24console.log(paymentSummary({ method: "giftCard", balance: 15 }));

Lines 1 to 4 describe three methods: a card with its last four digits, PayPal with an email, and a gift card with a balance. Line 11 switches on payment.method. Inside each case TypeScript knows which object it has, so line 13 can read last4 and line 17 can read balance. Line 19 hands the leftover to assertNever, and since every method has a case, there's no error. Line 23 prints Card ending 4242 and line 24 prints Gift card, $15 left.

Next month the shop adds Apple Pay. Add | { method: "applePay" } to the type with Edit & run, and line 19 gets an error until you add its case.

Common mix-ups

A default branch alone doesn't make a switch safe. Here are two statuses forgotten, with no error at all:

1type OrderStatus = "placed" | "shipped" | "delivered" | "cancelled";2 3function statusLabel(status: OrderStatus) {4  switch (status) {5    case "placed":6      return "We got your order";7    case "shipped":8      return "On its way";9    default:10      return "Unknown status";11  }12}13 14console.log(statusLabel("delivered"));

Line 1 lists four statuses, and lines 5 to 8 handle only two. Line 10 returns "Unknown status" for anything else, which TypeScript accepts, because a fallback can stand for any status. Line 14 asks about a delivered order and prints Unknown status.

The check also needs a union with a fixed list of members. A plain string is never used up:

1function statusLabel(status: string) {2  switch (status) {3    case "placed":4      return "We got your order";5    case "shipped":6      return "On its way";7    case "delivered":8      return "At your door";9    default:10      const unhandled: never = status;11      throw new Error(`Unknown status: ${unhandled}`);12  }13}

Line 1 says status is any string. Lines 3 to 8 handle three texts, but a string can be endless other texts, so it's still a string in default. Line 10 gets Type 'string' is not assignable to type 'never' on purpose, however many cases you add. Give status a union type, like OrderStatus, to make the check work.

• "A default branch makes a switch safe." No. A default that returns a fallback answers for every forgotten case, so TypeScript has nothing to report. Put the check in default instead.
• "never means null or undefined." No. undefined is a value. never has no values at all: it's the type of a place your code can't reach.
• "TypeScript checks every switch for missing cases on its own." No. It only reports a missing case when you ask: with a never variable, assertNever, or a return type.
• "The check works on any type." No. It needs a union with a fixed list of members, like "placed" | "shipped". A string or a number is never used up.
• "assertNever only matters while I type." No. It also throws while the page runs, when outside data has a value your type doesn't list, like "returned".

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

type Theme = "light" | "dark" | "system";

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

function themeIcon(theme: Theme) {
  switch (theme) {
    case "light":
      return "sun";
    case "dark":
      return "moon";
    default:
      return assertNever(theme);
  }
}

1type Theme = "light" | "dark" | "system";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function themeIcon(theme: Theme) {8  switch (theme) {9    case "light":10      return "sun";11    case "dark":12      return "moon";13    case "system":14      return "monitor";15    default:16      return assertNever(theme);17  }18}19 20console.log(themeIcon("system"));

1type Theme = "light" | "dark" | "system";2 3function themeIcon(theme: Theme) {4  switch (theme) {5    case "light":6      return "sun";7    case "dark":8      return "moon";9    case "system":10      return "monitor";11    default:12      const unhandled: never = theme;13      throw new Error(`Unknown theme: ${unhandled}`);14  }15}

1type Theme = "light" | "dark" | "system";2 3function themeIcon(theme: Theme) {4  switch (theme) {5    case "light":6      return "sun";7    case "dark":8      return "moon";9    case "system":10      return "monitor";11    default:12      const unhandled: never = theme;13      //                       ^?14      throw new Error(`Unknown theme: ${unhandled}`);15  }16}

1type ButtonVariant = "primary" | "secondary" | "danger";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function buttonClass(variant: ButtonVariant) {8  switch (variant) {9    case "primary":10      return "btn btn-blue";11    case "secondary":12      return "btn btn-grey";13    default:14      return assertNever(variant);15  }16}17 18console.log(buttonClass("primary"));

1type ButtonVariant = "primary" | "secondary" | "danger";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function buttonClass(variant: ButtonVariant) {8  switch (variant) {9    case "primary":10      return "btn btn-blue";11    case "secondary":12      return "btn btn-grey";13    case "danger":14      return "btn btn-red";15    default:16      return assertNever(variant);17  }18}19 20console.log(buttonClass("danger"));

1type Size = "S" | "M" | "L";2 3function sizeLabel(size: Size) {4  switch (size) {5    case "S":6      return "Small";7    case "M":8      return "Medium";9    case "L":10      return "Large";11    default:12      return assertNever(size);13  }14}15 16console.log(sizeLabel("M"));

1type Size = "S" | "M" | "L";2 3function assertNever(value: never): never {4  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);5}6 7function sizeLabel(size: Size) {8  switch (size) {9    case "S":10      return "Small";11    case "M":12      return "Medium";13    case "L":14      return "Large";15    default:16      return assertNever(size);17  }18}19 20console.log(sizeLabel("M"));

1type Notice =2  | { kind: "message"; from: string }3  | { kind: "sale"; percent: number }4  | { kind: "shipped"; orderId: number };5 6function noticeText(notice: Notice) {7  switch (notice.kind) {8    case "message":9      return `New message from ${notice.from}`;10    case "sale":11      return `${notice.percent}% off today`;12  }13}14 15console.log(noticeText({ kind: "shipped", orderId: 42 }));

1type Notice =2  | { kind: "message"; from: string }3  | { kind: "sale"; percent: number }4  | { kind: "shipped"; orderId: number };5 6function assertNever(value: never): never {7  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);8}9 10function noticeText(notice: Notice) {11  switch (notice.kind) {12    case "message":13      return `New message from ${notice.from}`;14    case "sale":15      return `${notice.percent}% off today`;16    case "shipped":17      return `Order ${notice.orderId} has shipped`;18    default:19      return assertNever(notice);20  }21}22 23console.log(noticeText({ kind: "shipped", orderId: 42 }));

1type Shipping = "standard" | "express" | "pickup";2 3function deliveryDays(method: Shipping): number {4  switch (method) {5    case "standard":6      return 5;7    case "express":8      return 1;9  }10}

1type Shipping = "standard" | "express" | "pickup";2 3function deliveryDays(method: Shipping): number {4  switch (method) {5    case "standard":6      return 5;7    case "express":8      return 1;9    case "pickup":10      return 0;11  }12}13 14console.log(deliveryDays("pickup"));

Check your understanding

For each question, ask two things: which members of the union reach default, and what the code does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Each case narrows a union. After the last case, the value's type is never: nothing is left.
• Put the leftover where only never fits, and a forgotten case becomes an error that names it.
• assertNever(value: never): never does that in one shared helper, and throws a clear error if an unlisted value arrives while the page runs.
• Add a member to a union, and the errors list every switch that still needs a case.
• A return type like : number also catches a missing case in a switch with no default.
• A fallback default or a plain string type turns the check off.

Coming next: Type predicates & assertion functions. You'll write your own checks, like isUser(value), that narrow types the way case does here.