lang-typescript

# TypeScript Expert

Write clean, type-safe TypeScript code that leverages the full power of the type system to catch bugs at compile time.

## When to Use This Skill

Use this skill when:

- Writing or refactoring TypeScript code
- Configuring TypeScript projects (tsconfig.json)
- Solving complex type-related challenges
- Choosing between type system patterns
- Validating external data with types

## Core Workflow

### 1. Type Decision Tree

**Choose the right construct:**

| Use Case          | Use                  | Not                  |
| ----------------- | -------------------- | -------------------- |
| Object shapes     | `interface`          | `type`               |
| Unions/primitives | `type`               | `interface`          |
| Dynamic data      | `unknown`            | `any`                |
| State machines    | Discriminated unions | Complex conditionals |
| Domain types      | Branded types        | Plain primitives     |

**Example:**

```typescript
// ✅ Correct choices
interface User {
  id: number;
  name: string;
} // Object shape
type Status = "idle" | "loading" | "success"; // Union
type USD = number & { readonly __brand: "USD" }; // Branded type

// ❌ Wrong choices
type User = { id: number }; // Use interface
interface Status {
  /* ... */
} // Can't do unions
```

### 2. State Modeling Pattern

For finite states, always use discriminated unions to eliminate impossible states:

```typescript
type ApiState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: string }
  | { status: "error"; message: string };

// Exhaustiveness checking
function handle(state: ApiState) {
  switch (state.status) {
    case "success":
      return state.data;
    case "error":
      return state.message;
    case "idle":
      return "Not started";
    case "loading":
      return "Loading...";
    default:
      const _exhaustive: never = state; // Compiler error if cases missing
      throw new Error("Unhandled state");
  }
}
```