Discriminated unions

The pattern: a common literal tag

A discriminated (tagged) union is a union of object types that all share one property — the discriminant — whose type is a distinct literal in each member. Switching or branching on that property narrows the whole object to the matching variant:

type Result =
  | { kind: "ok"; data: string }
  | { kind: "error"; message: string }
  | { kind: "loading" };

function render(r: Result): string {
  switch (r.kind) {
    case "ok":
      return r.data;
      //     ^? (parameter) r: { kind: "ok"; data: string }
    case "error":
      return r.message;
      //     ^? r: { kind: "error"; message: string }
    case "loading":
      return "…";
  }
}

In each case, r is narrowed to the single member whose kind matches the literal, so r.data is reachable in "ok" and r.message in "error" — and nowhere else. This replaces the eight-combination boolean soup from the Hook with three mutually exclusive, fully-typed states. Illegal states (data present during an error) are now unrepresentable.

Requirements for narrowing to work

The checker recognises a discriminated union only when:

1. The discriminant is a literal type, not a widened primitive. kind: "ok" works; kind: string does not. (Recall the let/const widening from the narrowing lesson — copying the tag into a let breaks this.)
2. Every member declares the discriminant with a distinct literal. If two members share kind: "ok", the checker cannot tell them apart and merges their fields.
3. You branch on the discriminant itself (r.kind), not on a derived value.

// Broken: widened discriminant
type Bad = { kind: string; data: string } | { kind: string; err: string };
declare const b: Bad;
if (b.kind === "data") {
  b.data;
  // Error: Property 'data' does not exist on type 'Bad'.
  //   — kind is `string`, not a literal, so no narrowing happens
}

Exhaustiveness with assertNever

The real power is catching missing cases at compile time. When every variant has been handled, the value in the default branch has type never. A helper that accepts only never then forces a compile error the moment a new variant is added but left unhandled:

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

function render(r: Result): string {
  switch (r.kind) {
    case "ok": return r.data;
    case "error": return r.message;
    case "loading": return "…";
    default: return assertNever(r);
    //                          ^? r: never  — fine today
  }
}

Now add a fourth variant { kind: "retrying"; attempt: number } to Result and do not touch render. The default branch no longer sees never — it sees { kind: "retrying"; attempt: number }:

// Error: Argument of type '{ kind: "retrying"; attempt: number; }'
//   is not assignable to parameter of type 'never'.

Every switch that forgot the new case lights up red across the codebase. This is the single most valuable property of discriminated unions for senior work: the type system turns “find all the places that need updating” from a manual grep into a guaranteed compile error.

Why this beats booleans and in

The boolean-flags model (loading, error, data all independent) allows 2^n combinations, most of them illegal. The in-guard model from the previous lesson works but is fragile if keys overlap. A discriminant tag is unambiguous, self-documenting, and — crucially — exhaustiveness-checkable. It is the canonical shape for: API responses (ok/error), Redux/reducer actions (type field), UI/network state machines (idle/loading/success/failure), AST nodes, and parser tokens.

// Redux-style action — the discriminant is conventionally `type`
type Action =
  | { type: "increment"; by: number }
  | { type: "reset" };

function reduce(state: number, a: Action): number {
  switch (a.type) {
    case "increment": return state + a.by;
    case "reset": return 0;
    default: return assertNever(a);
  }
}