
TypeScript is JavaScript with a type layer on top. Every TypeScript file compiles to JavaScript before it runs - understanding the two execution modes (run directly with `tsx`, compile with `tsc`) is the first thing to nail down.

<ExamplePair>
<ExampleProse>

`tsx` runs TypeScript directly without a separate compile step. It uses esbuild under the hood, strips types at runtime, and is the fastest way to run a `.ts` file in development.

</ExampleProse>
<ExampleCode>

```ts
// hello.ts
const message: string = "Hello, World!";
console.log(message);
```

```shell
$ npx tsx hello.ts
Hello, World!
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`tsc` compiles TypeScript to JavaScript and performs full type checking. The output is plain `.js` that any Node.js version can run.

A minimal `tsconfig.json` tells `tsc` which files to compile and what JavaScript version to target.

</ExampleProse>
<ExampleCode>

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "dist"
  }
}
```

```shell
$ npx tsc
$ node dist/hello.js
Hello, World!
```

</ExampleCode>
</ExamplePair>

<InProduction>
`ts-node` has significant startup cost because it uses the TypeScript compiler for every run. Prefer `tsx` (esbuild-backed) in development and scripts - it starts in milliseconds. For production Node.js services, always precompile with `tsc` and ship the `.js` output. Never ship `.ts` files to production: runtime transpilation adds startup latency, and tools like AWS Lambda and Google Cloud Run optimize for cold-start times where every millisecond counts.
</InProduction>


Running TypeScript with tsx and compiling with tsc - the two modes every TypeScript project uses.

Hello, World


TypeScript adds static types on top of JavaScript's runtime types. Most annotations are optional - the compiler infers types from assignments - but knowing the full type vocabulary lets you annotate precisely when inference isn't enough.

<ExamplePair>
<ExampleProse>

The primitive types mirror JavaScript's built-in values. Type annotations appear after the variable name with a colon.

</ExampleProse>
<ExampleCode>

```ts
const name: string = "Alice";
const age: number = 30;
const active: boolean = true;
const nothing: null = null;
const missing: undefined = undefined;
const id: symbol = Symbol("id");
const big: bigint = 9007199254740993n;
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`any` opts a value out of type checking entirely - the compiler stops tracking it. `unknown` is the safer alternative: values are type-checked, but you must narrow the type before using them.

</ExampleProse>
<ExampleCode>

```ts
// any: no type checking - avoid in new code
let loose: any = "hello";
loose = 42;          // no error
loose.toFixed(2);    // no error - even if loose is a string

// unknown: must narrow before use
let raw: unknown = JSON.parse('{"x": 1}');
// raw.x  ← error: Object is of type 'unknown'

