@minisylar/express-typed-router 1.6.2 → 1.7.1

package/README.md

@@ -1,79 +1,36 @@
 # @minisylar/express-typed-router
 
-A strongly-typed Express router with schema validation and automatic type inference for params, body, query, and middleware.
+A strongly typed Express router with **Standard Schema** validation, automatic type inference, and ✨ OpenAPI docs.
 
-## Features
+Define routes once, infer `params` / `body` / `query`, and generate a clean API spec for docs or client generation.
 
-- 🚀 **Full TypeScript support** with automatic type inference for route parameters
-- 🛡️ **Schema validation** for request body, query parameters, and route params (Zod, Yup, Valibot, Arktype,Joi,Effect,decoders,
-  ts.data.json,
-  unhoax, etc.)
-- 🔗 **Express.js compatibility** - works with Express 4 and Express 5
-- 🤝 **Mix with existing Express routes** - seamlessly integrates with your current codebase
-- 📝 **JSDoc documentation** with comprehensive examples
-- 📦 **ES Modules** and CommonJS support
-- 🎯 **Zero runtime overhead** for type checking
+---
 
-## Installation
+## What you get
 
-```bash
-npm install @minisylar/express-typed-router
-# or
-pnpm add @minisylar/express-typed-router
-# or
-yarn add @minisylar/express-typed-router
-```
-
-> **Note:** This package requires Express 4.18.0+ or Express 5.0.0+. For schema validation the library works with multiple popular schema libraries (examples below).
+- **Typed route handlers** — `req.params`, `req.body`, `req.query` inferred from your route + schema
+- **Typed middleware** — middleware can extend `req` and `res.locals`
+- **✨ OpenAPI docs** — generated from routes, schemas, and captured responses
+- **Schema-agnostic** — any Standard Schema-compatible validator (Zod, Yup, Valibot, Arktype, Joi...)
+- **Express 4 & 5** — common patterns supported
+- **Client-friendly output** — generate `generated-types.d.ts` and build any client wrapper
 
-### Schema Compatibility
+---
 
-This library is schema-agnostic: it provides a validation plumbing that works with multiple popular schema libraries. Below are short examples showing how you can use different schema libraries with the router. The router expects a schema-like object that can validate input; most adapters are straightforward.
+## Install
 
-Example with Zod (v3 or v4):
-
-```typescript
-import { z } from "zod"; // or "zod/v4" or "zod/v3" as needed
-const userSchema = z.object({ name: z.string() });
-router.post("/users", { bodySchema: userSchema }, handler);
-```
-
-Example with Yup:
-
-```javascript
-import * as yup from "yup";
-const userSchema = yup.object({ name: yup.string().required() });
-// pass the yup schema directly as bodySchema; the router will run validation
-router.post("/users", { bodySchema: userSchema }, handler);
-```
-
-Example with Valibot (valibot):
-
-```typescript
-import { object, string } from "valibot";
-const userSchema = object({ name: string() });
-router.post("/users", { bodySchema: userSchema }, handler);
-```
-
-Example with Arktype:
-
-```typescript
-import { object, string } from "arktype";
-const userSchema = object({ name: string() });
-router.post("/users", { bodySchema: userSchema }, handler);
+```bash
+npm install @minisylar/express-typed-router
+pnpm add @minisylar/express-typed-router
 ```
 
-If a schema library needs an adapter (for example to map its errors to the router's error format), add a small wrapper that runs validation and throws the expected error shape. See the project's examples for concrete adapter patterns.
-
-Note about Joi: Joi's TypeScript typings do not reliably infer the output type from the runtime schema shape. When using Joi you should either:
+Requires Express 4.18+ or Express 5.
 
-- provide an explicit generic type for the schema (e.g. `Joi.object<MyType>(...)`),
-- add a variable type annotation (e.g. `const s: Joi.ObjectSchema<MyType> = Joi.object(...)`), or
-- write a small adapter that validates at runtime and exposes a typed result to TypeScript.
+---
 
-## Quick Start
+## Quick start
 
-```javascript
+```ts
 import express from "express";
 import { z } from "zod";
 import { createTypedRouter } from "@minisylar/express-typed-router";
@@ -81,854 +38,392 @@ import { createTypedRouter } from "@minisylar/express-typed-router";
 const app = express();
 app.use(express.json());
 
-// Create a typed router
 const router = createTypedRouter();
 
-// Define routes - parameters are automatically typed!
-router.get("/users/:userId", (req, res) => {
-  // req.params.userId is automatically inferred as string
-  res.json({ userId: req.params.userId });
+router.get("/users/:id", (req, res) => {
+  res.json({ id: req.params.id }); // params.id: string
 });
 
-// Add validation with Zod schemas
 router.post(
   "/users",
-  {
-    bodySchema: z.object({
-      name: z.string(),
-      email: z.string().email(),
-    }),
-  },
+  { bodySchema: z.object({ name: z.string() }) },
   (req, res) => {
-    // req.body is validated and typed automatically
-    const { name, email } = req.body;
-    res.json({ id: "123", name, email });
-  }
+    res.json({ name: req.body.name }); // body.name: string
+  },
 );
 
-const expressRouter = router.getRouter();
-app.use("/api", expressRouter);
+app.use("/api", router.getRouter());
+app.use("/docs", router.docs({ title: "My API", version: "1.0.0" }));
+
 app.listen(3000);
+// http://localhost:3000/docs → interactive API docs
 ```
 
