Discriminated Unions - TypeScript Expert - ggcoder.com

Definition: What Is a Discriminated Union

A discriminated union (also called a tagged union) is a union of object types where every member shares a common literal-typed property called the discriminant or tag. TypeScript uses this property to narrow the union to a single member without any type assertion.

discriminated-union-basics.ts

1// Each member has a 'kind' discriminant with a unique literal value2type Shape =3  | { kind: "circle";    radius: number }4  | { kind: "rectangle"; width: number; height: number }5  | { kind: "triangle";  base: number;  height: number };67function area(shape: Shape): number {8  switch (shape.kind) {9    case "circle":10      // shape is { kind: "circle"; radius: number } here11      return Math.PI * shape.radius ** 2;12    case "rectangle":13      return shape.width * shape.height;14    case "triangle":15      return 0.5 * shape.base * shape.height;16  }17}

The discriminant key can be any property name (kind, type, tag, status…) as long as it appears in every member and holds a unique literal value per member.

Exhaustiveness Checking with never and assertNever

When you add a new variant to a union, you want TypeScript to force you to handle it. The assertNever pattern achieves this by assigning the default branch to a parameter typed as never — any unhandled variant causes a compile error.

assert-never.ts

1function assertNever(value: never, message?: string): never {2  throw new Error(message ?? `Unhandled variant: ${JSON.stringify(value)}`);3}45type Shape =6  | { kind: "circle";    radius: number }7  | { kind: "rectangle"; width: number; height: number }8  | { kind: "triangle";  base: number;  height: number };910function area(shape: Shape): number {11  switch (shape.kind) {12    case "circle":    return Math.PI * shape.radius ** 2;

Tip

assertNever should throw at runtime as a safety net: if you bypass the TypeScript error with a cast, the unhandled variant fails loudly at runtime instead of silently returning undefined.

Modeling State: API Results and State Machines

Discriminated unions are the ideal tool for modeling mutually exclusive states such as an API request lifecycle (loading / success / error) or steps in a state machine.

api-result-state-machine.ts

1// API result — impossible to access 'data' when status is "error"2type ApiResult<T> =3  | { status: "loading" }4  | { status: "success"; data: T }5  | { status: "error";   error: Error };67function render<T>(result: ApiResult<T>): string {8  switch (result.status) {9    case "loading": return "Loading…";10    case "success": return JSON.stringify(result.data); // data available here11    case "error":   return `Error: ${result.error.message}`; // error available here12    default:        return assertNever(result);

This pattern makes invalid states unrepresentable — you cannot have both data and error simultaneously, and you cannot accidentally access data when status is "loading".

Narrowing in if and switch

TypeScript narrows discriminated unions in both switch and if/else. After each discriminant check, TypeScript knows exactly which union member is in scope.

narrowing-if-switch.ts

1type Notification =2  | { kind: "email";   to: string;  subject: string }3  | { kind: "sms";     to: string;  body: string }4  | { kind: "push";    token: string; title: string };56// if/else narrowing7function sendNotification(n: Notification): void {8  if (n.kind === "email") {9    // n: { kind: "email"; to: string; subject: string }10    console.log(`Email to ${n.to}: ${n.subject}`);11  } else if (n.kind === "sms") {12    // n: { kind: "sms"; to: string; body: string }

Warning

Why must the discriminant be a literal type? If kind is typed as string (broad), TypeScript cannot narrow because any value qualifies. Only unique literal types (string literals, number literals, boolean) let TypeScript eliminate other members.

Common Mistakes

Non-Literal Discriminant

If the discriminant property is declared with a broad type like string or number, TypeScript cannot use it for narrowing. Always use specific literal values.

non-literal-discriminant.ts

1// WRONG — 'type' is string, not a literal — no narrowing possible2type BadAction =3  | { type: string; payload: string }4  | { type: string; id: number };56function handle(a: BadAction) {7  if (a.type === "add") {8    a.payload; // Error: Property 'payload' does not exist on type 'BadAction'9  }10}1112// CORRECT — each type is a distinct string literal

Warning

Another common mistake is omitting assertNever in the default branch. A silent default: break hides unhandled variants. Always use assertNever to get a compile error when the union grows.

Summary

A discriminated union is a union of object types sharing a common literal property called the discriminant

TypeScript narrows precisely when you check the discriminant in a switch or if/else

Use assertNever in the default branch to enforce exhaustiveness at compile time

The discriminant must be a literal type — broad types like string will not enable narrowing

Discriminated unions make invalid states unrepresentable — ideal for API results, Redux actions, and state machines

Adding a new variant to a union with assertNever automatically creates compile errors at every site that needs updating

1// Each member has a 'kind' discriminant with a unique literal value2type Shape =3 | { kind: "circle"; radius: number }4 | { kind: "rectangle"; width: number; height: number }5 | { kind: "triangle"; base: number; height: number };67function area(shape: Shape): number {8 switch (shape.kind) {9 case "circle":10 // shape is { kind: "circle"; radius: number } here11 return Math.PI * shape.radius ** 2;12 case "rectangle":13 return shape.width * shape.height;14 case "triangle":15 return 0.5 * shape.base * shape.height;16 }17}

1function assertNever(value: never, message?: string): never {2 throw new Error(message ?? `Unhandled variant: ${JSON.stringify(value)}`);3}45type Shape =6 | { kind: "circle"; radius: number }7 | { kind: "rectangle"; width: number; height: number }8 | { kind: "triangle"; base: number; height: number };910function area(shape: Shape): number {11 switch (shape.kind) {12 case "circle": return Math.PI * shape.radius ** 2;

1// API result — impossible to access 'data' when status is "error"2type ApiResult<T> =3 | { status: "loading" }4 | { status: "success"; data: T }5 | { status: "error"; error: Error };67function render<T>(result: ApiResult<T>): string {8 switch (result.status) {9 case "loading": return "Loading…";10 case "success": return JSON.stringify(result.data); // data available here11 case "error": return `Error: ${result.error.message}`; // error available here12 default: return assertNever(result);

1type Notification =2 | { kind: "email"; to: string; subject: string }3 | { kind: "sms"; to: string; body: string }4 | { kind: "push"; token: string; title: string };56// if/else narrowing7function sendNotification(n: Notification): void {8 if (n.kind === "email") {9 // n: { kind: "email"; to: string; subject: string }10 console.log(`Email to ${n.to}: ${n.subject}`);11 } else if (n.kind === "sms") {12 // n: { kind: "sms"; to: string; body: string }

1// WRONG — 'type' is string, not a literal — no narrowing possible2type BadAction =3 | { type: string; payload: string }4 | { type: string; id: number };56function handle(a: BadAction) {7 if (a.type === "add") {8 a.payload; // Error: Property 'payload' does not exist on type 'BadAction'9 }10}1112// CORRECT — each type is a distinct string literal