if (typeof raw === "object" && raw !== null && "x" in raw) {
  console.log((raw as { x: number }).x); // safe
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`never` is TypeScript's bottom type - a type with no values. It appears in two situations: functions that never return (they always throw or loop forever), and union branches that TypeScript has fully exhausted during narrowing.

The `assertUnreachable` helper is what makes `never` useful in practice. Its parameter type is `never`, so if TypeScript believes any value could reach that call, you get a compile error - not a runtime crash.

</ExampleProse>
<ExampleCode>

```ts
// A function that never returns has return type `never`
function fail(message: string): never {
  throw new Error(message);
}

// x: never means "this branch is impossible - the compiler guarantees it"
function assertUnreachable(x: never): never {
  return fail(`Unhandled case: ${JSON.stringify(x)}`);
}

type Direction = "north" | "south" | "east" | "west";

function move(dir: Direction): string {
  switch (dir) {
    case "north": return "moving north";
    case "south": return "moving south";
    case "east":  return "moving east";
    case "west":  return "moving west";
    default: return assertUnreachable(dir);
    // ↑ dir is `never` here because all cases are handled.
    // Add "northeast" to Direction and this line immediately errors.
  }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The real payoff shows up on a team. When you add a new variant to a shared union - a new event type, a new API status, a new feature flag - TypeScript errors at every unhandled `switch` across the entire codebase. You can't ship until every callsite is updated. `never` turns a runtime oversight into a compile-time requirement.

<ProdNote>
Add `assertUnreachable` to `utils/types.ts` and import it in every switch. When a teammate adds a new union variant, every unhandled switch fails to compile - the bug is caught in CI, not in production.
</ProdNote>

</ExampleProse>
<ExampleCode>

```ts
type ApiEvent =
  | { type: "success"; data: { id: string; name: string } }
  | { type: "error"; code: number; message: string }
  | { type: "loading" };

function handleEvent(event: ApiEvent): void {
  switch (event.type) {
    case "success":
      renderUser(event.data);
      break;
    case "error":
      showError(event.code, event.message);
      break;
    case "loading":
      showSpinner();
      break;
    default:
      assertUnreachable(event);
  }
}

// A teammate adds `{ type: "cancelled" }` to ApiEvent.
// The default branch above errors immediately:
//   Argument of type '{ type: "cancelled" }' is not
//   assignable to parameter of type 'never'.
// No runtime bug. No forgotten branch. Caught at CI.
```

</ExampleCode>
</ExamplePair>

<InProduction>
Ban `any` with `@typescript-eslint/no-explicit-any` from day one. Use `unknown` at every boundary where you don't control the shape - JSON.parse, API responses, message queues - and narrow before you use it. `any` lets bugs through silently; `unknown` makes the compiler ask you to prove it's safe first.
</InProduction>


TypeScript's built-in scalar types - string, number, boolean, null, undefined, symbol, bigint, any, unknown, never.

Basic Types


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.

Type Inference


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


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


TypeScript types every part of a function signature - parameters, return value, and the function itself as a value. Most types are inferred; you only annotate what TypeScript can't figure out on its own.

<ExamplePair>
<ExampleProse>

Parameter types are annotated after the name. Return types are inferred from the return statement, but an explicit annotation is useful for documentation and to catch mistakes early.

</ExampleProse>
<ExampleCode>

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

// Arrow function with explicit return type
const multiply = (a: number, b: number): number => a * b;

// Return type inferred as string
const greet = (name: string) => `Hello, ${name}!`;

console.log(add(2, 3));      // 5
console.log(multiply(4, 5)); // 20
console.log(greet("Ada"));   // Hello, Ada!
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Optional parameters use `?` after the name. Default parameters use `=`. TypeScript infers the type from the default value - no annotation needed.

</ExampleProse>
<ExampleCode>

```ts
function createUser(
  name: string,
  role: string = "member",
  email?: string,
): string {
  const base = `${name} (${role})`;
  return email ? `${base} <${email}>` : base;
}

console.log(createUser("Ada"));                          // "Ada (member)"
console.log(createUser("Grace", "admin"));               // "Grace (admin)"
console.log(createUser("Alan", "admin", "a@turing.io")); // "Alan (admin) <a@turing.io>"

// Rest parameters collect remaining args into a typed array
function sum(...numbers: number[]): number {
  return numbers.reduce((total, n) => total + n, 0);
}

console.log(sum(1, 2, 3, 4)); // 10
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A function type expression describes the shape of a function as a value. Use it to type callbacks, higher-order functions, and stored function references.

</ExampleProse>
<ExampleCode>

```ts
type Predicate<T> = (value: T) => boolean;
type Transform<A, B> = (input: A) => B;

function filter<T>(arr: T[], pred: Predicate<T>): T[] {
  return arr.filter(pred);
}

function map<A, B>(arr: A[], fn: Transform<A, B>): B[] {
  return arr.map(fn);
}

const evens = filter([1, 2, 3, 4, 5], (n) => n % 2 === 0);
const doubled = map([1, 2, 3], (n) => n * 2);

console.log(evens);   // [2, 4]
console.log(doubled); // [2, 4, 6]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Overloads let one function handle multiple distinct call signatures. Write the overload signatures first, then a single implementation signature that unifies them. Callers only see the overloads.

</ExampleProse>
<ExampleCode>

```ts
// Overload signatures (visible to callers)
function parse(input: string): number;
function parse(input: number): string;

// Implementation signature (not callable directly)
function parse(input: string | number): number | string {
  if (typeof input === "string") return parseInt(input, 10);
  return input.toString();
}

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

console.log(n, typeof n); // 42 number
console.log(s, typeof s); // "42" string
```

</ExampleCode>
</ExamplePair>

<InProduction>
Function overloads are the clean way to handle multiple call shapes without leaking `any` into callers. The implementation signature uses a union of all overload types - it is not callable directly, so callers always get the narrower overload types. Teams that skip overloads often widen the implementation to `any` to satisfy the type checker, which silently disables type safety for all callers. For callbacks passed across module boundaries, prefer explicit function type expressions over inline annotations - a named `type Handler = (event: Event) => void` is easier to update and find in search than scattered inline types. When TypeScript infers a return type as `void | string`, an explicit `: string` annotation on the function catches the bug at the definition instead of propagating it to every caller.
</InProduction>


Typed function signatures, optional and rest parameters, function type expressions, and overloads.

Functions


TypeScript adds type-level access modifiers and compile-time privacy to JavaScript classes. For most use cases, the TypeScript additions are enough - but knowing when ECMAScript's `#private` fields are the right tool prevents a class of runtime bugs.

<ExamplePair>
<ExampleProse>

Constructor parameter shorthand declares and initializes fields in one step. Prefix a constructor parameter with `public`, `private`, `protected`, or `readonly` and TypeScript creates the corresponding field automatically.

</ExampleProse>
<ExampleCode>

```ts
class User {
  constructor(
    public readonly id: string,
    public name: string,
    private email: string,
    protected role: string = "member",
  ) {}

  describe(): string {
    return `${this.name} (${this.role}) <${this.email}>`;
  }
}

const user = new User("u-1", "Ada", "ada@example.com");
console.log(user.describe()); // "Ada (member) <ada@example.com>"
console.log(user.id);         // "u-1"
console.log(user.name);       // "Ada"
// user.email → TypeScript error: private
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Abstract classes define a contract for subclasses without providing a complete implementation. Subclasses must implement every abstract method.

</ExampleProse>
<ExampleCode>

```ts
abstract class Shape {
  abstract area(): number;
  abstract perimeter(): number;

  describe(): string {
    return `area=${this.area().toFixed(2)}, perimeter=${this.perimeter().toFixed(2)}`;
  }
}

class Circle extends Shape {
  constructor(private radius: number) { super(); }
  area(): number { return Math.PI * this.radius ** 2; }
  perimeter(): number { return 2 * Math.PI * this.radius; }
}

class Rectangle extends Shape {
  constructor(private width: number, private height: number) { super(); }
  area(): number { return this.width * this.height; }
  perimeter(): number { return 2 * (this.width + this.height); }
}

const shapes: Shape[] = [new Circle(5), new Rectangle(4, 6)];
shapes.forEach((s) => console.log(s.describe()));
// area=78.54, perimeter=31.42
// area=24.00, perimeter=20.00
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A class can implement an interface to guarantee its shape. TypeScript checks that every required property and method is present with the right type.

</ExampleProse>
<ExampleCode>

```ts
interface Serializable {
  serialize(): string;
  deserialize(data: string): void;
}

interface Validatable {
  validate(): boolean;
}

class Config implements Serializable, Validatable {
  private data: Record<string, string> = {};

  set(key: string, value: string): void { this.data[key] = value; }
  get(key: string): string | undefined { return this.data[key]; }

  serialize(): string { return JSON.stringify(this.data); }
  deserialize(json: string): void { this.data = JSON.parse(json) as Record<string, string>; }
  validate(): boolean { return Object.keys(this.data).length > 0; }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

ECMAScript `#private` fields (the `#` prefix) are truly private at runtime - inaccessible from outside the class even via reflection. TypeScript's `private` keyword is erased at compile time and is accessible at runtime via `(obj as any).field`.

</ExampleProse>
<ExampleCode>

```ts
class SecureConfig {
  readonly name: string;
  #apiKey: string; // ECMAScript private - not accessible at runtime

  constructor(name: string, apiKey: string) {
    this.name = name;
    this.#apiKey = apiKey;
  }

  makeRequest(endpoint: string): string {
    // #apiKey available inside the class
    return `${endpoint}?key=${this.#apiKey}`;
  }
}

