Unions, discriminated unions and exhaustiveness

Make the impossible states unwritable

A request is often modelled with independent flags:

1type User = { name: string }2 3type Loose = { loading: boolean; data?: User; error?: string }

Nothing stops { loading: true, error: "timeout", data: someUser }, and every reader has to guess which field wins. A union lists the states that really exist:

1type User = { name: string }2 3type Request =4  | { status: "idle" }5  | { status: "loading" }6  | { status: "success"; data: User }7  | { status: "failure"; error: string }8 9function label(r: Request): string {10  switch (r.status) {11    case "idle":12      return "Not started"13    case "loading":14      return "Loading..."15    case "success":16      return `Hello, ${r.data.name}` // r is the success member here17    case "failure":18      return `Failed: ${r.error}`19  }20}

In each case, r is narrowed to the member with that status, so r.data exists only where it can. There is no way to build a success without data, or a failure with it.

Why the tag works

Types are erased, so the checker can only narrow on things that survive to runtime. The tag is ordinary data in the object, and the switch is ordinary JavaScript. Here is the same function after compilation, running:

The last call prints undefined: at runtime nothing stops a value that the type does not allow, and the switch simply falls off the end. The compiler can protect you from that, but only inside the code it checks.

Exhaustiveness checking

Add a default branch that assigns the value to never:

1type Request =2  | { status: "idle" }3  | { status: "loading" }4  | { status: "retrying"; attempt: number }5 6function label(r: Request): string {7  switch (r.status) {8    case "idle":9      return "Not started"10    case "loading":11      return "Loading..."12    default: {13      const unreachable: never = r // Error: Type '{ status: "retrying"; attempt: number; }' is not assignable to type 'never'14      return unreachable15    }16  }17}

With every member handled, the type left in default is never (no possible value), and the assignment compiles. When someone adds retrying, every switch that forgot it fails to compile at exactly that line. With strict on, the checker also complains when a function with a string return type can fall off the end of an incomplete switch, but the never line names the missing case and works in code that doesn't return.

Prefer literal tags ("success") over booleans for anything with more than two states, and keep the tag name the same across the union so one switch covers it.