@fresho/router 0.0.1 → 0.0.4

package/docs/middleware.md

@@ -0,0 +1,441 @@
+# Middleware
+
+@fresho/router provides a composable middleware system for request/response processing. Middleware can handle cross-cutting concerns like authentication, logging, CORS, and rate limiting.
+
+## Table of Contents
+
+- [Middleware Basics](#middleware-basics)
+- [Authoring Middleware](#authoring-middleware)
+  - [Simple Middleware](#simple-middleware)
+  - [Typed Context Access](#typed-context-access)
+  - [Adding Context Properties](#adding-context-properties)
+- [Built-in Middleware](#built-in-middleware)
+  - [Authentication](#authentication)
+  - [CORS](#cors)
+  - [Error Handling](#errorhandler)
+  - [Logging](#logger)
+  - [Rate Limiting](#ratelimit)
+  - [Request ID](#requestid)
+  - [Timeout](#timeout)
+  - [Content Type Validation](#contenttype)
+- [Middleware Utilities](#middleware-utilities)
+  - [compose](#compose)
+
+---
+
+## Middleware Basics
+
+Middleware functions receive a context and a `next` function. They can:
+- Modify the request before it reaches the handler
+- Short-circuit the request (return early without calling `next`)
+- Modify the response after the handler completes
+- Add properties to the context for downstream middleware and handlers
+
+```typescript
+import type { Middleware } from '@fresho/router';
+
+const timing: Middleware = async (ctx, next) => {
+  const start = Date.now();
+  const response = await next();
+  const ms = Date.now() - start;
+  response.headers.set('X-Response-Time', `${ms}ms`);
+  return response;
+};
+```
+
+Add middleware to a router after the routes:
+
+```typescript
+import { router } from '@fresho/router';
+import { cors, errorHandler } from '@fresho/router/middleware';
+
+const api = router({
+  hello: router({
+    get: async () => ({ message: 'Hello' }),
+  }),
+}, cors(), errorHandler(), timing);
+```
+
+---
+
+## Authoring Middleware
+
+### Simple Middleware
+
+A middleware is a function that takes `(context, next)` and returns a `Response`:
+
+```typescript
+import type { Middleware, MiddlewareContext, MiddlewareNext } from '@fresho/router';
+
+const logger: Middleware = async (ctx: MiddlewareContext, next: MiddlewareNext) => {
+  console.log(`${ctx.request.method} ${ctx.request.url}`);
+  return next();
+};
+```
+
+### Typed Context Access
+
+Use `Middleware<Ctx>` to type the context (environment and middleware-added properties):
+
+```typescript
+interface AppContext {
+  env: {
+    JWT_SECRET: string;
+    DB: D1Database;
+  };
+  user?: { id: string };  // Optional - may not exist yet
+}
+
+const auth: Middleware<AppContext> = async (ctx, next) => {
+  // ctx.env is typed (env.JWT_SECRET, env.DB)
+  // Other context properties are Partial (user may be undefined)
+  const secret = ctx.env.JWT_SECRET;
+  ctx.user = await validateToken(ctx.request, secret);
+  return next();
+};
+```
+
+Note: In middleware, `env` is required but other context properties are `Partial` since middleware may be building them up. In handlers, all context properties are required (middleware has already run).
+
+### Adding Context Properties
+
+Middleware can add properties to the context. These are available to downstream middleware and route handlers:
+
+```typescript
+// Middleware adds user to context
+const auth: Middleware = async (ctx, next) => {
+  ctx.user = await authenticate(ctx.request);
+  return next();
+};
+
+// Route handler receives the context with user
+profile: router({
+  get: route.ctx<{ user: User }>()({
+    handler: async (c) => {
+      // c.user is typed as User
+      return { name: c.user.name };
+    },
+  }),
+})
+```
+
+The `route.ctx<T>()` builder tells TypeScript what context properties the handler expects.
+
+---
+
+## Built-in Middleware
+
+Import from `@fresho/router/middleware`:
+
+```typescript
+import {
+  // Authentication
+  basicAuth,
+  bearerAuth,
+  jwtAuth,
+  // CORS
+  cors,
+  // Utilities
+  errorHandler,
+  logger,
+  rateLimit,
+  requestId,
+  timeout,
+  contentType,
+} from '@fresho/router/middleware';
+```
+
+---
+
+### Authentication
+
+@fresho/router includes several authentication middleware options:
+
+- **`basicAuth`** - HTTP Basic authentication
+- **`bearerAuth`** - Simple bearer token authentication
+- **`jwtAuth`** - JWT authentication with signature verification
+- **`jwtSign`** - JWT token signing utility
+
+For complete documentation, examples, and patterns (cookie-based auth, token refresh, etc.), see the **[Authentication Guide](authentication.md)**.
+
+Quick example:
+
+```typescript
+import { jwtAuth } from '@fresho/router/middleware';
+
+const api = router({
+  profile: router({
+    get: route.ctx<{ user: { id: string } }>()({
+      handler: async (c) => ({ id: c.user.id }),
+    }),
+  }),
+},
+  jwtAuth({
+    secret: process.env.JWT_SECRET,
+    claims: (payload) => ({ user: { id: payload.sub } }),
+  })
+);
+```
+
+---
+
+### cors
+
+Cross-Origin Resource Sharing headers.
+
+```typescript
+cors({
+  // Allowed origins (default: '*')
+  // Can be: string, string[], RegExp, or (origin: string) => boolean
+  origin: 'https://example.com',
+  // or: origin: ['https://example.com', 'https://app.example.com'],
+  // or: origin: /\.example\.com$/,
+  // or: origin: (origin) => origin.endsWith('.example.com'),
+
+  // Allowed methods (default: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)
+  methods: ['GET', 'POST'],
+
+  // Allowed request headers (default: Content-Type, Authorization)
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Custom-Header'],
+
+  // Headers to expose to the browser
+  exposedHeaders: ['X-Total-Count'],
+
+  // Allow credentials (cookies, authorization headers)
+  credentials: true,
+
+  // Max age for preflight cache in seconds (default: 86400)
+  maxAge: 3600,
+
+  // Pass preflight to next handler instead of returning 204
+  preflightContinue: false,
+})
+```
+
+---
+
+### errorHandler
+
+Catches errors and returns JSON error responses.
+
+```typescript
+errorHandler({
+  // Custom error logger
+  log: (error, ctx) => {
+    console.error(`[${ctx.requestId}]`, error);
+  },
+
+  // Expose error details in response (default: false)
+  // WARNING: Set to false in production
+  expose: process.env.NODE_ENV === 'development',
+
+  // Custom error response formatter
+  formatter: (error, ctx) => {
+    return new Response(JSON.stringify({
+      error: error.message,
+      requestId: ctx.requestId,
+    }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  },
+})
+```
+
+Supports errors with `status` or `statusCode` properties for custom HTTP status codes.
+
+**Using HttpError:**
+
+Use the `HttpError` class to throw errors with specific status codes:
+
+```typescript
+import { route, router } from '@fresho/router';
+import { errorHandler, HttpError } from '@fresho/router/middleware';
+
+const api = router({
+  users: router({
+    $id: router({
+      get: async (c) => {
+        const user = await db.findUser(c.path.id);
+        if (!user) throw new HttpError('User not found', 404);
+        return user;
+      },
+    }),
+  }),
+}, errorHandler());
+```
+
+This keeps handler return types clean (just `User`, not `User | Response`) while still allowing custom error responses.
+
+---
+
+### logger
+
+Request/response logging.
+
+```typescript
+logger({
+  // Custom log function (default: console.log)
+  log: (message) => myLogger.info(message),
+
+  // Include request headers in log
+  includeHeaders: true,
+
+  // Include request body in log
+  includeBody: true,
+
+  // Custom log formatter
+  formatter: (info) => {
+    return `${info.method} ${info.url} ${info.status} ${info.duration}ms`;
+  },
+})
+```
+
+To skip logging for certain paths, use separate routers:
+
+```typescript
+// Health check without logging
+const healthRouter = router({
+  get: async () => ({ status: 'ok' }),
+});
+
+// API routes with logging
+const apiRouter = router({
+  users: router({ ... }),
+}, logger());
+
+// Combine
+const app = router({
+  health: healthRouter,
+  api: apiRouter,
+});
+```
+
+---
+
+### rateLimit
+
+Rate limiting with configurable store.
+
+```typescript
+rateLimit({
+  // Time window in milliseconds (default: 60000 = 1 minute)
+  windowMs: 60 * 1000,
+
+  // Maximum requests per window (default: 100)
+  max: 100,
+
+  // Custom key generator (default: IP address from headers)
+  keyGenerator: (ctx) => {
+    return ctx.user?.id || getClientIp(ctx.request);
+  },
+
+  // Custom store (default: in-memory)
+  store: new RedisRateLimitStore(redis),
+
+  // Don't count successful requests (status < 400)
+  skipSuccessfulRequests: true,
+
+  // Don't count failed requests (status >= 400)
+  skipFailedRequests: true,
+
+  // Custom handler for rate-limited requests
+  handler: (ctx) => {
+    return new Response(JSON.stringify({ error: 'Slow down!' }), {
+      status: 429,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  },
+})
+```
+
+Adds rate limit headers to responses:
+- `X-RateLimit-Limit`: Maximum requests allowed
+- `X-RateLimit-Remaining`: Remaining requests in window
+- `X-RateLimit-Reset`: ISO timestamp when the window resets
+
+---
+
+### requestId
+
+Adds a unique request ID to each request.
+
+```typescript
+requestId({
+  // Header name (default: 'X-Request-ID')
+  headerName: 'X-Request-ID',
+
+  // Custom ID generator (default: crypto.randomUUID())
+  generator: () => `req-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+})
+```
+
+Sets `ctx.requestId` and adds the ID to response headers.
+
+---
+
+### timeout
+
+Times out long-running requests.
+
+```typescript
+timeout({
+  // Timeout in milliseconds (required)
+  timeout: 5000,
+
+  // Custom timeout message
+  message: 'Request took too long',
+})
+```
+
+Returns 408 Request Timeout on timeout.
+
+---
+
+### contentType
+
+Validates request Content-Type header.
+
+```typescript
+contentType({
+  // Required: expected content types
+  types: ['application/json', 'application/x-www-form-urlencoded'],
+
+  // Skip validation for these methods (default: GET, HEAD, OPTIONS)
+  skipMethods: ['GET', 'HEAD', 'OPTIONS'],
+
+  // Custom error message
+  message: 'Only JSON is accepted',
+})
+```
+
+Returns 415 Unsupported Media Type on mismatch.
+
+---
+
+## Middleware Utilities
+
+### compose
+
+Combines multiple middleware into a single middleware:
+
+```typescript
+import { compose } from '@fresho/router/middleware';
+
+const security = compose(
+  cors(),
+  rateLimit({ max: 100 }),
+  errorHandler(),
+);
+
+const api = router({
+  users: router({ ... }),
+}, security);
+```
+
+---
+
+## See Also
+
+- [Authentication Guide](authentication.md) - JWT, cookies, token refresh
+- [Main Documentation](../README.md)

package/package.json

@@ -1,10 +1,68 @@
 {
   "name": "@fresho/router",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @fresho/router",
+  "engines": {
+    "node": ">=22"
+  },
+  "version": "0.0.4",
+  "description": "Type-safe route definitions with auto-generated clients and OpenAPI docs",
+  "license": "MIT",
+  "author": "fresho.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fresho-dev/router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fresho-dev/router/issues"
+  },
+  "homepage": "https://github.com/fresho-dev/router#README.md",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
+    "router",
+    "routing",
+    "typescript",
+    "type-safe",
+    "cloudflare-workers",
+    "deno",
+    "bun",
+    "http",
+    "api",
+    "rest",
+    "middleware",
+    "openapi",
+    "validation",
+    "schema"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.mts",
+      "import": "./dist/middleware/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/middleware/index.ts",
+    "clean": "rm -rf ./dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . && npm run typecheck",
+    "lint:fix": "biome check --write .",
+    "test": "npm run lint && node --import tsx --test 'src/**/*.test.ts'"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.17.0-beta.6",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE"
   ]
 }