claude-toolkit 0.1.9

package/docs/best-practices/typescript/essential-patterns.md

@@ -0,0 +1,119 @@
+# Essential Patterns
+
+> Source: [Four Essential TypeScript Patterns You Can't Work Without](https://www.totaltypescript.com/four-essential-typescript-patterns) — Matt Pocock
+
+## 1. Branded Types
+
+Create **validation boundaries** by tagging base types with a unique label. Prevents mixing validated and unvalidated values of the same underlying type.
+
+```typescript
+type Brand<T, TBrand extends string> = T & { __brand: TBrand };
+
+type Password = Brand<string, "Password">;
+type Email = Brand<string, "Email">;
+
+function validatePassword(input: string): Password {
+  if (input.length < 8) throw new Error("Too short");
+  return input as Password;
+}
+
+function login(email: Email, password: Password) {
+  // Both values are guaranteed to have been validated
+}
+
+// login("user@test.com", "short") — Error! Raw strings are not Password/Email
+```
+
+**When to use:** Anywhere you need to ensure a value has passed through validation — passwords, emails, sanitized HTML, monetary amounts, database IDs.
+
+## 2. Globals
+
+Understand and manage TypeScript's **global type scope** for typing JavaScript globals like `process.env`, `window`, or custom global functions.
+
+```typescript
+declare global {
+  function myGlobalFunc(): boolean;
+  var myGlobalVar: number;
+}
+
+// Now available everywhere without imports
+console.log(myGlobalVar);
+myGlobalFunc();
+```
+
+**Practical use — strongly typing `process.env`:**
+
+```typescript
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      DATABASE_URL: string;
+      API_KEY: string;
+      NODE_ENV: "development" | "production" | "test";
+    }
+  }
+}
+
+// process.env.DATABASE_URL is now typed as string (not string | undefined)
+```
+
+## 3. Assertion Functions & Type Predicates
+
+Both patterns improve TypeScript's ability to narrow types.
+
+### Type Predicates
+
+Narrow types within conditionals using `is`:
+
+```typescript
+const values = ["a", "b", undefined, "c", undefined];
+
+const filtered = values.filter((v): v is string => Boolean(v));
+// string[] — TypeScript knows undefined was removed
+```
+
+### Assertion Functions
+
+Enforce type guarantees or throw errors using `asserts`:
+
+```typescript
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== "string") {
+    throw new Error(`Expected string, got ${typeof value}`);
+  }
+}
+
+function process(input: unknown) {
+  assertIsString(input);
+  // input is narrowed to string from here on
+  console.log(input.toUpperCase());
+}
+```
+
+**Key difference:** Predicates return `boolean` and work in `if`/`filter`. Assertions return `void` and narrow the type for all subsequent code in the scope.
+
+## 4. Classes (for Library APIs)
+
+Classes enable the **builder pattern** and self-typing structures — particularly useful in library code.
+
+```typescript
+class SDK {
+  loggedInUser?: User;
+
+  constructor(loggedInUser?: User) {
+    this.loggedInUser = loggedInUser;
+  }
+
+  assertIsLoggedIn(): asserts this is this & { loggedInUser: User } {
+    if (!this.loggedInUser) {
+      throw new Error("Not logged in");
+    }
+  }
+}
+
+const sdk = new SDK();
+sdk.assertIsLoggedIn();
+// sdk.loggedInUser is now User (not User | undefined)
+```
+
+**When to use:** Libraries and SDKs where you need fluent APIs, chainable methods, or internal type refinement. This pattern powers libraries like tRPC.

package/docs/best-practices/typescript/generics-patterns.md

@@ -0,0 +1,105 @@
+# Generics Patterns
+
+> Sources: [TypeScript Generics in 3 Easy Patterns](https://www.totaltypescript.com/typescript-generics-in-three-easy-patterns), [There Is No Such Thing As A Generic](https://www.totaltypescript.com/no-such-thing-as-a-generic) — Matt Pocock
+
+## Mental Model
+
+Matt argues that "generics" is a misleading name. What people call generics is actually **three distinct patterns** for passing type arguments around.
+
+## Pattern 1: Passing Types to Types
+
+Create reusable type definitions that accept type parameters — like function arguments, but for types.
+
+```typescript
+type ApiResponse<TData> = {
+  data: TData;
+  error?: { message: string };
+};
+
+type UserResponse = ApiResponse<{
+  id: string;
+  name: string;
+}>;
+
+type OrderResponse = ApiResponse<{
+  orderId: string;
+  total: number;
+}>;
+```
+
+This eliminates repetitive wrapper types while keeping each response strongly typed.
+
+## Pattern 2: Passing Types to Functions
+
+Explicitly specify type arguments when calling a function:
+
+```typescript
+const createSet = <T>() => {
+  return new Set<T>();
+};
+
+const stringSet = createSet<string>();
+const numberSet = createSet<number>();
+```
+
+Use this when TypeScript has no value to infer from — the function takes no arguments of type `T`.
+
+## Pattern 3: Inferring Types from Arguments
+
+The most common and powerful pattern. TypeScript deduces type parameters from the values you pass:
+
+```typescript
+const createSet = <T>(initial: T) => {
+  return new Set<T>([initial]);
+};
+
+const stringSet = createSet("matt"); // Set<string>
+const numberSet = createSet(123);    // Set<number>
+```
+
+A practical example with constraints:
+
+```typescript
+const objKeys = <T extends object>(obj: T): Array<keyof T> => {
+  return Object.keys(obj) as Array<keyof T>;
+};
+
+const keys = objKeys({ a: 1, b: 2 });
+// ("a" | "b")[]
+```
+
+The `extends object` constraint ensures only objects are accepted, while `keyof T` preserves the specific key types.
+
+## When to Use Generics vs Unions
+
+From Matt's tip "Know when to use generics":
+
+**Use generics** when the output type depends on the input type — the caller's choice flows through the function.
+
+```typescript
+// Generic: return type depends on input
+function first<T>(arr: T[]): T | undefined {
+  return arr[0];
+}
+```
+
+**Use unions** when the function handles a fixed set of types internally.
+
+```typescript
+// Union: function handles all cases itself
+function format(value: string | number): string {
+  return String(value);
+}
+```
+
+## Constraining Generics
+
+Use `extends` to document expectations and catch misuse at the call site:
+
+```typescript
+function merge<T extends object, U extends object>(a: T, b: U): T & U {
+  return { ...a, ...b };
+}
+```
+
+Without the constraint, callers could pass primitives and get confusing errors deep inside the implementation.

package/docs/best-practices/typescript/micro-opinions.md

@@ -0,0 +1,87 @@
+# Micro-Opinions
+
+> Small but specific stances from Matt Pocock on everyday TypeScript choices.
+
+## Declare Return Types for Top-Level Functions
+
+> Source: [Should You Declare Return Types?](https://www.totaltypescript.com/should-you-declare-return-types)
+
+Declare return types on module-level functions. This communicates intent and helps both humans and AI tools understand what a function is designed to return.
+
+```typescript
+// Do this for top-level functions
+const fetchUser = async (id: string): Promise<User> => {
+  const res = await fetch(`/api/users/${id}`);
+  return res.json();
+};
+```
+
+**Exception:** Skip return types for components returning JSX — the return type is always obvious.
+
+```typescript
+// Skip for JSX-returning components
+const Avatar = (props: AvatarProps) => {
+  return <img alt={props.name} />;
+};
+```
+
+## Prefer `const` Over `let`
+
+> Source: [How let and const Work In TypeScript](https://www.totaltypescript.com/let-and-const)
+
+`const` gives TypeScript narrower, literal type inference. `let` widens to the base type because the variable could be reassigned.
+
+```typescript
+const genre = "rock"; // type: "rock" (literal)
+let genre = "rock";   // type: string (widened)
+```
+
+Prefer `const` to get stricter types. If you must use `let`, add an explicit type annotation.
+
+## Prefer `T[]` Over `Array<T>`
+
+> Source: [Array\<T\> vs T[]: Which is better?](https://www.totaltypescript.com/array-types-in-typescript)
+
+Both are functionally identical. Matt prefers `T[]` because:
+- TypeScript's compiler, hover info, and error messages always use `T[]` syntax
+- It feels more natural and is used throughout the official docs
+
+**Caveat:** `Array<keyof Person>` avoids the need for parentheses that `(keyof Person)[]` requires. Minor edge case.
+
+**What matters most:** Pick one and enforce it with an ESLint rule. Consistency beats preference.
+
+## Don't Use Method Shorthand Syntax
+
+> Source: [Method Shorthand Syntax Considered Harmful](https://www.totaltypescript.com/method-shorthand-syntax-considered-harmful)
+
+Method shorthand in interfaces/types is **bivariant** — it accepts parameter types both narrower and wider than specified, creating a type safety gap.
+
+```typescript
+// Bivariant (unsafe) — allows narrowing the parameter
+interface Handler {
+  handle(input: Animal): void;
+}
+
+// Properly covariant (safe)
+interface Handler {
+  handle: (input: Animal) => void;
+}
+```
+
+With the shorthand, you can implement `handle` expecting `Dog` instead of `Animal`, then pass a `Cat` at runtime — TypeScript won't catch it.
+
+**Enforcement:** Use the ESLint rule `@typescript-eslint/method-signature-style` with `"property"` option.
+
+## Never Use the `Function` Type
+
+> Source: [Don't use Function type in TypeScript](https://www.totaltypescript.com/dont-use-function-keyword-in-typescript)
+
+`Function` represents *any* function with no type information. It kills inference, autocomplete, and safety.
+
+| Instead of | Use |
+|---|---|
+| `Function` | `(...args: any[]) => any` (any function) |
+| `Function` | `() => void` (no-arg callback) |
+| `Function` | `(item: T) => number` (specific signature) |
+
+Be as specific as possible. The more precise the function type, the more TypeScript can help you.

package/docs/best-practices/typescript/runtime-validation.md

@@ -0,0 +1,62 @@
+# Runtime Validation
+
+> Source: [When Should You Use Zod?](https://www.totaltypescript.com/when-should-you-use-zod) — Matt Pocock
+
+## The Framework: Trust Boundaries
+
+Matt's recommendation is based on how much you trust the data entering your application.
+
+## Use Zod: Untrusted Inputs
+
+Validate data you don't control. These are attack vectors and sources of runtime surprises:
+
+- **CLI arguments** (`process.argv`)
+- **Public API endpoints** (path params, headers, request bodies)
+- **Form submissions**
+- **WebSocket connections**
+- **`localStorage`** (users can manipulate it directly)
+
+```typescript
+import { z } from "zod";
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+});
+
+// At the API boundary
+const result = CreateUserSchema.safeParse(req.body);
+if (!result.success) {
+  return res.status(400).json(result.error);
+}
+// result.data is now fully typed and validated
+```
+
+As Matt notes: "If these APIs are exposed to the world, anyone can ping them. If they aren't validated, many might even be vectors for attack."
+
+## Consider Zod: Third-Party APIs
+
+APIs you don't control can change without warning. Validation at the boundary catches drift early:
+
+> "Validation will be thrown early, right when the data enters your app. This makes it much easier to debug and fix."
+
+**Tradeoff:** Zod adds ~12kb gzipped. Consider whether that matters for your bundle.
+
+## Skip Zod: Controlled Inputs
+
+When you control both ends of the data flow (e.g., fullstack app where your frontend talks to your own backend):
+
+- Version drift is "usually just a browser refresh away from a better experience"
+- The security risk is minimal since you control the server
+- The overhead of maintaining schemas for internal data isn't worth it
+
+## Summary
+
+| Data Source | Trust Level | Validate? |
+|---|---|---|
+| User input (forms, CLI, localStorage) | None | Yes |
+| Public API endpoints | None | Yes |
+| Third-party APIs | Low | Recommended |
+| Your own backend (same deploy) | High | Usually skip |
+| Internal function calls | Full | Never |

package/docs/best-practices/typescript/satisfies-operator.md

@@ -0,0 +1,100 @@
+# The `satisfies` Operator
+
+> Source: [5 Ways to Use Satisfies in TypeScript](https://www.totaltypescript.com/how-to-use-satisfies-operator) — Matt Pocock
+
+## What It Does
+
+`satisfies` validates that a value conforms to a type **without widening the inferred type**. You get compile-time validation and narrow inference at the same time.
+
+## 5 Practical Uses
+
+### 1. Strongly Typed URL Search Parameters
+
+`URLSearchParams` normally accepts loose `Record<string, string>`. Use `satisfies` to catch missing required fields:
+
+```typescript
+type GHIssueURLParams = {
+  title: string;
+  body: string;
+};
+
+const params = new URLSearchParams({
+  title: "New Issue",
+} satisfies GHIssueURLParams);
+// Error: Property 'body' is missing
+```
+
+### 2. Strongly Typed POST Request Bodies
+
+`JSON.stringify` erases type information. Validate the body shape before serialization:
+
+```typescript
+type Post = {
+  title: string;
+  content: string;
+};
+
+fetch("/api/posts", {
+  method: "POST",
+  body: JSON.stringify({
+    title: "New Post",
+    content: "Lorem ipsum.",
+  } satisfies Post),
+});
+```
+
+### 3. Inferring Tuples Without `as const`
+
+Get tuple behavior with index bounds checking:
+
+```typescript
+type MoreThanOneMember = [any, ...any[]];
+
+const tuple = [1, 2, 3] satisfies MoreThanOneMember;
+const doesNotExist = tuple[3]; // Error: index out of bounds
+```
+
+### 4. Enforcing `as const` Object Shapes
+
+Combine `as const` with `satisfies` to get immutable objects that must conform to a shape:
+
+```typescript
+type RouteConfig = Record<
+  string,
+  { url: string; searchParams: Record<string, string> }
+>;
+
+const routes = {
+  home: { url: "/", searchParams: {} },
+  about: { url: "/about", searchParams: {} },
+} as const satisfies RouteConfig;
+
+// routes.home.url is narrowed to "/" (not string)
+// AND the shape is validated against RouteConfig
+```
+
+### 5. Enforcing `as const` Array Shapes
+
+Validate recursive structures while preserving literal types:
+
+```typescript
+type NavElement = {
+  title: string;
+  url?: string;
+  children?: readonly NavElement[];
+};
+
+const nav = [
+  { title: "Home", url: "/" },
+  {
+    title: "About",
+    children: [{ title: "Team", url: "/about/team" }],
+  },
+] as const satisfies readonly NavElement[];
+```
+
+**Important:** Array properties in the type must be marked `readonly` to align with `as const`'s immutability.
+
+## When to Reach for `satisfies`
+
+Use it when you need **both** validation against a type **and** narrow inference of the actual value. If you only need one or the other, a regular type annotation or `as const` alone is sufficient.

package/docs/best-practices/typescript/tsconfig-cheat-sheet.md

@@ -0,0 +1,129 @@
+# TSConfig Cheat Sheet
+
+> Source: [The TSConfig Cheat Sheet](https://www.totaltypescript.com/tsconfig-cheat-sheet) — Matt Pocock
+
+## Base Options (Every Project)
+
+These belong in every `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    // Smooth over CJS/ESM interop differences
+    "esModuleInterop": true,
+
+    // Skip type-checking node_modules .d.ts files for performance
+    "skipLibCheck": true,
+
+    // Stable target — prefer over "esnext"
+    "target": "es2022",
+
+    // Allow importing .js and .json files
+    "allowJs": true,
+    "resolveJsonModule": true,
+
+    // Treat all files as modules (avoids redeclaration errors)
+    "moduleDetection": "force",
+
+    // Prevent unsafe TS features that break per-file transpilation
+    "isolatedModules": true,
+
+    // Enforce import type / export type syntax
+    "verbatimModuleSyntax": true
+  }
+}
+```
+
+## Strictness
+
+Enable all strict checks, plus two extras Matt considers essential:
+
+```jsonc
+{
+  "compilerOptions": {
+    // All strict type-checking options
+    "strict": true,
+
+    // Force checking array/object index access (prevents undefined bugs)
+    "noUncheckedIndexedAccess": true,
+
+    // Make the override keyword functional in classes
+    "noImplicitOverride": true
+  }
+}
+```
+
+Matt **deliberately excludes** noisier options like `noImplicitReturns`, `noUnusedLocals`, and `noUnusedParameters`. Add them only if your team wants them — they create friction during development.
+
+## When TypeScript Transpiles (tsc emits JS)
+
+```jsonc
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "outDir": "dist"
+  }
+}
+```
+
+### For Published Libraries
+
+Add `.d.ts` generation so consumers get autocomplete:
+
+```jsonc
+{
+  "compilerOptions": {
+    "declaration": true
+  }
+}
+```
+
+### For Monorepo Packages
+
+```jsonc
+{
+  "compilerOptions": {
+    "composite": true,
+    "sourceMap": true,
+    "declarationMap": true
+  }
+}
+```
+
+## When TypeScript Does NOT Transpile (Linting Mode)
+
+When a bundler (Vite, esbuild, etc.) handles transpilation:
+
+```jsonc
+{
+  "compilerOptions": {
+    // Mimic bundler module resolution
+    "module": "preserve",
+
+    // Don't emit JS files
+    "noEmit": true
+  }
+}
+```
+
+## Environment-Specific `lib`
+
+**DOM environments** (browsers, SSR with DOM APIs):
+
+```jsonc
+{
+  "compilerOptions": {
+    "lib": ["es2022", "dom", "dom.iterable"]
+  }
+}
+```
+
+**Non-DOM environments** (Node.js CLIs, serverless, workers):
+
+```jsonc
+{
+  "compilerOptions": {
+    "lib": ["es2022"]
+  }
+}
+```

package/docs/best-practices/typescript/type-organization.md

@@ -0,0 +1,64 @@
+# Type Organization
+
+> Source: [Where To Put Your Types in Application Code](https://www.totaltypescript.com/where-to-put-your-types-in-application-code) — Matt Pocock
+
+## Three Rules
+
+### Rule 1: Colocate Single-Use Types
+
+When a type is used in only one place, put it in the same file where it's used.
+
+```typescript
+// components/Avatar.tsx
+type AvatarProps = {
+  imageUrl: string;
+  name: string;
+};
+
+export function Avatar({ imageUrl, name }: AvatarProps) {
+  // ...
+}
+```
+
+Don't extract single-use types into separate files. It's low-cost to refactor later if the type grows in scope. Inlining is fine for truly single-use types.
+
+### Rule 2: Share Types Across Modules
+
+When a type serves multiple files, move it to a shared `*.types.ts` file at the appropriate level:
+
+- **App-wide types** → `src/types.ts` or `src/shared.types.ts`
+- **Folder-specific types** → `src/features/auth/auth.types.ts`
+
+This mirrors how you'd handle shared functions — keep them at the narrowest scope that covers all consumers.
+
+```
+src/
+├── types.ts                    # App-wide types
+├── features/
+│   ├── auth/
+│   │   ├── auth.types.ts       # Shared within auth feature
+│   │   ├── login.tsx
+│   │   └── signup.tsx
+│   └── billing/
+│       ├── billing.types.ts
+│       └── invoice.tsx
+```
+
+### Rule 3: Monorepo-Level Sharing
+
+In a monorepo, types used across multiple packages go in a dedicated shared package:
+
+```
+packages/
+├── types/                      # Shared types package
+│   └── src/
+│       └── index.ts
+├── web-app/
+│   └── src/
+└── api/
+    └── src/
+```
+
+## Core Principle
+
+Share types across the **smallest number of modules** that require them. Don't pre-extract types "just in case" — colocate by default and widen scope only when a second consumer appears.