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.
type Shape = | { kind: "circle"; radius: number } | { kind: "rect"; width: number; height: number };
Try it
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.
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
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
nevervariable in thedefaultbranch; 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,tagandstatus; pick one and stay consistent.