Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Literal and Object Types

TypeScript discriminated unions

Reference for TypeScript discriminated unions: a shared literal tag, narrowing with switch and if, exhaustiveness with never, and modelling states and results.

A discriminated union (also called a tagged union) is a union of object types that all share one property with a distinct literal type, the discriminant. When you check that property, TypeScript narrows the whole value to the matching member, so the other properties become available with the right types.

It is the idiomatic way to model "one of several shapes": results that are either success or failure, state machines, UI events, AST nodes and API responses.

TypeScript
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

Try it

TypeScript Narrowing with switch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Exhaustiveness and results

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
type U =
  | { tag: "a"; /* members of A */ }
  | { tag: "b"; /* members of B */ };

if (u.tag === "a") { /* u is A here */ }
Requirement Description
Discriminant property Present in every member, with a literal type (string, number, boolean, null, undefined, or an enum member).
Distinct values Each member must have a different literal so a check identifies exactly one member.
Check forms ===, !==, switch, in on the discriminant, and truthiness for true/false discriminants.

Edge cases: if the tag type is plain string, there is no narrowing. A tag that is a union of literals in one member (kind: "a" | "b") still narrows, but to that member only. Destructuring the tag and the payload separately works since TypeScript 4.6 when they come from a const destructuring of a union.

Usage notes

  • Exhaustiveness: assign the leftover value to a never variable in the default branch; adding a member to the union then produces a compile error at every unhandled switch.
  • Return type inference: a function with a complete switch and no default can have a declared return type without a final return; the compiler knows all paths return.
  • Booleans as tags: { ok: true } / { ok: false } is a valid discriminant, as the second example shows.
  • Runtime data: the compiler trusts your types; validate JSON from the network before treating it as a discriminated union.
  • Prefer over optional fields: { value?: T; error?: string } allows impossible combinations; a tagged union does not.
  • Versus classes: unions of plain objects serialize easily and need no instanceof.
  • Naming: common tags are kind, type, tag and status; pick one and stay consistent.