TypeScript Discriminated Unions

TypeScript Discriminated Unions

Model mutually exclusive states with discriminated unions and exhaustive narrowing

When to Use

• Representing states that cannot coexist (loading/success/error, open/closed)
• Replacing boolean flags or optional fields that create invalid state combinations
• Ensuring switch statements handle all possible cases
• Modeling domain events, API responses, or form states

Instructions

1. Define a discriminated union with a shared literal field (discriminant):

type Result<T> =
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }
  | { status: 'loading' };

2. Narrow with switch or if statements — TypeScript narrows the type automatically:

function handleResult<T>(result: Result<T>) {
  switch (result.status) {
    case 'success':
      console.log(result.data); // TypeScript knows data exists here
      break;
    case 'error':
      console.log(result.error); // TypeScript knows error exists here
      break;
    case 'loading':
      console.log('Loading...');
      break;
  }
}

3. Exhaustive checking with never — catch unhandled cases at compile time:

function assertNever(x: never): never {
  throw new Error(`Unexpected value: ${x}`);
}

function handleResult<T>(result: Result<T>): string {
  switch (result.status) {
    case 'success':
      return 'OK';
    case 'error':
      return 'FAIL';
    case 'loading':
      return 'WAIT';
    default:
      return assertNever(result);
    // If a new status is added, this line errors at compile time
  }
}

4. Replace boolean flags with discriminated unions:

// Bad: invalid states are possible (isLoading + error both true)
interface State {
  isLoading: boolean;
  data?: User;
  error?: Error;
}

// Good: each state is explicitly defined
type State =
  | { kind: 'idle' }
  | { kind: 'loading' }
  | { kind: 'success'; data: User }
  | { kind: 'error'; error: Error };

5. Model domain events:

type OrderEvent =
  | { type: 'ORDER_PLACED'; orderId: string; items: Item[] }
  | { type: 'PAYMENT_RECEIVED'; orderId: string; amount: number }
  | { type: 'ORDER_SHIPPED'; orderId: string; trackingNumber: string }
  | { type: 'ORDER_CANCELLED'; orderId: string; reason: string };

function processEvent(event: OrderEvent): void {
  switch (event.type) {
    case 'ORDER_PLACED':
      // event.items is available
      break;
    case 'ORDER_SHIPPED':
      // event.trackingNumber is available
      break;
  }
}

6. Combine with generics:

type ApiResponse<T> =
  | { ok: true; data: T; status: number }
  | { ok: false; error: string; status: number };

async function fetchUser(): Promise<ApiResponse<User>> {
  // ...
}

7. Discriminate on multiple properties when one is not enough:

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

8. Use in operator for narrowing when there is no explicit discriminant:

type Fish = { swim: () => void };
type Bird = { fly: () => void };

function move(animal: Fish | Bird) {
  if ('swim' in animal) {
    animal.swim(); // Narrowed to Fish
  }
}

Details

A discriminated union (also called a tagged union) is a union of types that share a common property with literal type values. TypeScript uses this property as a discriminant to narrow the type in conditional branches.

The discriminant property must be:

• Present on every member of the union
• A literal type (string literal, number literal, boolean literal)
• Unique per member (or at least narrow enough to distinguish)

Exhaustive checking patterns:

• switch with default: assertNever(x) — throws at runtime if an unhandled case is reached
• Assigning to never variable: const _exhaustive: never = x — compile-time only, no runtime overhead
• TypeScript's --noUncheckedIndexedAccess and strictNullChecks enhance exhaustiveness checking

Performance: Discriminated unions have zero runtime overhead beyond the discriminant property. The narrowing happens entirely at compile time.

Common naming conventions for discriminants:

• kind — for geometric shapes, node types, abstract syntax trees
• type — for events, actions, messages
• status — for state machines, API responses
• tag — for algebraic data types

Trade-offs:

• Discriminated unions make invalid states unrepresentable — but require more type definitions upfront
• Adding a new variant requires updating all switch statements — the exhaustive check catches this at compile time
• Deep nesting of discriminated unions can make type inference slow
• String literal discriminants are not refactoring-friendly — renaming a string literal requires finding all usage sites

Source

https://typescriptlang.org/docs/handbook/2/narrowing.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.