
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.

Type Aliases


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


Interfaces describe the shape of an object. TypeScript uses structural typing - any object that has the required fields satisfies the interface, regardless of what class or constructor created it.

<ExamplePair>
<ExampleProse>

An interface declares a set of required properties and their types. Optional properties use `?`; readonly properties use `readonly` and cannot be reassigned after creation.

</ExampleProse>
<ExampleCode>

```ts
interface User {
  id: string;
  name: string;
  email?: string;         // optional
  readonly createdAt: Date; // cannot be changed after assignment
}

const user: User = {
  id: "u_1",
  name: "Alice",
  createdAt: new Date(),
};

user.name = "Bob";          // ok - name is mutable
// user.createdAt = new Date(); // error - readonly
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Interfaces can extend other interfaces to compose shapes without repeating fields. A class can implement an interface to guarantee it satisfies the contract.

</ExampleProse>
<ExampleCode>

```ts
interface Entity {
  id: string;
  createdAt: Date;
  updatedAt: Date;
}

interface Product extends Entity {
  name: string;
  priceInCents: number;
  sku: string;
}

// Any object with all required fields satisfies Product - no class needed
const widget: Product = {
  id: "p_1",
  name: "Widget",
  priceInCents: 999,
  sku: "WGT-001",
  createdAt: new Date(),
  updatedAt: new Date(),
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Declaration merging: declaring the same interface twice merges the two declarations into one. This is how library authors augment global types without modifying the original source.

</ExampleProse>
<ExampleCode>

```ts
interface Config {
  port: number;
}

interface Config {
  host: string; // merged - both declarations combine
}

// Config now requires: { port: number; host: string }
const config: Config = { port: 3000, host: "localhost" };
```

</ExampleCode>
</ExamplePair>

<InProduction>
Interfaces are open by design - declaration merging is how libraries like Express augment `Request` to add `req.user` without forking the types. That power cuts both ways: if you accidentally re-declare an interface you own, TypeScript silently merges the declarations rather than erroring, which can add unexpected properties to an otherwise closed contract. For shapes you own and don't want extended by consumers or test utilities, prefer type aliases - they're closed and don't merge.
</InProduction>


Declaring interfaces - optional and readonly properties, extending interfaces, and declaration merging.