Discriminated Unions

Also Known As

TL;DR

Explanation

Each member of the union has a shared property with a unique literal type (kind, type, status, tag). TypeScript uses the discriminant to narrow inside switch/if blocks with no runtime overhead beyond the field check. Pattern replaces: class hierarchies, boolean flags, optional fields that are only set in certain states. Exhaustiveness: add a default: const x: never = value branch to get a compile error when a new union member is added but not handled. Common in Redux actions, API response variants, result types (Ok | Err), FSM states.

Diagram

stateDiagram-v2
    [*] --> loading
    loading --> success : data fetched
    loading --> error : request failed
    success --> [*]
    error --> loading : retry

Watch Out

Common Misconception

Why It Matters

Common Mistakes

• Using a boolean discriminant — booleans only give two variants; use a string literal for extensibility.
• Forgetting the never exhaustiveness check — new variants added later silently fall through.
• Putting shared fields on the union level instead of each member — breaks narrowing.
• Using type assertions instead of discriminant checks — bypasses the safety.

Avoid When

• When variants share most fields and only differ in one optional aspect — a simple optional field is cleaner.
• When the number of variants changes very frequently and exhaustiveness checking becomes a maintenance burden.

When To Use

• Modelling FSM states, async request lifecycle (loading/success/error), or Redux action types.
• Any time you have mutually exclusive variants that carry different data.

Code Examples

// Impossible state possible: what if both error and data are set?
type ApiResponse = {
    loading: boolean;
    data?: User;
    error?: string;
};

if (response.data) {
    // error might also be set — ambiguous

// Discriminated union — impossible states are impossible
type ApiResponse =
    | { status: 'loading' }
    | { status: 'success'; data: User }
    | { status: 'error';   message: string };

function render(r: ApiResponse) {
    switch (r.status) {
        case 'loading': return <Spinner />;
        case 'success': return <UserCard user={r.data} />;
        case 'error':   return <ErrorMsg text={r.message} />;
        default:
            const _: never = r; // compile error if a variant is unhandled
    }
}

References

• ↗ https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions

Tags

Related Terms