const config = new SecureConfig("prod", "secret-key-123");
console.log(config.name);          // "prod"
console.log(config.makeRequest("/api/data")); // "/api/data?key=secret-key-123"

// No runtime error - # fields aren't regular properties; cast access returns undefined
// console.log((config as any).apiKey); // undefined
// console.log((config as any)["#apiKey"]); // undefined
```

</ExampleCode>
</ExamplePair>

<InProduction>
TypeScript's `private` keyword is a type-system fiction - it's erased at runtime, so `(obj as any).field` bypasses it. This is fine for most internal APIs, but if you need runtime privacy (hiding API keys from `console.log`, protecting sensitive config from serialization libraries that walk prototypes), use ECMAScript `#private` fields. They're backed by a WeakMap in V8 and genuinely inaccessible outside the class. One practical check: add a compile-time assertion when a class must satisfy an interface - `const _: SomeInterface = {} as MyClass` catches the mismatch at definition time rather than at the call site where the class is used as an interface value.
</InProduction>


Constructor shorthand, access modifiers, readonly, abstract classes, implementing interfaces, and ECMAScript private fields.

Classes


Enums define a named set of constants. TypeScript's `enum` is a compile-time and runtime construct - it emits a JavaScript object. Knowing what gets emitted is the key to avoiding the footguns.

<ExamplePair>
<ExampleProse>

Numeric enums auto-increment from 0 by default. TypeScript generates a reverse mapping - `Direction[0]` returns `"Up"`. The emitted object contains both `Direction.Up = 0` and `Direction[0] = "Up"`.

</ExampleProse>
<ExampleCode>

```ts
enum Direction {
  Up,    // 0
  Down,  // 1
  Left,  // 2
  Right, // 3
}

console.log(Direction.Up);        // 0
console.log(Direction[0]);        // "Up"  ← reverse mapping
console.log(Direction["Down"]);   // 1

function move(dir: Direction): string {
  if (dir === Direction.Up) return "moving up";
  return `moving to ${Direction[dir]}`;
}

console.log(move(Direction.Left)); // "moving to Left"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

String enums assign string values explicitly. There is no reverse mapping. String enums are safer than numeric ones: the serialized value is human-readable and there's no falsy-zero footgun.

</ExampleProse>
<ExampleCode>

```ts
enum Status {
  Pending  = "PENDING",
  Active   = "ACTIVE",
  Inactive = "INACTIVE",
  Deleted  = "DELETED",
}

