Discriminated Unions and Exhaustive Checks

A discriminated union is a union of object types that share one literal property – the "tag" – like status: "loading" | "success" | "error". Checking the tag tells TypeScript exactly which shape you have. It's one of the most useful patterns in TypeScript: request states in React, Redux actions, payment results and messages all use it.

A discriminated union

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rectangle"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":    return Math.PI * shape.radius ** 2;      // shape: circle
    case "rectangle": return shape.width * shape.height;       // shape: rectangle
    case "triangle":  return 0.5 * shape.base * shape.height;  // shape: triangle
  }
}

const shapes: Shape[] = [
  { kind: "circle", radius: 1 },
  { kind: "rectangle", width: 3, height: 4 },
  { kind: "triangle", base: 6, height: 2 },
];
for (const s of shapes) console.log(s.kind, area(s).toFixed(2));

circle 3.14
rectangle 12.00
triangle 6.00

Each member has a kind with a different literal value. Inside each case, TypeScript knows the exact member, so shape.radius is only allowed in the circle branch.

Exhaustive checks with never

What happens when someone adds a new shape later? Make the compiler find every switch that doesn't handle it:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "hexagon"; side: number };          // newly added

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

function perimeter(shape: Shape): number {
  switch (shape.kind) {
    case "circle": return 2 * Math.PI * shape.radius;
    case "square": return 4 * shape.side;
    default:       return assertNever(shape);    // hexagon reaches here
  }
}
console.log(perimeter({ kind: "square", side: 2 }));

main.ts(14,39): error TS2345: Argument of type '{ kind: "hexagon"; side: number; }' is not assignable to parameter of type 'never'.

With the hexagon case added, the code compiles and runs:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "hexagon"; side: number };

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

function perimeter(shape: Shape): number {
  switch (shape.kind) {
    case "circle":  return 2 * Math.PI * shape.radius;
    case "square":  return 4 * shape.side;
    case "hexagon": return 6 * shape.side;
    default:        return assertNever(shape);
  }
}
console.log(perimeter({ kind: "square", side: 2 }), perimeter({ kind: "hexagon", side: 1.5 }));

8 9

Request state: impossible states made impossible

interface Course { title: string; lessons: number }

// Bad: { loading: boolean; data?: Course[]; error?: string } allows loading + error + data at once.
type RequestState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: Course[] }
  | { status: "error"; error: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "idle":    return "Click to load courses";
    case "loading": return "Loading…";
    case "success": return state.data.map((c) => `${c.title} (${c.lessons})`).join(", ");
    case "error":   return `Something went wrong: ${state.error}`;
  }
}

const states: RequestState[] = [
  { status: "idle" },
  { status: "loading" },
  { status: "success", data: [{ title: "TypeScript", lessons: 20 }, { title: "SQL", lessons: 30 }] },
  { status: "error", error: "Network timeout" },
];
for (const s of states) console.log(render(s));

Click to load courses
Loading…
TypeScript (20), SQL (30)
Something went wrong: Network timeout

Practice

Summary