-That's it! Your routes now have full type safety and validation.
-
-## Works with Existing Express Routes
+---
 
-The typed router seamlessly integrates with your existing Express application - no need to rewrite everything!
+## Route typing
 
-```javascript
-import express from "express";
-import { createTypedRouter } from "@minisylar/express-typed-router";
+Path params are inferred from the route string. No extra types needed.
 
-const app = express();
-app.use(express.json());
-
-// Your existing Express routes continue to work
-app.get("/health", (req, res) => {
-  res.json({ status: "ok" });
-});
-
-// Existing Express router
-const legacyRouter = express.Router();
-legacyRouter.get("/legacy/:id", (req, res) => {
-  res.json({ id: req.params.id });
+```ts
+router.get("/users/:id", (req, res) => {
+  req.params.id; // string
 });
 
-// New typed router with full type safety
-const typedRouter = createTypedRouter();
-typedRouter.get("/users/:userId", (req, res) => {
-  // req.params.userId is automatically typed as string
-  res.json({ userId: req.params.userId });
+router.get("/flights/:from-:to", (req, res) => {
+  req.params.from; // string
+  req.params.to; // string
 });
 
-// Extract the Express router before using it
-const typedExpressRouter = typedRouter.getRouter();
-
-// Mix them all together
-app.use("/api/legacy", legacyRouter);
-app.use("/api/v2", typedExpressRouter);
-
-// Gradually migrate your routes to get type safety where you need it!
-app.listen(3000);
-```
-
-## The Main API: `createTypedRouter()`
-
-`createTypedRouter()` is the primary and most flexible way to create typed routers. It supports:
-
-- ✅ **Global middleware** with automatic type merging
-- ✅ **Per-route middleware** with type inference
-- ✅ **Zod validation** for params, body, and query
-- ✅ **Express 4 & 5 compatibility** with full route pattern support
-- ✅ **Chainable API** for easy configuration
-
-### Global Middleware
-
-**Important**: Unlike Express, middleware must be applied using method chaining or capturing returned routers. See the [FAQ section](#faq-and-common-patterns) for details.
-
-```typescript
-// Method chaining pattern (recommended)
-const router = createTypedRouter()
-  .useMiddleware(authMiddleware)
-  .useMiddleware(loggingMiddleware)
-  .useMiddleware(timestampMiddleware);
-
-// All routes automatically get types from all middleware
-router.get("/protected", (req, res) => {
-  // req.userId, req.requestId, req.timestamp all available and typed
+router.get("/posts/:year/:month?", (req, res) => {
+  req.params.year; // string
+  req.params.month; // string | undefined
 });
-
-// Alternative: capturing returned router
-const baseRouter = createTypedRouter();
-const routerWithMiddleware = baseRouter
-  .useMiddleware(authMiddleware)
-  .useMiddleware(loggingMiddleware);
-
-// Use the router with middleware applied
-routerWithMiddleware.get("/users", handler);
 ```
 
-### Per-Route Middleware
+Schema options infer body and query:
 
-```typescript
+```ts
 router.get(
-  "/admin/:userId",
-  {
-    middleware: [adminMiddleware, auditMiddleware],
+  "/search",
+  { querySchema: z.object({ q: z.string() }) },
+  (req, res) => {
+    req.query.q; // string — validated at runtime, typed at compile time
   },
+);
+
+router.post(
+  "/users",
+  { bodySchema: z.object({ name: z.string(), email: z.string().email() }) },
   (req, res) => {
-    // Types from both global AND per-route middleware are merged
-    // req.userId (global), req.isAdmin (adminMiddleware), req.auditId (auditMiddleware)
-  }
+    req.body.name; // string
+    req.body.email; // string
+  },
 );
 ```
 
-### Express 4 & 5 Route Pattern Support
-
-Works with **all** Express routing patterns:
-
-```typescript
-// Named parameters
-router.get("/users/:userId", handler); // { userId: string }
-
-// Multiple parameters
-router.get("/users/:userId/posts/:postId", handler); // { userId: string; postId: string }
+<details>
+<summary><strong>All supported route patterns</strong></summary>
 
-// Consecutive parameters with separators
+```ts
+router.get("/users/:id", handler); // { id: string }
 router.get("/flights/:from-:to", handler); // { from: string; to: string }
 router.get("/files/:name.:ext", handler); // { name: string; ext: string }
-
-// Optional parameters (Express 4)
 router.get("/posts/:year/:month?", handler); // { year: string; month?: string }
-
-// Repeating parameters (Express 5)
 router.get("/files/:path+", handler); // { path: string[] }
-
-// Optional repeating (Express 5)
 router.get("/search/:terms*", handler); // { terms?: string[] }
-
-// Optional segments (Express 5)
 router.get("/api{/:version}/users", handler); // { version?: string }
-
-// Regex constraints
 router.get("/users/:id(\\d+)", handler); // { id: string }
-
-// Wildcards
 router.get("/static/*", handler); // { "0": string }
 ```
 
-## Comprehensive Example
-
-```javascript
-import express from "express";
-import { z } from "zod";
-import { createTypedRouter } from "@minisylar/express-typed-router";
-
-const app = express();
-app.use(express.json());
-
-// Create router and define middleware inline (automatically typed!)
-const router = createTypedRouter()
-  .useMiddleware((req, res, next) => {
-    const token = req.headers.authorization;
-    req.userId = "user123";
-    req.isAdmin = token?.includes("admin") || false;
-    next();
-  })
-  .useMiddleware((req, res, next) => {
-    req.requestId = Math.random().toString(36);
-    console.log(`[${req.requestId}] ${req.method} ${req.path}`);
-    next();
-  });
-
-// Define schemas
-const CreateUserSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-  role: z.enum(["user", "admin"]).optional(),
-});
-
-const UserQuerySchema = z.object({
-  include: z.array(z.string()).optional(),
-  limit: z.coerce.number().int().positive().max(100).default(10),
-});
-
-// Routes with full type safety
-router.get(
-  "/users/:userId",
-  {
-    querySchema: UserQuerySchema,
-  },
-  (req, res) => {
-    // All properties are automatically typed:
-    const { userId } = req.params; // string (auto-inferred from route)
-    const { include, limit } = req.query; // from schema validation
-    const { userId: authUserId, isAdmin, requestId } = req; // from middleware
-
-    res.json({
-      id: userId,
-      authUserId,
-      isAdmin,
-      requestId,
-      include,
-      limit,
-    });
-  }
-);
-
-router.post(
-  "/users",
-  {
-    bodySchema: CreateUserSchema,
-  },
-  (req, res) => {
-    const { name, email, role } = req.body; // Fully typed from schema
-    const { userId, isAdmin, requestId } = req; // From middleware
-
-    if (role === "admin" && !isAdmin) {
-      return res.status(403).json({ error: "Insufficient permissions" });
-    }
-
-    res.status(201).json({
-      id: "new-user-id",
-      name,
-      email,
-      role: role || "user",
-      createdBy: userId,
-      requestId,
-    });
-  }
-);
-
-// Per-route middleware can also be inline
-router.delete(
-  "/users/:userId",
-  {
-    middleware: [
-      (req, res, next) => {
-        if (!req.isAdmin) {
-          return res.status(403).json({ error: "Admin required" });
-        }
-        req.hasAdminAccess = true;
-        next();
-      },
-    ], // No need for 'as const' - middleware arrays are automatically typed
-  },
-  (req, res) => {
-    // Types from BOTH global middleware AND per-route middleware
-    const { userId } = req.params; // From route
-    const { userId: authUserId, requestId } = req; // From global middleware
-    const { hasAdminAccess } = req; // From per-route middleware
-
-    res.json({
-      deleted: userId,
-      deletedBy: authUserId,
-      requestId,
-      hasAdminAccess,
-    });
-  }
-);
+</details>
 
-app.use("/api", router.getRouter());
-app.listen(3000, () => {
-  console.log("Server running on http://localhost:3000");
-});
-```
+---
 
-### With Explicit TypeScript Types
+## Middleware typing
 
-For TypeScript users who prefer explicit typing, you can define middleware with generics:
+Declare what a middleware adds to `req`, and that type flows into every handler that uses it.
 
-```typescript
-import { TypedMiddleware } from "@minisylar/express-typed-router";
+```ts
+import type { TypedMiddleware } from "@minisylar/express-typed-router";
 
-// Define typed middleware explicitly
-const authMiddleware: TypedMiddleware<{ userId: string; isAdmin: boolean }> = (
+const requireAuth: TypedMiddleware<{ userId: string; email: string }> = (
   req,
   res,
-  next
+  next,
 ) => {
-  const token = req.headers.authorization;
-  req.userId = "user123";
-  req.isAdmin = token?.includes("admin") || false;
+  const payload = jwt.verify(
+    req.headers.authorization!,
+    process.env.JWT_SECRET!,
+  );
+  req.userId = payload.userId;
+  req.email = payload.email;
   next();
 };
+```
 
-const loggingMiddleware: TypedMiddleware<{ requestId: string }> = (
-  req,
-  res,
-  next
-) => {
-  req.requestId = Math.random().toString(36);
-  console.log(`[${req.requestId}] ${req.method} ${req.path}`);
-  next();
-};
+**Global middleware** — applied to all routes on the router:
 
-// Use the explicitly typed middleware
+```ts
 const router = createTypedRouter()
-  .useMiddleware(authMiddleware)
+  .useMiddleware(requireAuth)
   .useMiddleware(loggingMiddleware);
 
-// Rest of the routes work the same way...
-```
-
-## TypeScript Features
-
-For TypeScript users, the library provides advanced type safety features:
-
-### Typed Middleware
-
-Define middleware that extends the request object with typed properties:
-
-```typescript
-import { TypedMiddleware } from "@minisylar/express-typed-router";
-
-const authMiddleware: TypedMiddleware<{ userId: string; isAdmin: boolean }> = (
-  req,
-  res,
-  next
-) => {
-  req.userId = "user123";
-  req.isAdmin = true;
-  next();
-};
-
-// Add to router - types are automatically merged
-router.useMiddleware(authMiddleware);
-
-router.get("/protected", (req, res) => {
-  // TypeScript knows about req.userId and req.isAdmin
-  const { userId, isAdmin } = req;
-  res.json({ userId, isAdmin });
+router.get("/profile", (req, res) => {
+  req.userId; // string — from requireAuth
+  req.requestId; // string — from loggingMiddleware
 });
 ```
 
-### Per-Route Middleware with Type Merging
+**Per-route middleware** — scoped to one route, types still merge:
 
-```typescript
-const adminMiddleware: TypedMiddleware<{ hasAdminAccess: true }> = (
-  req,
-  res,
-  next
-) => {
-  if (!req.isAdmin) {
-    return res.status(403).json({ error: "Admin required" });
-  }
-  req.hasAdminAccess = true;
-  next();
-};
-
-router.get(
-  "/admin/:userId",
-  {
-    middleware: [adminMiddleware], // No need for 'as const' - arrays are automatically typed
-  },
-  (req, res) => {
-    // Types from BOTH global and per-route middleware are available
-    const { userId } = req.params; // From route params
-    const { userId: authUserId } = req; // From global middleware
-    const { hasAdminAccess } = req; // From per-route middleware
-
-    res.json({ userId, authUserId, hasAdminAccess });
-  }
-);
-```
-
-### Advanced Route Parameter Types
-
-The library automatically infers complex Express route patterns:
-
-```typescript
-// Express 5 repeating parameters
-router.get("/files/:path+", (req, res) => {
-  const { path } = req.params; // string[] - automatically inferred!
-});
-
-// Optional parameters
-router.get("/posts/:year/:month?", (req, res) => {
-  const { year, month } = req.params; // { year: string; month?: string }
-});
-
-// Complex patterns with separators
-router.get("/flights/:from-:to", (req, res) => {
-  const { from, to } = req.params; // { from: string; to: string }
+```ts
+router.get("/admin", { middleware: [requireAdmin] }, (req, res) => {
+  req.userId; // from global middleware
+  req.isAdmin; // from requireAdmin
 });
 ```
 
-## Alternative API Styles
+> **Note:** `useMiddleware` returns a new router instance. Use method chaining or capture the return value — see [Common Patterns](#common-patterns).
 
-<details>
-<summary><strong>🎯 createTypedRouterWithMiddleware(...middleware)</strong> - Pre-configured with middleware</summary>
+---
 
-For developers who prefer setting up all middleware upfront:
+## ✨ OpenAPI and docs
 
-```typescript
-import {
-  createTypedRouterWithMiddleware,
-  TypedMiddleware,
-} from "@minisylar/express-typed-router";
+Mount the docs endpoint and get a Scalar-based interactive UI plus raw OpenAPI JSON — all generated automatically from your routes.
 
-const authMiddleware: TypedMiddleware<{ userId: string; isAdmin: boolean }> = (
-  req,
-  res,
-  next
-) => {
-  req.userId = "user123";
-  req.isAdmin = true;
-  next();
-};
-
-const timestampMiddleware: TypedMiddleware<{ timestamp: Date }> = (
-  req,
-  res,
-  next
-) => {
-  req.timestamp = new Date();
-  next();
-};
-
-// Create router with middleware - types are automatically merged
-const router = createTypedRouterWithMiddleware(
-  authMiddleware,
-  timestampMiddleware
+```ts
+app.use(
+  "/docs",
+  router.docs({
+    title: "My API",
+    version: "1.0.0",
+    description: "Public API docs",
+    specOutputPath: "./openapi.json", // write spec to disk (enables watch mode)
+  }),
 );
-
-router.get("/protected", (req, res) => {
-  // req.userId, req.isAdmin, and req.timestamp are all typed correctly!
-  res.json({
-    userId: req.userId, // string
-    isAdmin: req.isAdmin, // boolean
-    timestamp: req.timestamp, // Date
-  });
-});
-```
-
-</details>
-
-<details>
-<summary><strong>⚙️ createTypedRouterWithConfig(config)</strong> - Custom configuration</summary>
-
-For applications that need custom error handling or configuration:
-
-```typescript
-import { createTypedRouterWithConfig } from "@minisylar/express-typed-router";
-
-const router = createTypedRouterWithConfig({
-  errorHandler: (error, req, res, next) => {
-    if (error.name === "ZodError") {
-      res.status(400).json({
-        error: "Validation failed",
-        details: error.errors,
-      });
-    } else {
-      next(error);
-    }
-  },
-});
-
-// Use normally
-router.get("/users/:id", (req, res) => {
-  // Custom error handling is automatically applied
-  const { id } = req.params;
-  res.json({ id });
-});
-```
-
-</details>
-
-## Express 4 & 5 Route Pattern Support
-
-This library provides **complete TypeScript inference** for all Express.js routing patterns across both Express 4 and 5:
-
-### Basic Patterns (Express 4 & 5)
-
-```typescript
-// Named parameters
-router.get("/users/:userId", handler);
-// → { userId: string }
-
-// Multiple parameters
-router.get("/users/:userId/posts/:postId", handler);
-// → { userId: string; postId: string }
-
-// Parameters with separators
-router.get("/flights/:from-:to", handler);
-// → { from: string; to: string }
-
-router.get("/files/:name.:ext", handler);
-// → { name: string; ext: string }
-```
-
-### Advanced Patterns (Express 4)
-
-```typescript
-// Optional parameters
-router.get("/posts/:year/:month?", handler);
-// → { year: string; month?: string }
-
-// Regex constraints
-router.get("/users/:id(\\d+)", handler);
-// → { id: string }
-
-// Wildcards
-router.get("/files/*", handler);
-// → { "0": string }
-
-router.get("/api/*/files/*", handler);
-// → { "0": string; "1": string }
+// GET /docs              → Scalar UI
+// GET /docs/openapi.json → raw OpenAPI 3.1 spec
 ```
 
-### Express 5 Enhanced Patterns
+**What's generated automatically:**
 
-```typescript
-// Repeating parameters (one or more)
-router.get("/files/:path+", handler);
-// → { path: string[] }
+- route paths, methods, and path parameters
+- query and body schemas (from `querySchema` / `bodySchema`)
+- response examples — captured from real `res.json()` calls, no manual input needed
+- tags and summaries — inferred from route paths, or set manually
 
-// Optional repeating (zero or more)
-router.get("/search/:terms*", handler);
-// → { terms?: string[] }
-
-// Optional segments with braces
-router.get("/api{/:version}/users", handler);
-// → { version?: string }
-
-router.get("/files{/:category}/:filename", handler);
-// → { category?: string; filename: string }
-```
-
-### Real-World Examples
-
-```typescript
-// E-commerce routes
-router.get("/products/:category/:subcategory?", handler);
-// → { category: string; subcategory?: string }
-
-// File serving with optional versioning
-router.get("/assets{/:version}/:filename.:ext", handler);
-// → { version?: string; filename: string; ext: string }
-
-// API versioning with wildcards
-router.get("/api/v:version/*", handler);
-// → { version: string; "0": string }
-
-// Multi-segment paths (Express 5)
-router.get("/docs/:sections+", handler);
-// → { sections: string[] }
-```
+**Custom route metadata:**
 
-All patterns work seamlessly with Zod validation and middleware type inference!
-
-## API Reference
-
-### `createTypedRouter()` - Main API
-
-Creates a typed router instance with full flexibility for middleware and validation.
-
-```typescript
-const router = createTypedRouter();
-
-// Add global middleware (chainable)
-router.useMiddleware(middleware1)
-      .useMiddleware(middleware2);
-
-// All HTTP methods supported
-router.get(path, options?, handler)
-router.post(path, options?, handler)
-router.put(path, options?, handler)
-router.patch(path, options?, handler)
-router.delete(path, options?, handler)
-router.options(path, options?, handler)
-router.head(path, options?, handler)
-router.all(path, options?, handler)
-```
-
-**Route Options:**
-
-- `bodySchema`: Zod schema for request body validation
-- `querySchema`: Zod schema for query parameter validation
-- `paramsSchema`: Zod schema for route parameter validation (optional - auto-inferred from path)
-- `middleware`: Array of typed middleware functions for this specific route
-
-**Examples:**
-
-```typescript
-// Simple route with auto-inferred params
-router.get("/users/:id", (req, res) => {
-  const { id } = req.params; // string
-});
-
-// With body validation
+```ts
 router.post(
   "/users",
   {
-    bodySchema: z.object({ name: z.string() }),
-  },
-  (req, res) => {
-    const { name } = req.body; // string
-  }
-);
-
-// With per-route middleware
-router.get(
-  "/admin",
-  {
-    middleware: [authMiddleware, adminMiddleware] as const,
+    bodySchema: CreateUserSchema,
+    responseSchema: UserSchema, // typed responses in the spec
+    tags: ["Users"],
+    summary: "Create a user",
+    description: "Creates a new account and returns the created user.",
   },
-  (req, res) => {
-    // Types from both middleware are available
-  }
+  handler,
 );
 ```
 
-### `TypedMiddleware<T>`
+**Multi-router docs** — one `.docs()` call covers everything:
 
-Type for middleware functions that extend the request object.
+```ts
+const api = createTypedRouter()
+  .use("/users", usersRouter)
+  .use("/auth", authRouter);
 
-```typescript
-const authMiddleware: TypedMiddleware<{ userId: string }> = (
-  req,
-  res,
-  next
-) => {
-  req.userId = "123";
-  next();
-};
-```
-
-<details>
-<summary><strong>Alternative APIs</strong></summary>
-
-### `createTypedRouterWithConfig(config)`
+app.use("/docs", api.docs({ title: "My API", version: "1.0.0" }));
+// Discovers all sub-routers and merges routes with correct prefixes
 
-```typescript
-const router = createTypedRouterWithConfig({
-  errorHandler: (error, req, res, next) => {
-    // Custom error handling
-  },
-});
 ```
 
-### `createTypedRouterWithMiddleware(...middleware)`
+### Schema library support for docs
 
-```typescript
-const router = createTypedRouterWithMiddleware(middleware1, middleware2);
-```
+All validators work for **request validation**. For **OpenAPI schema generation** (showing field names and types in the spec), some libraries need an extra converter package installed in your project. This library auto-detects them at runtime — install the one you need and it just works, no config required.
 
-</details>
+| Library | Validation | Docs schema | Extra install |
+|---|---|---|---|
+| Zod 4 | ✅ | ✅ | none — built-in |
+| Zod 3 | ✅ | ✅ | `zod-to-json-schema` |
+| Valibot | ✅ | ✅ | `@valibot/to-json-schema` |
+| ArkType | ✅ | ✅ | none — built-in |
+| Effect | ✅ | ✅ | none — built-in |
+| Yup | ✅ | ⚠️ | not supported — no official JSON Schema converter |
+| Joi | ✅ | ⚠️ | not supported — no official JSON Schema converter |
+| Decoders / ts.data.json / unhoax | ✅ | ⚠️ | not supported — no schema introspection |
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the library
-pnpm build
-
-# Run type checking
-pnpm type-check
-
-# Build in watch mode
-pnpm build:watch
-```
+> **⚠️ Partial docs** means routes still appear in the spec with paths, methods, and captured response examples — only the request body/query field shapes are missing.
 
-## License
+---
 
-ISC
+## Client types
 
-## FAQ and Common Patterns
+The library generates an OpenAPI spec. Feed it to `openapi-typescript` to get a `.d.ts` file, then use it with any HTTP client.
 
-### Middleware Behavior Differences from Express
+### Generate types
 
-#### IMPORTANT: Router Middleware and Route Registration
+One-time:
 
-When using middleware with `express-typed-router`, there's an important difference from standard Express behavior:
+```bash
+npx openapi-typescript http://localhost:3000/docs/openapi.json -o ./generated-types.d.ts
+```
 
-**In Express**, middleware added with `router.use()` applies to all routes registered _after_ it:
+Watch mode — types regenerate automatically as routes change (requires `specOutputPath` set above):
 
-```javascript
-// Express middleware behavior
-const router = express.Router();
-router.use(authMiddleware); // Apply middleware
-router.get("/route1", handler1); // Has authMiddleware
-router.use(logMiddleware); // Apply another middleware
-router.get("/route2", handler2); // Has BOTH auth and log middleware
+```bash
+npx openapi-typescript ./openapi.json -o ./generated-types.d.ts --watch
 ```
 
-**In express-typed-router**, `useMiddleware()` returns a _new router instance_ for type safety:
+### Use with `openapi-fetch`
 
-```typescript
-// ❌ WON'T WORK - middleware not applied to route
-const router = createTypedRouter();
-router.useMiddleware(authMiddleware); // Returns new router that isn't captured
-router.get("/route", handler); // Original router without middleware!
+```ts
+import createClient from "openapi-fetch";
+import type { paths } from "./generated-types";
 
-// ✅ CORRECT - chain methods (recommended)
-const router = createTypedRouter()
-  .useMiddleware(authMiddleware)
-  .get("/route", handler);
+const client = createClient<paths>({ baseUrl: "http://localhost:3000/api" });
 
-// ✅ CORRECT - chain directly from middleware call
-const router = createTypedRouter();
-router.useMiddleware(authMiddleware).get("/route", handler);
+// Path, params, body, and response all typed from the spec
+const { data } = await client.GET("/users/{id}", {
+  params: { path: { id: "123" } },
+});
 
-// ✅ ALSO CORRECT - use per-route middleware
-const router = createTypedRouter();
-router.get("/route", { middleware: [authMiddleware] }, handler);
+const { data: user } = await client.POST("/users", {
+  body: { name: "Alice", email: "alice@example.com" },
+});
 ```
 
-This design is necessary for full type safety but requires a different pattern than standard Express.
+### Roll your own client
 
-### Common Express Patterns vs express-typed-router
+If you prefer not to add `openapi-fetch`, use the generated types directly with standard `fetch`:
 
-Here are common Express patterns and how to achieve them with express-typed-router:
+```ts
+import type { paths } from "./generated-types";
 
-#### Pattern 1: Adding middleware to specific routes
+type Body<
+  P extends keyof paths,
+  M extends keyof paths[P],
+> = paths[P][M] extends {
+  requestBody?: { content: { "application/json": infer B } };
+}
+  ? B
+  : never;
+
+type Res<
+  P extends keyof paths,
+  M extends keyof paths[P],
+> = paths[P][M] extends {
+  responses: { 200: { content: { "application/json": infer R } } };
+}
+  ? R
+  : unknown;
+
+async function apiFetch<P extends keyof paths, M extends keyof paths[P]>(
+  path: P,
+  options: {
+    method: M;
+    data?: Body<P, M>;
+    params?: {
+      path?: Record<string, string | number>;
+      query?: Record<string, string | number | boolean>;
+    };
+  },
+): Promise<Res<P, M>> {
+  const url = new URL(
+    String(path).replace(/\{([^}]+)\}/g, (_, key) =>
+      encodeURIComponent(String(options.params?.path?.[key] ?? "")),
+    ),
+    "/api",
+  );
+
+  for (const [k, v] of Object.entries(options.params?.query ?? {})) {
+    url.searchParams.set(k, String(v));
+  }
 
-**Express:**
+  const res = await fetch(url, {
+    method: String(options.method).toUpperCase(),
+    headers: options.data ? { "Content-Type": "application/json" } : undefined,
+    body: options.data ? JSON.stringify(options.data) : undefined,
+  });
 
-```javascript
-const router = express.Router();
-router.get("/public", publicHandler);
-router.use(authMiddleware); // Only affects routes below
-router.get("/private", privateHandler); // Has authMiddleware
-```
+  return res.json();
+}
 
-**express-typed-router:**
+// Path, method, body, and params all typed from the spec
+await apiFetch("/users/{id}", {
+  method: "get",
+  params: { path: { id: "123" } },
+});
+await apiFetch("/users", {
+  method: "post",
+  data: { name: "Alice", email: "alice@example.com" },
+});
+await apiFetch("/search", { method: "get", params: { query: { q: "hello" } } });
+```
 
-```typescript
-// Option 1: Separate routers
-const publicRouter = createTypedRouter();
-publicRouter.get("/public", publicHandler);
+The same type utilities work with axios — swap `fetch` for `axios.request`.
 
-const privateRouter = createTypedRouter().useMiddleware(authMiddleware);
-privateRouter.get("/private", privateHandler);
+---
 
-// Combine in Express
-app.use(publicRouter.getRouter());
-app.use(privateRouter.getRouter());
+## Common patterns
 
-// Option 2: Per-route middleware
-const router = createTypedRouter();
-router.get("/public", publicHandler);
-router.get("/private", { middleware: [authMiddleware] }, privateHandler);
-```
+### Migrate an existing Express app
 
-#### Pattern 2: Adding middleware for a group of routes
+No rewrite required. Add typed routes alongside existing ones.
 
-**Express:**
+```diff
+  const app = express();
 
-```javascript
-const router = express.Router();
-router.get("/public", handler);
++ const typedRouter = createTypedRouter();
++ typedRouter.get("/users/:id", (req, res) => {
++   res.json({ id: req.params.id }); // typed
++ });
 
-// Only admin routes have auth middleware
-const adminRouter = express.Router();
-adminRouter.use(authMiddleware);
-adminRouter.get("/users", adminHandler1);
-adminRouter.get("/settings", adminHandler2);
+  app.get("/health", (_req, res) => res.json({ ok: true })); // untouched
 
-router.use("/admin", adminRouter);
++ app.use("/api", typedRouter.getRouter());
++ app.use("/docs", typedRouter.docs());
 ```
 
-**express-typed-router:**
-
-```typescript
-const publicRouter = createTypedRouter();
-publicRouter.get("/public", handler);
+### Middleware on a group of routes
 
-// Admin router with middleware
-const adminRouter = createTypedRouter().useMiddleware(authMiddleware);
-adminRouter.get("/users", adminHandler1);
-adminRouter.get("/settings", adminHandler2);
+```ts
+// All admin routes share auth middleware and its types
+const adminRouter = createTypedRouter()
+  .useMiddleware(requireAuth)
+  .get("/users", listUsersHandler)
+  .delete("/users/:id", deleteUserHandler);
 
-// Combine with Express
-app.use(publicRouter.getRouter());
 app.use("/admin", adminRouter.getRouter());
 ```
 
-#### Pattern 3: Middleware with dynamically added routes
+### Per-feature routers, one doc endpoint
 
-**Express:**
+```ts
+import {usersRouter} from "./v1/usersRouter"
+....
 
-```javascript
-const router = express.Router();
-router.use(middleware);
+const api = createTypedRouter()
+  .use("/users", usersRouter)
+  .use("/orders", ordersRouter)
+  .use("/auth", authRouter);
 
-// Later, routes are added dynamically
-function addRoute(path, handler) {
-  router.get(path, handler); // Has middleware
-}
+app.use("/api/v1", api.getRouter());
+app.use("/docs", api.docs({ title: "My API", version: "1.0.0" }));
 ```
 
-**express-typed-router:**
+---
 
-```typescript
-// Option 1: Pass the router to the function
-const router = createTypedRouter().useMiddleware(middleware);
+## API surface
 
-function addRoute(router, path, handler) {
-  router.get(path, handler);
-}
+|                                          |                                                  |
+| ---------------------------------------- | ------------------------------------------------ |
+| `createTypedRouter()`                    | Create a router                                  |
+| `createTypedRouterWithMiddleware(...mw)` | Create a router pre-configured with middleware   |
+| `createTypedRouterWithConfig(config)`    | Create a router with custom error handling       |
+| `router.useMiddleware(mw)`               | Add typed global middleware (returns new router) |
+| `router.use(prefix, subRouter)`          | Mount a sub-router                               |
+| `router.getRouter()`                     | Get the underlying Express router                |
+| `router.docs(options)`                   | Get the docs + OpenAPI spec router               |
+| `TypedMiddleware<T>`                     | Type helper for middleware that extends `req`    |
 
-// Option 2: Factory function
-function createRouteAdder(middleware) {
-  const router = createTypedRouter().useMiddleware(middleware);
+---
 
-  return {
-    addRoute: (path, handler) => router.get(path, handler),
-    getRouter: () => router.getRouter(),
-  };
-}
+## Development
 
-const routeAdder = createRouteAdder(middleware);
-routeAdder.addRoute("/path", handler);
-app.use(routeAdder.getRouter());
+```bash
+pnpm install
+pnpm build
+pnpm type-check
+pnpm build:watch
 ```
 
-### Using express-typed-router in JavaScript
-
-JavaScript users don't need to worry about TypeScript types but should still follow the middleware chaining pattern:
-
-```javascript
-// JavaScript usage
-const { createTypedRouter } = require("@minisylar/express-typed-router");
+---
 
-const router = createTypedRouter().useMiddleware((req, res, next) => {
-  req.user = { id: "user123" };
-  next();
-});
-
-router.get("/users", (req, res) => {
-  // req.user is available but not typed (JavaScript doesn't have types)
-  res.json({ userId: req.user.id });
-});
-
-module.exports = router.getRouter();
-```
-
-## Contributing
+## License
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+ISC