console.log(Status.Active);  // "ACTIVE"
console.log(Status["Active"]); // "ACTIVE"
// No reverse mapping: Status["ACTIVE"] → undefined

function printStatus(s: Status): void {
  console.log(`Status is: ${s}`);
}

printStatus(Status.Pending); // "Status is: PENDING"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`const enum` inlines values at every use site and emits no runtime object. This produces smaller output but breaks when the enum is consumed from a different compilation unit or with `isolatedModules: true`.

</ExampleProse>
<ExampleCode>

```ts
const enum Axis { X = "x", Y = "y", Z = "z" }

function rotate(axis: Axis, degrees: number): string {
  return `rotate ${degrees}° on ${axis}`;
}

// Emitted JS: rotate("x", 90) - the string is inlined, no Axis object exists
console.log(rotate(Axis.X, 90)); // "rotate 90° on x"

// Regular enum for comparison - emits a full JS object
enum Color { Red = "#E63946", Blue = "#3178C6" }
console.log(Color.Red); // "#E63946"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

String literal unions achieve the same type safety as string enums with less ceremony - no emit, no import, natural JSON serialization.

</ExampleProse>
<ExampleCode>

```ts
// Enum version - emits JS, requires import, can't spread into JSON cleanly
enum RoleEnum { Admin = "admin", Member = "member", Guest = "guest" }

// Union version - type only, no emit, identical runtime behavior
type Role = "admin" | "member" | "guest";

function greet(role: Role): string {
  return role === "admin" ? "Welcome, admin." : `Hello, ${role}.`;
}

// The union works directly with JSON without translation
const payload = { userId: "u-1", role: "admin" as Role };
console.log(JSON.stringify(payload)); // {"userId":"u-1","role":"admin"}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Numeric enums are the most dangerous TypeScript feature in production APIs. `0` is falsy, so `if (status)` silently skips the first enum member - a common source of bugs when the default state maps to `0`. String enums are safer but still emit a runtime object and require an import wherever they're used, which creates coupling across module boundaries. The practical recommendation for most codebases: use string literal unions (`type Role = "admin" | "member"`) for variant types that appear in API contracts; use `const enum` only in single-package TypeScript projects that don't use `isolatedModules`; avoid plain numeric enums in any code that touches external data. If you inherit a codebase full of enums, `@typescript-eslint/prefer-literal-type` can flag them automatically.
</InProduction>


Numeric, string, and const enums; heterogeneous enums; reverse mapping; and when to use string literal unions instead.

Enums


Mapped types iterate over the keys of an existing type and produce a new type with transformed values or modifiers. They are how TypeScript's standard utility types (`Partial`, `Readonly`, `Required`) are implemented - not compiler magic, but plain TypeScript you can write yourself.

<ExamplePair>
<ExampleProse>

The `{ [K in keyof T]: ... }` syntax creates a new type with the same keys as `T` but with transformed values. `keyof T` produces a union of all key names; `K` is the loop variable; the value on the right determines the new property type.

</ExampleProse>
<ExampleCode>

```ts
type User = {
  id: string;
  name: string;
  email: string;
};

// Every value becomes an array of that type
type Listify<T> = {
  [K in keyof T]: T[K][];
};

type UserLists = Listify<User>;
// { id: string[]; name: string[]; email: string[] }

// Wrap every value in a Promise
type Asyncify<T> = {
  [K in keyof T]: Promise<T[K]>;
};

type AsyncUser = Asyncify<User>;
// { id: Promise<string>; name: Promise<string>; email: Promise<string> }
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Modifier prefixes control `readonly` and optionality. `+` adds the modifier (the default when you omit it); `-` removes it. This lets you strip all `readonly` constraints or make every optional property required.

</ExampleProse>
<ExampleCode>

```ts
type Config = {
  readonly host: string;
  readonly port: number;
  debug?: boolean;
};

// -readonly: strip all readonly modifiers
type Mutable<T> = {
  -readonly [K in keyof T]: T[K];
};

type MutableConfig = Mutable<Config>;
// { host: string; port: number; debug?: boolean }

// -?: make every optional property required
type Complete<T> = {
  [K in keyof T]-?: T[K];
};

type RequiredConfig = Complete<Config>;
// { readonly host: string; readonly port: number; debug: boolean }
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Key remapping via `as` lets you rename keys as part of the mapped type. Combine with template literal types to derive new names - for example, converting every field into a getter method signature.

</ExampleProse>
<ExampleCode>

```ts
type Model = {
  id: string;
  name: string;
  createdAt: Date;
};

// Remap key names: prepend "get" and capitalize
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type ModelGetters = Getters<Model>;
// {
//   getId:        () => string;
//   getName:      () => string;
//   getCreatedAt: () => Date;
// }

// Filter keys with `as` + `never` - omit all Function-valued properties
type DataOnly<T> = {
  [K in keyof T as T[K] extends Function ? never : K]: T[K];
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A practical example: `Versioned<T>` adds a `_version` field to any entity for optimistic-locking. Enforcing it at the type level means the version field is present everywhere it's required - without repeating it in every entity definition.

</ExampleProse>
<ExampleCode>

```ts
type Versioned<T> = T & { _version: number };

