claude-toolkit 0.16.0 → 0.17.0

package/docs/best-practices/typescript/discriminated-unions.md

@@ -1,75 +0,0 @@
-# Discriminated Unions
-
-> Source: [TypeScript Discriminated Unions for Frontend Developers](https://www.totaltypescript.com/discriminated-unions-are-a-devs-best-friend) — Matt Pocock
-
-## The Problem: Bag of Optionals
-
-The naive approach to modeling state uses optional properties in a single type:
-
-```typescript
-// Don't do this
-type State = {
-  status: "loading" | "success" | "error";
-  data?: { id: string };
-  error?: Error;
-};
-```
-
-This allows **impossible states**: you can have `status: "success"` with no `data`, or `status: "loading"` with an `error`. TypeScript can't help you because every property is independently optional.
-
-## The Solution: Discriminated Unions
-
-Model each state as a distinct member of a union, with only the properties relevant to that state:
-
-```typescript
-type State =
-  | { status: "loading" }
-  | { status: "success"; data: { id: string } }
-  | { status: "error"; error: Error };
-```
-
-Now `data` only exists when `status` is `"success"`, and `error` only exists when `status` is `"error"`. Impossible states are unrepresentable.
-
-## Type Narrowing
-
-You must check the discriminator before accessing state-specific properties. This strictness is a feature:
-
-```typescript
-function handleState(state: State) {
-  if (state.status === "success") {
-    // TypeScript knows state.data exists here
-    console.log(state.data.id);
-  }
-
-  if (state.status === "error") {
-    // TypeScript knows state.error exists here
-    console.log(state.error.message);
-  }
-}
-```
-
-## Component Props Pattern
-
-Apply discriminated unions to component APIs with conditional properties:
-
-```typescript
-type ModalProps =
-  | {
-      variant: "with-description";
-      title: string;
-      description: string;
-      buttonText: string;
-    }
-  | {
-      variant: "base";
-      title: string;
-    };
-```
-
-This prevents consumers from passing `description` without `buttonText`, or using the wrong combination of props.
-
-## Why This Matters
-
-As Matt puts it: "Instead of a big optional bag of data, you'll start understanding the connections between data and UI."
-
-Discriminated unions force you to think about which data belongs together in which state — and the compiler enforces those relationships for you.

package/docs/best-practices/typescript/enums-alternatives.md

@@ -1,72 +0,0 @@
-# Enums & Alternatives
-
-> Source: [Why I Don't Like Enums](https://www.totaltypescript.com/why-i-dont-like-typescript-enums) — Matt Pocock
-
-## The Verdict
-
-**Avoid enums. Use `as const` objects with derived union types instead.**
-
-## Why Enums Are Problematic
-
-### 1. Numeric Enums Accept Raw Numbers
-
-Numeric enums allow passing any raw number where an enum value is expected — completely defeating the purpose of type safety.
-
-```typescript
-enum Direction {
-  Up,    // 0
-  Down,  // 1
-  Left,  // 2
-  Right, // 3
-}
-
-function move(dir: Direction) {}
-
-move(99); // No error! TypeScript allows this.
-```
-
-### 2. Inconsistent Behavior
-
-Numeric and string enums behave differently:
-- Numeric enums generate **bidirectional** mappings (value-to-key and key-to-value), doubling the runtime keys
-- String enums enforce stricter type-checking but don't generate reverse mappings
-- You can mix numeric and string values in a single enum (don't)
-
-### 3. Nominal Typing
-
-Enums use nominal typing — two enums with identical values are not interchangeable. This breaks from JavaScript's structural approach and creates surprising incompatibilities.
-
-### 4. Implementation Bugs
-
-The TypeScript repository has 71 open enum-related bug issues. The TS team has indicated many are architecturally unfixable.
-
-## The Alternative: `as const` Objects
-
-```typescript
-const Direction = {
-  Up: "up",
-  Down: "down",
-  Left: "left",
-  Right: "right",
-} as const;
-
-type Direction = (typeof Direction)[keyof typeof Direction];
-// "up" | "down" | "left" | "right"
-```
-
-This gives you:
-- A runtime object for lookups (`Direction.Up`)
-- A union type for type safety (`Direction`)
-- No surprising behavior
-- Standard JavaScript semantics
-
-## If You Must Use Enums
-
-Use **string enums only**. They behave more predictably, resemble the transpiled output more closely, and don't allow raw value assignment.
-
-```typescript
-enum Status {
-  Active = "active",
-  Inactive = "inactive",
-}
-```

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

@@ -1,119 +0,0 @@
-# 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

@@ -1,105 +0,0 @@
-# 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

@@ -1,87 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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

@@ -1,100 +0,0 @@
-# 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.