
A union type expresses "this value is one of these types." TypeScript narrows the union in each branch so every case is handled with the exact right shape.

<ExamplePair>
<ExampleProse>

The `|` operator creates a union. TypeScript enforces that you handle every member before using member-specific properties.

</ExampleProse>
<ExampleCode>

```ts
type StringOrNumber = string | number;

function format(value: StringOrNumber): string {
  if (typeof value === "string") {
    return value.toUpperCase(); // string methods available here
  }
  return value.toFixed(2); // number methods available here
}

console.log(format("hello")); // "HELLO"
console.log(format(3.14159)); // "3.14"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `&` operator creates an intersection - a type that satisfies all members simultaneously. Use intersections to combine two shapes into one without inheritance.

</ExampleProse>
<ExampleCode>

```ts
type Named = { name: string };
type Aged = { age: number };
type Person = Named & Aged;

const person: Person = { name: "Ada", age: 36 };

type WithTimestamp<T> = T & { createdAt: Date };
type TimestampedPerson = WithTimestamp<Person>;

const record: TimestampedPerson = {
  name: "Grace",
  age: 85,
  createdAt: new Date("1906-12-09"),
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

String literal unions model a closed set of allowed values - safer than `string` and more ergonomic than an enum. TypeScript checks exhaustiveness and provides autocomplete.

</ExampleProse>
<ExampleCode>

```ts
type Status = "pending" | "active" | "inactive" | "deleted";
type Direction = "north" | "south" | "east" | "west";
type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

function handleStatus(status: Status): string {
  if (status === "active") return "User is active";
  if (status === "deleted") return "User was deleted";
  return `Status: ${status}`;
}

// TypeScript error - "banned" is not assignable to type Status
// handleStatus("banned");
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A discriminated union adds a shared literal field (the discriminant) that TypeScript uses to narrow the active variant in a switch. Each branch gets the exact shape for that case - no optional fields, no casting.

</ExampleProse>
<ExampleCode>

```ts
type Shape =
  | { kind: "circle";    radius: number }
  | { kind: "rect";      width: number; height: number }
  | { kind: "triangle";  base: number;  height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
  }
}

console.log(area({ kind: "circle", radius: 5 })); // 78.53981633974483
console.log(area({ kind: "rect", width: 4, height: 6 })); // 24
```

</ExampleCode>
</ExamplePair>

<InProduction>
String literal unions are safer than `enum` for flag and variant types in most production codebases. They serialize to the same string in JSON without a compilation artifact, don't carry the numeric-enum falsy footgun (where `0` is falsy and `if (status)` silently skips the default state), and produce cleaner error messages when a value is wrong. Discriminated unions replace most class hierarchies: values serialize naturally to JSON, work with Redux and XState without adapters, and make adding new variants safe - as long as you include an exhaustiveness check (`default: const _: never = shape`) in every switch.
</InProduction>


Union (|), intersection (&), literal unions, and discriminated unions - the building blocks of TypeScript's variant-safe modeling.

Union Types


Generics let you write code that works across types while preserving type safety. A generic function says "I'll take a value of type T and give back a value of type T" - the caller determines what T is.

<ExamplePair>
<ExampleProse>

A generic function accepts a type parameter in angle brackets. TypeScript infers the type argument from the value you pass - you rarely need to specify it explicitly.

</ExampleProse>
<ExampleCode>

```ts
function identity<T>(value: T): T {
  return value;
}

const s = identity("hello"); // inferred: string
const n = identity(42);      // inferred: number

// Explicit type argument when inference isn't possible
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

const head = first([1, 2, 3]); // inferred: number | undefined
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Generic interfaces describe structures that work with any type. A `Stack<T>` can hold numbers, strings, or any other type - the interface enforces consistency.

</ExampleProse>
<ExampleCode>

```ts
interface Stack<T> {
  push(item: T): void;
  pop(): T | undefined;
  peek(): T | undefined;
  readonly size: number;
}

class ArrayStack<T> implements Stack<T> {
  private items: T[] = [];

  push(item: T): void { this.items.push(item); }
  pop(): T | undefined { return this.items.pop(); }
  peek(): T | undefined { return this.items[this.items.length - 1]; }
  get size(): number { return this.items.length; }
}

const stack = new ArrayStack<number>();
stack.push(1);
stack.push(2);
console.log(stack.peek()); // 2
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `extends` keyword constrains a type parameter. The function now only accepts values that satisfy the constraint - TypeScript can safely access constrained properties inside the body.

</ExampleProse>
<ExampleCode>

```ts
// Without constraint: TypeScript doesn't know T has .length
// function longest<T>(a: T, b: T): T { return a.length > b.length ? a : b; }