type Product = { id: string; name: string; price: number };
type Order   = { id: string; items: string[]; total: number };

type VersionedProduct = Versioned<Product>;
type VersionedOrder   = Versioned<Order>;

function update<T extends { id: string }>(
  entity: Versioned<T>,
  patch: Partial<T>
): Versioned<T> {
  return { ...entity, ...patch, _version: entity._version + 1 };
}

const product: VersionedProduct = {
  id: "p1", name: "Widget", price: 9.99, _version: 1,
};
const updated = update(product, { price: 12.99 });
console.log(updated._version); // 2
```

</ExampleCode>
</ExamplePair>

<InProduction>
`Readonly<T>` and `Partial<T>` are stdlib mapped types - not compiler magic. Writing your own lets you enforce constraints at the type level without runtime overhead. A `Versioned<T>` that adds `_version` to any entity ensures the optimistic-lock field is required at every persistence boundary. Key remapping with `as` combined with `never` is the idiomatic way to filter keys - producing a narrowed type that only exposes the fields you want (e.g., stripping all `Function` properties for a serializable snapshot). If you find yourself writing the same optional/required/readonly transformation more than once, write a generic mapped type once and reuse it.
</InProduction>


Build new types by transforming every key of an existing type - the mechanism behind Partial, Readonly, and the rest of the TypeScript stdlib.

Mapped Types


TypeScript's standard library ships a set of utility types built from mapped types, conditional types, and `infer`. You don't need to install anything - they're available in every TypeScript project.

<ExamplePair>
<ExampleProse>

`Partial<T>` makes every property optional. `Required<T>` does the reverse. `Readonly<T>` prevents mutation. `Record<K, V>` constructs an object type with keys `K` and values `V` - useful for lookup tables and index signatures.

</ExampleProse>
<ExampleCode>

```ts
type User = { id: string; name: string; email: string };

// Partial - all fields optional (common for update payloads)
type UserPatch = Partial<User>;
// { id?: string; name?: string; email?: string }

// Required - all fields mandatory (strips optional markers)
type FullUser = Required<UserPatch>;
// { id: string; name: string; email: string }

// Readonly - no assignments after construction
type ImmutableUser = Readonly<User>;
const u: ImmutableUser = { id: "1", name: "Ada", email: "ada@example.com" };
// u.name = "Grace"; // Error: cannot assign to 'name' - it is read-only

// Record - maps a union of keys to a value type
type RolePermissions = Record<"admin" | "editor" | "viewer", string[]>;
const permissions: RolePermissions = {
  admin:  ["read", "write", "delete"],
  editor: ["read", "write"],
  viewer: ["read"],
};
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Pick<T, K>` keeps only the listed keys. `Omit<T, K>` drops them. `Exclude<T, U>` removes members of a union that extend `U`. `Extract<T, U>` keeps only members that extend `U`.

</ExampleProse>
<ExampleCode>

```ts
type Article = {
  id: string;
  title: string;
  body: string;
  authorId: string;
  publishedAt: Date | null;
};

// Pick - keep only what the list endpoint needs
type ArticleSummary = Pick<Article, "id" | "title" | "publishedAt">;
// { id: string; title: string; publishedAt: Date | null }

// Omit - strip internal fields before sending to the client
type PublicArticle = Omit<Article, "authorId">;
// { id: string; title: string; body: string; publishedAt: Date | null }

type Status = "pending" | "active" | "suspended" | "deleted";

// Exclude - remove specific members from a union
type LiveStatus = Exclude<Status, "deleted" | "suspended">;
// "pending" | "active"

// Extract - keep only the matching members
type TerminalStatus = Extract<Status, "suspended" | "deleted">;
// "suspended" | "deleted"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`ReturnType<F>` extracts the return type of a function. `Parameters<F>` extracts the parameter types as a tuple. `InstanceType<C>` extracts the instance type of a class constructor. `Awaited<T>` recursively unwraps `Promise` wrappers.

</ExampleProse>
<ExampleCode>

```ts
function fetchUser(id: string): Promise<{ id: string; name: string }> {
  return Promise.resolve({ id, name: "Ada" });
}

// ReturnType - derive the return type without repeating it
type FetchUserReturn = ReturnType<typeof fetchUser>;
// Promise<{ id: string; name: string }>

// Awaited - unwrap the Promise
type ResolvedUser = Awaited<FetchUserReturn>;
// { id: string; name: string }

// Parameters - extract argument types as a tuple
type FetchUserParams = Parameters<typeof fetchUser>;
// [id: string]

class Repository {
  constructor(private db: string) {}
  find(id: string): Promise<{ id: string }> {
    return Promise.resolve({ id });
  }
}

// InstanceType - get the type of an instance from its constructor
type RepoInstance = InstanceType<typeof Repository>;
// Repository
```

