
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.

Interfaces


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


TypeScript infers types from the values you assign - you rarely need to annotate every variable. But inference has rules, and knowing when it widens a type vs narrows it prevents subtle bugs.

<ExamplePair>
<ExampleProse>

`const` infers a narrow literal type. `let` infers a wide primitive type because the value can change.

</ExampleProse>
<ExampleCode>

```ts
const lang = "typescript";  // type: "typescript" (string literal)
let lang2 = "typescript";   // type: string (widened)

const count = 42;            // type: 42 (numeric literal)
let count2 = 42;             // type: number (widened)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Object and array literals inferred with `const` still get wide types for their properties - the object reference is const, but the properties are mutable. Use `as const` to lock everything down to literal types.

</ExampleProse>
<ExampleCode>

```ts
const config = { env: "production", port: 3000 };
// config.env: string (NOT "production")
// config.port: number (NOT 3000)

const config2 = { env: "production", port: 3000 } as const;
// config2.env: "production"
// config2.port: 3000
// All properties are readonly - config2.env = "staging" is a type error
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

TypeScript infers function return types automatically. Annotating the return type explicitly is optional but documents intent and catches mistakes when the function body changes.

</ExampleProse>
<ExampleCode>

```ts
// inferred return type: number
function add(a: number, b: number) {
  return a + b;
}

// explicit return type - documents intent, errors if the body returns something else
function greet(name: string): string {
  return `Hello, ${name}!`;
}

// explicit return type: Promise<number>
async function fetchCount(): Promise<number> {
  return 42;
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The widening of object literals is one of the most common TypeScript footguns in configuration code. `const config = { env: 'production' }` gives `config.env` the type `string`, not `'production'`. When this config object is passed to a function expecting `{ env: 'production' | 'staging' }`, TypeScript rejects it with a confusing error. Fix it at the source with `as const` or an explicit type annotation. This pattern appears constantly in feature flags, environment configs, and route definitions - getting it right once prevents a class of "works at runtime but fails type checking" surprises.
</InProduction>


How TypeScript infers types from assignments - const vs let narrowing, as const, and return type inference.