Union Types

1What a Union Type Is

A union type describes a value that can be one of several types, written with |.

let id: number | string;
id = 42;      // ✅
id = "abc42"; // ✅
id = true;    // ❌ boolean is not part of the union

2You Can Only Use What EVERY Member Has in Common

function printId(id: number | string) {
  console.log(id.toUpperCase()); // ❌ error — toUpperCase doesn't exist on `number`
}

Without knowing which member of the union a value actually is, TypeScript only allows operations valid for all possible members — accessing .toUpperCase() is unsafe because it would crash if id turned out to be a number at runtime. This is exactly the motivation for narrowing (its own topic): checking which specific member you have before using type-specific operations.

function printId(id: number | string) {
  if (typeof id === "string") {
    console.log(id.toUpperCase()); // ✅ narrowed to `string` inside this block
  } else {
    console.log(id.toFixed(2));     // ✅ narrowed to `number` here
  }
}

3Unions of Literal Types

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction) { /* ... */ }
move("up");       // ✅
move("diagonal"); // ❌ not one of the allowed literals

This pattern — a union of specific string/number literals — is the TypeScript equivalent of an enum in many codebases (compare with the Enums topic), and is extremely common for representing a fixed, closed set of allowed values.

4Discriminated Unions — the Most Important Union Pattern

A discriminated union is a union of object types that all share one common property (the "discriminant" or "tag") with a distinct literal value per variant — this lets TypeScript narrow the entire object shape based on checking just that one property.

interface LoadingState { status: "loading"; }
interface SuccessState { status: "success"; data: string; }
interface ErrorState { status: "error"; message: string; }

type FetchState = LoadingState | SuccessState | ErrorState;

function render(state: FetchState) {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data;      // ✅ narrowed to SuccessState — .data is safely accessible
    case "error":
      return state.message;    // ✅ narrowed to ErrorState — .message is safely accessible
  }
}

Checking state.status narrows the checker's understanding of state's entire shape in each branch, not just the status property itself — this is the standard, idiomatic way to model state machines, API response shapes, and variant data in TypeScript.

5Union vs Intersection (Quick Contrast)

type UnionExample = { a: number } | { b: string };        // EITHER shape — has a OR b (or check first)
type IntersectionExample = { a: number } & { b: string };  // BOTH shapes — has a AND b

Full depth on intersections is their own topic — the short version: | means "could be any of these," & means "must satisfy all of these simultaneously."

// assigning INTO a union: value must match AT LEAST ONE member
let id: number | string = 42; // ✅ number matches one member

// assigning a union OUT to a narrower target: EVERY member must match
function needsString(s: string) {}
declare const maybe: number | string;
// needsString(maybe); // ❌ number doesn't satisfy string — fails because NOT EVERY member matches

type A = string | string;      // simplifies to just `string`
type B = string | any;          // simplifies to `any` — any absorbs everything
type C = "a" | "b" | string;     // simplifies to just `string` — the wider type absorbs the literals

⚠️ Common Pitfalls

1. Calling a member-specific method without narrowing first — always a compile error; you must narrow (via typeof, in, a discriminant check, etc.) before accessing anything not common to every union member.
2. Forgetting to add a default/exhaustiveness check in a switch — an unhandled new variant added to the union later won't be caught unless you use the exhaustiveness-checking pattern (assigning the unreachable case to a never-typed variable — covered in the Any/Unknown/Never topic).
3. Widening a literal union accidentally — assigning a Direction-typed value to a plain let string variable widens it, losing the restriction (see the Type Inference topic's widening rules).
4. Designing a discriminated union without a shared, uniquely-literal discriminant property — narrowing only works this cleanly when one property has a distinct literal type per variant; a shared non-literal property (like a plain string "status") won't narrow anything.

📋 Quick Reference

A | B                     → value is A OR B — only shared members usable without narrowing
{ status: "x", ... } | ...  → discriminated union — switch/if on the shared literal tag to narrow
typeof / in / tag check      → narrows a union down to specific member(s)

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

Source: ts_union_types_theory.md · generated by tools/build_lessons.py