</ExampleCode>
</ExamplePair>

<InProduction>
`ReturnType<typeof fn>` is especially useful for third-party code you can't modify - derive the type from its runtime behavior instead of maintaining a duplicate annotation that will drift. `Awaited<T>` is essential for async pipelines: `Awaited<ReturnType<typeof fetchUser>>` gives you the resolved payload type without additional ceremony. For update payloads, reach for `Partial<T>` at the API boundary and `Required<T>` at the persistence boundary - this makes the required/optional contract explicit at every layer. Avoid `Partial` in function bodies where the data should already be complete; a missing field should be a type error, not a runtime surprise.
</InProduction>


The TypeScript stdlib ships 20+ built-in utility types - Partial, Readonly, Pick, Omit, Exclude, ReturnType, and Awaited cover most day-to-day needs.

Utility Types


TypeScript tracks the type of every value at every point in your control flow. When you check a type, TypeScript "narrows" the union inside that branch so you can safely access variant-specific properties without a cast.

<ExamplePair>
<ExampleProse>

`typeof` narrows primitive types. `instanceof` narrows class instances. The `in` operator narrows by property presence. Equality checks narrow by value. TypeScript applies each to the right branch automatically.

</ExampleProse>
<ExampleCode>

```ts
function process(value: string | number | Date): string {
  if (typeof value === "string") {
    return value.toUpperCase(); // value: string
  }
  if (value instanceof Date) {
    return value.toISOString(); // value: Date
  }
  return value.toFixed(2); // value: number
}

type Circle = { kind: "circle"; radius: number };
type Rect   = { kind: "rect"; width: number; height: number };
type Shape  = Circle | Rect;

function describe(shape: Shape): string {
  if ("radius" in shape) {
    return `circle r=${shape.radius}`; // shape: Circle
  }
  return `rect ${shape.width}×${shape.height}`; // shape: Rect
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Truthiness narrowing removes `null`, `undefined`, `0`, and `""` from the type. Assignment narrowing refines the type each time a variable is assigned - TypeScript tracks all assignment sites in the function.

</ExampleProse>
<ExampleCode>

```ts
function greet(name: string | null): string {
  if (!name) {
    return "Hello, stranger"; // name is falsy here
  }
  return `Hello, ${name}`; // name: string (null removed)
}

// Assignment narrowing
let id: string | number = Math.random() > 0.5 ? "abc" : 42;

if (typeof id === "string") {
  id = id.toUpperCase(); // id: string
} else {
  id = id * 2; // id: number
}

// Nullable field narrowing
type Profile = { avatar: string | undefined };