// With constraint: T must have a length property
function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("short", "longer"));    // "longer"
console.log(longest([1, 2], [3, 4, 5]));   // [3, 4, 5]

// Works on any type with .length - strings, arrays, typed arrays
function withId<T extends object>(item: T, id: string): T & { id: string } {
  return { ...item, id };
}

const user = withId({ name: "Ada" }, "user-1");
// user: { name: string; id: string }
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Default type parameters let callers omit the type argument when a sensible default exists - similar to default function parameters.

</ExampleProse>
<ExampleCode>

```ts
interface ApiResponse<T = unknown> {
  data: T;
  status: number;
  message: string;
}

// No type argument needed - defaults to unknown
const raw: ApiResponse = { data: null, status: 200, message: "OK" };

// Explicit type argument for typed responses
const typed: ApiResponse<{ id: string; name: string }> = {
  data: { id: "1", name: "Ada" },
  status: 200,
  message: "OK",
};
```

</ExampleCode>
</ExamplePair>

<InProduction>
Unbounded generics (`<T>`) accept any value, which pushes validation into the implementation and often forces unsafe casts. Constrain early: `<T extends object>`, `<T extends { id: string }>`, or `<T extends keyof SomeType>`. Understanding generics lets you read and write the standard utility types (`Partial<T>`, `Required<T>`, `Record<K, V>`, `ReturnType<F>`) instead of treating them as magic - they're all built on the same `<T extends ...>` mechanism. For REST API clients, a single generic `fetch<T>(url: string): Promise<T>` wrapper with a runtime Zod parse is the cleanest pattern: the generic provides IDE autocompletion; the parse catches schema drift before it propagates through the app.
</InProduction>


Type parameters, generic functions and interfaces, constraints with extends, and default type parameters.

Generics


A type alias gives a name to any type expression - a primitive, a union, an object shape, a function signature, or a combination of all of these. Aliases are more flexible than interfaces and are the right tool when the shape shouldn't be extended or merged.

<ExamplePair>
<ExampleProse>

`type` gives a name to any type, including unions and intersections that interfaces can't express.

</ExampleProse>
<ExampleCode>

```ts
type ID = string | number;
type Nullable<T> = T | null;
type Point = { x: number; y: number };
type Callback = (error: Error | null, result?: string) => void;

// Intersection - combines two shapes into one
type TimestampedPoint = Point & { timestamp: number };

const p: TimestampedPoint = { x: 1, y: 2, timestamp: Date.now() };
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Recursive types reference themselves. A tree node or nested JSON structure are the canonical cases.

</ExampleProse>
<ExampleCode>

```ts
type TreeNode = {
  value: number;
  left?: TreeNode;
  right?: TreeNode;
};

type JSONValue =
  | string
  | number
  | boolean
  | null
  | JSONValue[]
  | { [key: string]: JSONValue };

const tree: TreeNode = {
  value: 1,
  left: { value: 2 },
  right: { value: 3, left: { value: 4 } },
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Template literal types compose string literal types the same way template literals compose strings. They're used to derive event names, route patterns, or any string that follows a predictable structure.

</ExampleProse>
<ExampleCode>

```ts
type EventName = "click" | "focus" | "blur";
type HandlerName = `on${Capitalize<EventName>}`;
// HandlerName = "onClick" | "onFocus" | "onBlur"

type Route = "/users" | "/posts" | "/comments";
type ApiRoute = `/api${Route}`;
// ApiRoute = "/api/users" | "/api/posts" | "/api/comments"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A discriminated union uses a shared literal field (`type`) to let TypeScript narrow the active variant in a switch statement. Each branch gets the exact shape for that variant - no optional fields, no casting.

</ExampleProse>
<ExampleCode>

```ts
type Action =
  | { type: "ADD_ITEM";   payload: { id: string; name: string } }
  | { type: "REMOVE_ITEM"; id: string }
  | { type: "CLEAR" };

function reducer(state: string[], action: Action): string[] {
  switch (action.type) {
    case "ADD_ITEM":
      return [...state, action.payload.name]; // action.payload is typed here
    case "REMOVE_ITEM":
      return state.filter((_, i) => i !== parseInt(action.id)); // action.id is typed here
    case "CLEAR":
      return [];
  }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Discriminated unions replace most class hierarchies in TypeScript codebases. They serialize cleanly to JSON (no methods, no prototype chains), work naturally with Redux and XState, and make adding new variants safe - the compiler forces you to handle every case in every switch. The key discipline: always include a `default: const _: never = action` exhaustiveness check so that adding a new variant to the union without updating every switch is a compile error, not a silent runtime bug.
</InProduction>


Type aliases vs interfaces, recursive types, template literal types, and discriminated unions.