types-and-interfaces

Types and Interfaces

The pattern

Claude Code uses three type patterns consistently: discriminated unions for output data shapes (the Zod outputSchema for tools that can return one of several kinds of result), Zod schemas as single source of truth for tool inputs (the schema drives runtime validation AND TypeScript types simultaneously via z.infer<>), and DeepImmutable wrappers for AppState to prevent accidental mutation.

The discipline is: define shape once, derive everything else. A Zod schema for a tool's input is defined once in inputSchema. The TypeScript type z.infer<typeof inputSchema> is derived from it. The LLM's JSON schema is derived from it. Runtime validation uses it. There is no second interface FooInput to drift from the schema.

Why this matters

The LLM produces JSON. JSON must be validated at runtime. TypeScript types catch compile-time issues. If these are defined separately, they drift: the TypeScript interface says limit?: number but the runtime validator doesn't check it's a number, leading to a crash at runtime. Zod solves this by being both the runtime validator and the source for z.infer<> types.

Discriminated unions for output data types (e.g. a file read that returns text, image, pdf, or unchanged) make exhaustive handling compiler-enforced. The TypeScript compiler narrows the type in each case branch. This eliminates an entire class of missing-case bugs. For errors, tools throw rather than returning an error variant — the success/error boundary is the thrown-exception contract, not the ToolResult shape.

AppState uses DeepImmutable<T> to prevent anyone from mutating state directly. All state changes must go through setAppState(prev => next), making state transitions traceable and atomic.

How to apply it

1. Tool inputs: always use Zod. Use lazySchema() wrapper from utils/lazySchema.ts to defer parsing until first access (faster startup). Use z.strictObject (not z.object) to reject unknown keys. Derive the TypeScript type with type MyInput = z.infer<typeof inputSchema>.
2. Tool output shapes: when a tool can return one of several kinds of result, define a Zod outputSchema using z.discriminatedUnion. Derive the TypeScript type with type Output = z.infer<typeof outputSchema>.
3. AppState fields: add to the AppState type in AppStateStore.ts. The type is DeepImmutable<{...}> — nested objects are also deeply immutable. You cannot .push() to arrays; you must spread them.
4. Message types: use the existing discriminated union. Don't add new message types without understanding the normalization pipeline — messages flow through multiple transformations before reaching the API.
5. Avoid any: use unknown for values whose type is genuinely unknown at the call site, then narrow with type guards.