Union Types and Discriminated Unions

One Variable, Multiple Possible Types

In JavaScript, a variable can hold different types at different times. A function might return a string on success and null on failure. An API response might be a user object or an error object. TypeScript models this reality with union types.

But raw unions are clumsy. The real power comes from discriminated unions — a pattern that turns TypeScript's type system into a state machine verifier.

Basic Union Types

// A value that can be one of several types
type StringOrNumber = string | number;

function format(value: StringOrNumber): string {
  // Can't call .toUpperCase() — might be a number
  // Can't call .toFixed() — might be a string
  // Must narrow first
  if (typeof value === "string") {
    return value.toUpperCase(); // OK — narrowed to string
  }
  return value.toFixed(2); // OK — narrowed to number
}

// Union of literals — extremely useful for finite sets
type Direction = "north" | "south" | "east" | "west";
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
type LogLevel = "debug" | "info" | "warn" | "error";

Discriminated Unions — The Real Power

A discriminated union is a union where every member has a common property (the discriminant) with a unique literal type:

// Each state has a 'status' discriminant with a unique literal value
type RequestState =
  | { status: "idle" }
  | { status: "loading"; startedAt: number }
  | { status: "success"; data: unknown; duration: number }
  | { status: "error"; error: Error; retryCount: number };

function renderRequest(state: RequestState) {
  switch (state.status) {
    case "idle":
      return "Ready to fetch";
    case "loading":
      return `Loading since ${state.startedAt}`; // startedAt available
    case "success":
      return `Got data in ${state.duration}ms`; // data, duration available
    case "error":
      return `Error: ${state.error.message} (retry #${state.retryCount})`; // error, retryCount available
  }
}

After checking state.status, TypeScript knows exactly which variant you're in and which properties are available. No optional properties, no null checks, no casting.

Discriminated Unions as State Machines

This is where discriminated unions shine in production. Instead of boolean flags and optional properties, model your state as a union:

// BAD — boolean soup
interface FormState {
  isSubmitting: boolean;
  isSuccess: boolean;
  isError: boolean;
  data?: ResponseData;
  error?: Error;
}
// Problem: isSubmitting && isSuccess — is that valid? TypeScript can't tell.
// Problem: data exists when isError is true? No compile-time protection.

// GOOD — discriminated union
type FormState =
  | { status: "idle" }
  | { status: "validating"; fields: Record<string, string> }
  | { status: "submitting"; fields: Record<string, string> }
  | { status: "success"; data: ResponseData }
  | { status: "error"; error: Error; fields: Record<string, string> };

// Impossible states are literally unrepresentable
// You can never have data AND error simultaneously
// You can never be submitting AND idle simultaneously

Exhaustive Checking with never

The never type ensures you handle every variant in a discriminated union:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    case "triangle":
      return 0.5 * shape.base * shape.height;
    default: {
      // If all cases are handled, shape is 'never' here
      const _exhaustive: never = shape;
      return _exhaustive;
    }
  }
}

// If someone adds a new variant:
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "triangle"; base: number; height: number }
  | { kind: "rectangle"; width: number; height: number }; // NEW

// The default case now ERROR:
// Type '{ kind: "rectangle"; width: number; height: number }' is not assignable to type 'never'
// ^ Forces you to add the missing case

function assertNever(value: never, message?: string): never {
  throw new Error(message ?? `Unexpected value: ${JSON.stringify(value)}`);
}

// Usage
default:
  return assertNever(shape, `Unknown shape kind: ${(shape as any).kind}`);

Production Scenario: API Response Handling

// Type-safe API responses with discriminated unions
type ApiResponse<T> =
  | { ok: true; data: T; status: number }
  | { ok: false; error: { code: string; message: string }; status: number };

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  const body = await res.json();

  if (res.ok) {
    return { ok: true, data: body as User, status: res.status };
  }
  return { ok: false, error: body, status: res.status };
}

// Caller gets exhaustive type safety
async function displayUser(id: string) {
  const result = await fetchUser(id);

  if (result.ok) {
    // result.data is User — no optional chaining needed
    console.log(result.data.name);
  } else {
    // result.error is { code: string; message: string }
    console.error(`${result.error.code}: ${result.error.message}`);
  }
}

// React component with discriminated union state
type UserPageState =
  | { phase: "loading" }
  | { phase: "loaded"; user: User; posts: Post[] }
  | { phase: "error"; message: string; retry: () => void }
  | { phase: "not-found" };

function UserPage({ state }: { state: UserPageState }) {
  switch (state.phase) {
    case "loading":
      return <Skeleton />;
    case "loaded":
      return <UserProfile user={state.user} posts={state.posts} />;
    case "error":
      return <ErrorBanner message={state.message} onRetry={state.retry} />;
    case "not-found":
      return <NotFoundPage />;
  }
}

Refactor Boolean Soup to Discriminated Union

type ModalState =
  | { phase: "closed" }
  | { phase: "opening"; content: React.ReactNode }
  | { phase: "open"; content: React.ReactNode }
  | { phase: "confirming"; content: React.ReactNode; onConfirm: () => void }
  | { phase: "error"; content: React.ReactNode; error: string }
  | { phase: "closing" };