TypeScript Handler Library Development

This skill helps you work with the `typed-handler` TypeScript library - a fluent, type-safe API for building request handlers with automatic validation that works with any validation library (Zod, Joi, Yup) and any web framework (Express, Fastify, Hono).

Project Overview

`typed-handler` provides a builder pattern for creating type-safe request handlers with these design principles:

Development Commands

**Package Manager**: Always use **pnpm** (version 8.15.0), never npm or yarn.

Setup

```bash

pnpm install # Install dependencies

pnpm prepare # Set up git hooks

```

Development

```bash

pnpm dev # Run dev server (watches examples/express-zod/index.ts)

pnpm type-check # Type checking

```

Testing

```bash

pnpm test # Run tests (Vitest)

pnpm test:watch # Watch mode

pnpm test:coverage # Coverage (requires 90% threshold)

pnpm test:types # Type tests (tsd)

```

Building & Quality

```bash

pnpm build # Build library (outputs to dist/)

pnpm lint # Lint with Biome

pnpm lint:fix # Lint and auto-fix

pnpm format # Format code

```

Publishing

```bash

pnpm changeset # Create changeset

pnpm version # Version packages

pnpm release # Build and publish

```

Architecture

Core Components

1. **Handler Class** (`src/handler.ts`): Main builder using immutable chain construction

2. **Validator System** (`src/validators/`): Auto-detects Zod, Joi, Yup; supports custom validators

3. **Framework Adapters** (`src/adapters/`): Bridge to Express, Fastify, Hono, or raw handlers

4. **Type System** (`src/types.ts`): Full type inference throughout the handler chain

5. **Configuration** (`src/config.ts`): Global and per-handler config with pluggable logger

Execution Flow

```

Input Data → Validate Input → Run Middleware (build context) →

Execute Handler → Validate Output → Return Result

```

Immutability Pattern (Critical)

All builder methods MUST:

1. Clone the current handler via `this.clone()`

2. Modify the clone

3. Return the clone with updated types

Example:

```typescript

.input(zodSchema) // Infer input type from schema

.use(async () => ({ user })) // Add context

.handle(async (input, ctx) => result) // Handler function

.output(zodSchema) // Validate output

```

Code Structure

```

src/

├── index.ts # Main exports

├── handler.ts # Handler class (core builder)

├── types.ts # Core types and type inference

├── config.ts # Configuration system

├── validators/registry.ts # Custom validator registration

├── adapters/ # Express, Fastify, Hono, Raw

├── errors/ # ValidationError, HandlerError

└── utils/response.ts # ResponseObject helpers

tests/

├── unit/

├── integration/

└── types/

```

Implementation Guidelines

Type Safety Requirements

1. **Preserve type inference**: Handler methods must return correctly typed handlers

2. **Context accumulation**: `.use()` merges types: `Handler<TInput, TContext & TNewContext, TOutput>`

3. **Input inference**: Support schema-based and explicit type parameter modes

4. **Type tests**: Add `tsd` tests for new inference scenarios

Framework Adapter Pattern

Adapters detect multi-input (object with `body`, `query`, `params`, `headers`) and extract appropriately:

```typescript

const input = handler.expectsMultiInput()

? { body: req.body, query: req.query, params: req.params, headers: req.headers }

: req.body;

const result = await handler.execute(input, { req, res });

```

Configuration

Testing Strategy

Common Biome Lint Ignores

Important Rules

1. **Always use pnpm**, never npm or yarn

2. **Preserve immutability** in all handler methods (clone before modify)

3. **Reference `TECHSPEC.md`** for detailed design decisions

4. **90% test coverage is enforced** - all new code must be well tested

5. **Type safety is critical** - all handler chains must have full type inference

6. **Git hooks run on pre-commit** (lint staged files) and **pre-push** (type-check + tests)

Example Usage

When working with this library:

1. Read the technical specification in `TECHSPEC.md` for design context

2. Ensure all modifications maintain immutability pattern

3. Run `pnpm type-check` and `pnpm test` before committing

4. Add type tests for any new type inference features

5. Maintain >90% test coverage for all changes