function renderAvatar(profile: Profile): string {
  const { avatar } = profile;
  if (!avatar) return "/default-avatar.png"; // avatar is falsy: type stays string | undefined
  return avatar; // avatar: string
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A user-defined type guard is a function whose return type is a type predicate (`arg is Type`). When the function returns `true`, TypeScript narrows the argument to the specified type in the calling scope.

</ExampleProse>
<ExampleCode>

```ts
type Cat = { kind: "cat"; meow(): void };
type Dog = { kind: "dog"; bark(): void };
type Animal = Cat | Dog;

function isCat(animal: Animal): animal is Cat {
  return animal.kind === "cat";
}

function makeSound(animal: Animal): void {
  if (isCat(animal)) {
    animal.meow(); // animal: Cat
  } else {
    animal.bark(); // animal: Dog
  }
}

// Type guard for unknown API responses
function isStringArray(value: unknown): value is string[] {
  return (
    Array.isArray(value) && value.every((item) => typeof item === "string")
  );
}

const raw: unknown = JSON.parse('["a", "b", "c"]');
if (isStringArray(raw)) {
  console.log(raw.join(", ")); // raw: string[]
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

An assertion function (`asserts arg is Type`) throws if the assertion fails and narrows the type for all code that follows. The exhaustive `never` check turns a `switch` on a discriminated union into a compile-time registry - adding a new variant without handling it is a type error.

</ExampleProse>
<ExampleCode>

```ts
function assertDefined<T>(value: T | null | undefined, msg: string): asserts value is T {
  if (value == null) throw new Error(msg);
}

let maybeUser: { name: string } | null = null;
// assertDefined(maybeUser, "user required"); // throws at runtime if null
// After the call, maybeUser is narrowed to { name: string }

// Exhaustive switch - adding a new variant without a case is a type error
type Action =
  | { type: "INCREMENT"; by: number }
  | { type: "RESET" }
  | { type: "SET"; value: number };

function reduce(count: number, action: Action): number {
  switch (action.type) {
    case "INCREMENT": return count + action.by;
    case "RESET":     return 0;
    case "SET":       return action.value;
    default: {
      // If Action gains a new variant and this case is missing, _: never is a type error
      const _: never = action;
      throw new Error(`Unhandled action: ${JSON.stringify(_)}`);
    }
  }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
A discriminated union + `switch (action.type)` with `default: const _: never = action` is a compile-time registry - adding a new variant without handling it is a type error everywhere the switch appears. This pattern replaces the Visitor pattern in most TypeScript codebases: it's simpler, serializes to JSON without adapters, and the compiler enforces exhaustiveness. Assertion functions (`asserts value is T`) are the right tool for validating data at trust boundaries (API responses, config loading) - they narrow the type for all downstream code without needing an `if` at every call site. Prefer `unknown` over `any` for unvalidated input: `unknown` forces you to narrow before use; `any` bypasses the type checker silently.
</InProduction>


Control-flow analysis, type guards, assertion functions, and exhaustive checks - how TypeScript proves a value's type at each point in the program.

Narrowing


TypeScript uses the same ES module syntax as JavaScript and adds `import type` for type-only imports. The `tsconfig.json` `moduleResolution` strategy controls how module specifiers are resolved - getting this wrong causes builds that typecheck locally but fail in production.

<ExamplePair>
<ExampleProse>

Named exports, default exports, and `import type` work as in ES modules. `import type` is stripped entirely at compile time - it emits no runtime import statement, which prevents accidental side-effect imports and keeps bundler tree-shaking accurate.

</ExampleProse>
<ExampleCode>

```ts
// user.ts
export type UserId = string;

export interface User {
  id: UserId;
  name: string;
  role: "admin" | "member";
}

export function createUser(name: string): User {
  return { id: crypto.randomUUID(), name, role: "member" };
}

export default createUser;
```

```ts
// app.ts
import createUser, { type User, type UserId } from "./user";
// ^ "import type" syntax: User and UserId are stripped at compile time.
// createUser is a value import - it survives into the JS output.

const user: User = createUser("Ada");
const id: UserId = user.id;
console.log(id);
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Re-exports collect related exports from multiple files into a single entry point (a "barrel"). This keeps import paths short for consumers while the implementation stays split across files.

</ExampleProse>
<ExampleCode>

```ts
// lib/auth/session.ts
export interface Session { token: string; expiresAt: Date }
export function parseSession(raw: string): Session { /* ... */ return {} as Session; }

// lib/auth/user.ts
export interface AuthUser { id: string; email: string }
export function getUser(token: string): Promise<AuthUser> { /* ... */ return Promise.resolve({} as AuthUser); }

// lib/auth/index.ts - barrel
export type { Session } from "./session";
export { parseSession } from "./session";
export type { AuthUser } from "./user";
export { getUser } from "./user";
```

```ts
// pages/api/me.ts - clean import from the barrel
import { parseSession, getUser } from "@/lib/auth";
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`moduleResolution` in `tsconfig.json` controls how TypeScript resolves module specifiers. The `bundler` strategy matches Vite, esbuild, and Next.js - it allows extension-less imports and path aliases. `node16` / `nodenext` require explicit `.js` extensions (even for `.ts` source files), matching Node.js ESM resolution.

</ExampleProse>
<ExampleCode>

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    // "bundler" for Vite/Next.js/esbuild - no extensions required, path aliases work
    "moduleResolution": "bundler",
    "module": "ESNext",

    // Path aliases - @/ maps to project root
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

```ts
// With moduleResolution: "bundler" - clean alias imports work
import { Button } from "@/components/Button";
import type { User } from "@/lib/types";

// With moduleResolution: "node16" - explicit extensions required
// import { Button } from "@/components/Button.js"; // .js even for .ts source
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`isolatedModules: true` requires every file to be compilable in isolation - no `const enum` across files, no type-only re-exports without `export type`. This matches how esbuild, swc, and Babel transform TypeScript: one file at a time, without full type information.

</ExampleProse>
<ExampleCode>

```ts
// WITHOUT isolatedModules - this compiles fine with tsc but breaks under esbuild/swc:
export { SomeType } from "./types"; // esbuild can't tell if SomeType is a value or type

// WITH isolatedModules: true - use explicit "export type"
export type { SomeType } from "./types"; // unambiguous: type-only, stripped at build time

// const enum is also banned under isolatedModules - use a regular enum or string union:
// const enum Direction { Up, Down } // Error under isolatedModules
enum Direction { Up = "UP", Down = "DOWN" } // OK: regular string enum
type DirectionLiteral = "UP" | "DOWN";       // Better: string literal union
```

</ExampleCode>
</ExamplePair>

<InProduction>
`import type` prevents runtime artifacts when bundlers strip types - without it, a type-only import can become an empty side-effect import that confuses tree shaking and produces surprising output in module graphs. Set `isolatedModules: true` from day one: it's required by esbuild, swc, and most modern build tools, and catching the error early is cheaper than debugging a production build where a `const enum` silently expanded differently than expected. For path aliases, the `paths` in `tsconfig.json` only affect TypeScript's type resolution - configure your bundler (Next.js `next.config.js`, Vite `resolve.alias`) separately to make runtime imports work. The two configs must stay in sync.
</InProduction>


ES module import/export in TypeScript, import type, barrel re-exports, path aliases, moduleResolution strategies, and isolatedModules.

Modules


A declaration file (`.d.ts`) describes the shape of a JavaScript module to TypeScript without containing any runtime code. It is the bridge between the untyped JS ecosystem and TypeScript's type system.

<ExamplePair>
<ExampleProse>

A `.d.ts` file declares types for a module. The declarations are erased at compile time - they exist only for the type checker. If a package ships without types, you write (or install) a `.d.ts` to tell TypeScript what the package exports.

</ExampleProse>
<ExampleCode>

```ts
// types/untyped-logger.d.ts
// Describes a hypothetical "untyped-logger" npm package that has no @types/ package

declare module "untyped-logger" {
  export interface LogLevel {
    level: "debug" | "info" | "warn" | "error";
  }

  export interface Logger {
    debug(msg: string, meta?: Record<string, unknown>): void;
    info(msg: string, meta?: Record<string, unknown>): void;
    warn(msg: string, meta?: Record<string, unknown>): void;
    error(msg: string, error?: Error, meta?: Record<string, unknown>): void;
  }

  export function createLogger(name: string): Logger;
  export const rootLogger: Logger;
}
```

```ts
// Now this import is fully typed
import { createLogger } from "untyped-logger";
const log = createLogger("api");
log.info("server started", { port: 3000 });
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `/// <reference types="..." />` directive adds type declarations from a package to the global scope. Global augmentation extends built-in types - useful for adding custom properties to `window`, `process.env`, or Express's `Request`.

</ExampleProse>
<ExampleCode>

```ts
// global.d.ts - augment Express Request with your auth context
import "express";

declare global {
  namespace Express {
    interface Request {
      user?: {
        id: string;
        role: "admin" | "member";
      };
    }
  }
}

// env.d.ts - type process.env entries so missing vars are a type error
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      JWT_SECRET: string;
      NODE_ENV: "development" | "production" | "test";
      PORT?: string; // optional - has a default
    }
  }
}
```

```ts
// reference directive - include a types package in this file's scope
/// <reference types="node" />

const buf = Buffer.from("hello"); // Buffer is available because of the reference
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`@types/` packages (from DefinitelyTyped) provide types for untyped npm packages. They are versioned independently of the library - a library patch release can silently break under an old `@types` version or vice versa. Lock both versions in `package.json`.

</ExampleProse>
<ExampleCode>

```jsonc
// package.json - lock library and @types/ versions together
{
  "dependencies": {
    "express": "4.18.2"   // runtime library
  },
  "devDependencies": {
    "@types/express": "4.17.21"  // lock major.minor to match library
    // A mismatch - e.g., @types/express@5.x with express@4.x - causes
    // type errors that are invisible until you update and break everything.
  }
}
```

```ts
// Check if a package ships its own types (no @types/ needed):
// Look for "types" or "typings" in the package's package.json.
// If present, @types/ is unnecessary and may conflict.
import type { RequestHandler } from "express"; // from @types/express
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

For packages you own, TypeScript generates `.d.ts` files automatically from source when `declaration: true` is set in `tsconfig.json`. For API clients, generate types from your OpenAPI or GraphQL schema - two handwritten sources of truth for the same contract always diverge.

</ExampleProse>
<ExampleCode>

```jsonc
// tsconfig.json - emit declarations alongside compiled JS
{
  "compilerOptions": {
    "declaration": true,        // emit .d.ts for every .ts file
    "declarationMap": true,     // emit .d.ts.map for Go-to-Definition in source
    "declarationDir": "dist/types", // output declarations to a separate folder
    "outDir": "dist"
  }
}
```

```bash
# Generate TypeScript types from an OpenAPI spec (openapi-typescript)
npx openapi-typescript openapi.yaml -o src/types/api.d.ts

# Generate TypeScript types from a GraphQL schema (graphql-code-generator)
npx graphql-codegen --config codegen.yml
```

```ts
// Import the generated types - no manual maintenance
import type { components } from "@/types/api";

type User = components["schemas"]["User"];
type CreateUserRequest = components["schemas"]["CreateUserRequest"];
```

</ExampleCode>
</ExamplePair>

<InProduction>
`@types/` packages are maintained separately from the library they describe - a patch release of the library can quietly break under an old `@types` version, or a new `@types` version can introduce types incompatible with the runtime behavior you rely on. Lock both `express` and `@types/express` to matching major.minor versions in `package.json`. For teams that own their API: generate `.d.ts` files from an OpenAPI spec or GraphQL schema rather than handwriting them. Two sources of truth for the same contract always diverge - the spec diverges from the implementation, and the handwritten types diverge from the spec. A generated type file eliminates one of those gaps at zero maintenance cost.
</InProduction>


Writing .d.ts files, augmenting global types, @types/ version skew, and generating declarations from OpenAPI or GraphQL schemas instead of handwriting them.