@mpen/routekit 0.1.0

package/README.md

@@ -0,0 +1,526 @@
+# @mpen/routekit
+
+Typed server-side routing utilities for Fetch-compatible runtimes.
+
+`routekit` is a small router around the platform `Request`/`Response` APIs. It matches
+`URLPattern` routes, runs typed middleware, supports schema-backed handlers with Zod or
+Valibot, can expose route metadata as OpenAPI, and can generate a typed API client from
+the same router definitions.
+
+## Installation
+
+```bash
+bun add @mpen/routekit
+```
+
+Install the schema library you plan to use:
+
+```bash
+bun add zod
+# or
+bun add valibot @valibot/to-json-schema
+```
+
+## Quick Start
+
+```ts
+import { Router, ok } from '@mpen/routekit'
+
+const router = new Router()
+
+router.get('/', () => ok({ message: 'Hello World!' }))
+
+router.get('/users/:id', ({ path }) => {
+    const { id } = path as { id: string }
+    return ok({ id })
+})
+
+export default router
+```
+
+Use the router anywhere a Fetch-compatible handler is accepted:
+
+```ts
+import router from './router'
+
+Bun.serve({
+    port: 3000,
+    fetch: router.fetch,
+})
+```
+
+You can also exercise a router directly in tests:
+
+```ts
+const response = await router.fetch(new Request('https://example.com/users/123'))
+expect(await response.json()).toEqual({ id: '123' })
+```
+
+## Routing
+
+Routes can be registered with method helpers:
+
+```ts
+router.get('/health', () => text('ok'))
+router.head('/health', () => noContent())
+router.post('/items', async ({ req }) => ok(await req.json()))
+router.put('/items/:id', () => text('updated'))
+router.patch('/items/:id', () => text('patched'))
+router.delete('/items/:id', () => text('deleted'))
+```
+
+Or with a full route definition:
+
+```ts
+import { HttpMethod } from '@mpen/http'
+
+router.add({
+    name: 'items.detail',
+    method: HttpMethod.GET,
+    path: '/items/:id',
+    accept: 'application/json',
+    meta: {
+        openapi: {
+            summary: 'Fetch an item',
+        },
+    },
+    handler: ({ path }) => ok({ id: (path as { id: string }).id }),
+})
+```
+
+`path` may be a string or a `URLPattern`. Named path parameters are exposed on
+`ctx.path`. When a route name is omitted, routekit derives one from the method and
+path so tooling such as API client generation still has a stable name to work with.
+
+Routers can be mounted under a prefix:
+
+```ts
+const api = new Router()
+api.get('/health', () => new Response('ok'))
+
+const app = new Router()
+app.mount('/api', api)
+```
+
+## Handler Results
+
+Handlers may return:
+
+- a `Response`
+- a `RoutekitResponse` from helpers such as `ok()`, `response()`, `text()`, or `html()`
+- a `string`, `Uint8Array`, `Buffer`, or `ReadableStream` for raw native bodies
+- a structured object wrapped with `ok()` for content negotiation
+- an async generator that yields typed response directives
+
+For structured responses, return `ok(value)`. When no `Content-Type` is set, the router
+serializes the body using the request's `Accept` header:
+
+```ts
+router.get('/profile', () => ok({ name: 'Ada' }))
+```
+
+Use `text()` and `html()` for represented bodies that should skip negotiation:
+
+```ts
+router.get('/health', () => text('ok'))
+```
+
+Streaming handlers yield explicit directives:
+
+```ts
+router.get('/events', async function* () {
+    yield head(HttpStatus.OK, { 'content-type': 'text/plain; charset=utf-8' })
+    yield chunk('hello ')
+    yield chunk('world')
+})
+```
+
+## Configuration
+
+Request body parsers, response body serializers, and loggers are configured with fluent
+router methods. `add...` methods append to inherited configuration, while `set...`
+methods replace inherited configuration for that router subtree.
+
+```ts
+const router = new Router()
+    .addRequestBodyParser(customRequestBodyParser)
+    .addResponseBodySerializer(customResponseBodySerializer)
+    .setLogger(logger)
+```
+
+Use `setRequestBodyParsers()` or `setResponseBodySerializers()` when a subtree should
+have an exact parser or serializer list instead of inheriting from its parent.
+
+Parser and serializer `mediaTypes` entries may include an Accept-style `q`
+preference. Client `Accept` quality wins for responses; server `q` values resolve
+ties before registration order.
+
+## Middleware
+
+Middleware runs in registration order and can add fields to the request context. The
+added fields are reflected in handler types.
+
+```ts
+import type { ContextMiddleware } from '@mpen/routekit'
+
+const auth: ContextMiddleware<{ userId: string }> = (ctx) => {
+    ctx.userId = 'user-123'
+}
+
+const router = new Router().use(auth)
+
+router.get('/me', ({ userId }) => ok({ userId }))
+```
+
+`router.use(middleware)` applies middleware to the router itself, not only to routes
+registered after the call. Middleware registered on a router runs for every matching
+route on that router, including routes that were added before the middleware was
+registered.
+
+Use `router.mount()` with inline configuration when middleware should apply to a subset
+of routes:
+
+```ts
+const router = new Router()
+
+router.get('/health', () => text('ok'))
+
+router.mount({ prefix: '/admin', middleware: auth }, (admin) => {
+    admin.get('/users', ({ userId }) => ok({ userId }))
+    admin.post('/users', ({ userId }) => ok({ createdBy: userId }))
+})
+
+router.get('/status', () => ok({ status: 'up' }))
+```
+
+In this example, `auth` runs for `/admin/users` but not for `/health` or `/status`.
+
+Middleware that creates a response declares it with a schema-bound factory. Its response
+metadata is inherited automatically by every affected route.
+
+```ts
+import { HttpStatus } from '@mpen/http'
+import { response } from '@mpen/routekit'
+import { defineZodMiddleware } from '@mpen/routekit/routes'
+import { z } from 'zod'
+
+const requireAuth = defineZodMiddleware({
+    responses: {
+        [HttpStatus.UNAUTHORIZED]: z.object({ error: z.literal('unauthorized') }),
+    },
+    run: (_ctx, { respond }) =>
+        respond(response({ error: 'unauthorized' }, { status: HttpStatus.UNAUTHORIZED })),
+})
+```
+
+### Encapsulation and Inheritance
+
+`mount()` composes routers from inline route blocks or existing router instances:
+
+- `router.mount({ prefix, middleware }, configure)` creates a scoped inline router.
+  Use it when routes are declared together and should share extra middleware or config.
+- `router.mount(prefix, childRouter)` attaches an existing router, optionally under a
+  path prefix. Use it when routes live in another module or should be reusable as their
+  own router.
+- `router.mount({ prefix, middleware }, childRouter)` wraps an existing router with
+  additional runtime middleware.
+
+Parent middleware runs first, followed by scoped middleware and then child router
+middleware. Request body parsers, response body serializers, loggers, and error handlers
+inherit through the same router tree. Child routers can append parser/serializer config
+or replace it with `setRequestBodyParsers()` and `setResponseBodySerializers()`.
+
+> [!IMPORTANT]
+> `router.use(middleware)` is retroactive for that router. If you add a route, create a
+> scoped mount, or mount a child router and later call `router.use(auth)`, `auth` still runs
+> for those earlier entries. To mount a child router without that middleware, keep the
+> parent router middleware-free and apply middleware only to scoped mounts or child routers
+> that need it.
+
+A mounted router still keeps its own TypeScript context boundary. Handlers declared
+inside the mounted router are typed from that router's middleware, even though parent
+middleware also runs at runtime. Use inline `mount({ middleware }, router => { ... })`
+when handlers should see scoped middleware context in their TypeScript types.
+
+This differs from some other routers:
+
+- [Express](https://expressjs.com/en/guide/using-middleware.html) uses an ordered
+  middleware stack. Middleware registered before a mounted router can wrap it; middleware
+  registered after the mount does not retroactively affect it.
+- [Hono](https://hono.dev/docs/guides/middleware) also runs middleware in registration
+  order, and [route grouping](https://hono.dev/docs/api/routing#grouping-ordering) adds
+  the child router's stored routes to the parent at the time `route()` is called.
+- [Fastify](https://fastify.dev/docs/latest/Reference/Encapsulation/) is closer to
+  RouteKit's model: child contexts can access parent plugins, hooks, and decorators,
+  while sibling contexts stay isolated.
+- [Elysia](https://elysiajs.com/tutorial/getting-started/encapsulation/) encapsulates
+  hooks to their own instance by default and exposes explicit `local`, `scoped`, and
+  `global` scope controls.
+
+Middleware can also wrap downstream results:
+
+```ts
+import { defineMiddleware } from '@mpen/routekit'
+
+router.use(
+    defineMiddleware({
+        async run(_ctx, { next, forward }) {
+            const response = await next()
+            if (response instanceof Response) {
+                response.headers.set('x-powered-by', 'routekit')
+            }
+            return forward(response)
+        },
+    }),
+)
+```
+
+Built-in middleware is available from `@mpen/routekit/middleware`:
+
+```ts
+import { TerminalLogger } from '@mpen/logger'
+import {
+    acceptCtx,
+    bodyLimit,
+    cors,
+    requestIdCtx,
+    requestLogger,
+    startTimeCtx,
+} from '@mpen/routekit/middleware'
+
+const router = new Router()
+    .setLogger(new TerminalLogger())
+    .useRequest(requestIdCtx({ writeHeaderName: 'x-request-id' }))
+    .useRequest(requestLogger())
+
+router.use([
+    startTimeCtx(),
+    acceptCtx(),
+    bodyLimit({ maxSize: 1024 * 1024 }),
+    cors({ origin: 'https://app.example.com', credentials: true }),
+])
+```
+
+Every request context exposes the inherited `ctx.logger`. Request-boundary middleware runs
+for generated responses as well as matched handlers, so `requestIdCtx()` and
+`requestLogger()` correlate status, timing, and known response body-size output consistently.
+It also records `user_agent.original`. Behind a trusted ingress proxy, opt in to the original
+client-address header:
+
+```ts
+router.useRequest(requestLogger({ trustedClientAddressHeader: 'x-forwarded-for' }))
+```
+
+This records the first forwarded address as `client.address`; only enable it when clients
+cannot send that header directly.
+
+`rateLimit()` supports fixed-window identity, subnet, ASN, country, and endpoint limits.
+It can use the default in-memory storage or a custom `RateLimitStorage` implementation.
+
+## Zod Routes
+
+Zod helpers validate request input, infer typed `params`, and attach JSON Schema metadata
+to routes for OpenAPI and client generation.
+
+```ts
+import { HttpStatus } from '@mpen/http'
+import { Router, ok } from '@mpen/routekit'
+import { createZodRouteBuilder } from '@mpen/routekit/routes'
+import { z } from 'zod'
+
+const router = new Router()
+const route = createZodRouteBuilder()
+
+router.post(
+    '/books/:id',
+    route({
+        name: 'books.byId',
+        schema: {
+            request: {
+                path: z.object({ id: z.coerce.number().int() }),
+                body: z.object({
+                    title: z.string(),
+                    author: z.string(),
+                }),
+            },
+            response: {
+                body: {
+                    [HttpStatus.OK]: z.object({
+                        id: z.number().int(),
+                        title: z.string(),
+                        author: z.string(),
+                    }),
+                },
+            },
+        },
+        handler: ({ params }) =>
+            ok({
+                id: params.path.id,
+                title: params.body.title,
+                author: params.body.author,
+            }),
+    }),
+)
+```
+
+Available Zod APIs:
+
+- `createZodRouteBuilder(defaults)` creates method-helper options or full routes with shared defaults.
+- `zodSchemaMiddleware(options)` defines an explicit request/response schema boundary.
+- `defineZodMiddleware(options)` declares and validates terminal responses originated by middleware.
+
+Request validation failures return a `400` JSON response by default. Override
+`onRequestValidationError` together with `validationResponses` to customize that response.
+Response validation can be controlled with `validateResponse`.
+
+## Valibot Routes
+
+Valibot helpers expose the same shape as the Zod helpers:
+
+```ts
+import { HttpStatus } from '@mpen/http'
+import { ok } from '@mpen/routekit'
+import { createValibotRouteBuilder } from '@mpen/routekit/routes'
+import * as v from 'valibot'
+
+const route = createValibotRouteBuilder()
+
+router.post(
+    '/books/:id',
+    route({
+        name: 'books.byId',
+        schema: {
+            request: {
+                path: v.object({
+                    id: v.pipe(
+                        v.string(),
+                        v.transform((value) => Number(value)),
+                        v.integer(),
+                    ),
+                }),
+                body: v.object({
+                    title: v.string(),
+                    author: v.string(),
+                }),
+            },
+            response: {
+                body: {
+                    [HttpStatus.OK]: v.object({
+                        id: v.number(),
+                        title: v.string(),
+                        author: v.string(),
+                    }),
+                },
+            },
+        },
+        handler: ({ params }) =>
+            ok({
+                id: params.path.id,
+                title: params.body.title,
+                author: params.body.author,
+            }),
+    }),
+)
+```
+
+Available Valibot APIs:
+
+- `createValibotRouteBuilder(defaults)`
+- `valibotSchemaMiddleware(options)`
+- `defineValibotMiddleware(options)`
+
+## OpenAPI
+
+The `openapi()` handler reflects the active router's registered routes and schema metadata.
+
+```ts
+import { openapi } from '@mpen/routekit/handlers'
+
+router.get(
+    '/openapi.json',
+    openapi({
+        info: {
+            title: 'Example API',
+            version: '1.0.0',
+        },
+        servers: [{ url: 'https://api.example.com' }],
+    }),
+)
+```
+
+Route `meta.openapi` is merged into the generated operation, so route-level summaries,
+tags, security, and custom responses can be supplied beside the handler.
+
+## Generated API Clients
+
+`routekit-gen-api-client` loads a router module, reads `router.getRoutes()`, and writes a
+typed client from each route's name, method, path, and JSON Schema metadata.
+
+```bash
+bun run routekit-gen-api-client ./src/server/router.ts -o ./src/client/api-client.gen.ts -p
+```
+
+The router module must export a router instance as `default`, `router`, or another named
+export with a `getRoutes()` method.
+
+Generated clients use `@mpen/routekit/client`:
+
+```ts
+import { FetchTransport } from '@mpen/routekit/client'
+import { ApiClient } from './api-client.gen'
+
+const client = new ApiClient(
+    new FetchTransport({
+        baseUrl: 'https://api.example.com',
+        headers: () => ({ authorization: `Bearer ${token}` }),
+    }),
+)
+
+const response = await client.books.byId.post({
+    path: 123,
+    body: { title: 'Dune', author: 'Frank Herbert' },
+    headers: { 'content-type': 'application/json' },
+})
+
+if (response.ok) {
+    const book = await response.parseBody()
+    console.log(book.title)
+}
+```
+
+Routes with multiple documented response statuses generate a response union narrowed by
+`response.status`:
+
+```ts
+const response = await client.widgets.byId.post(options)
+
+if (response.status === 400) {
+    const body = await response.parseBody()
+    console.log(body.message)
+}
+```
+
+Use `--client-name <Name>` to change the generated class name, `--import-type
+<Type:module>` for external schema-generated types, and `--response-type <Type>` to use a
+custom generic response wrapper.
+
+## Exports
+
+- `@mpen/routekit` exports `Router`, response helpers, and core router types.
+- `@mpen/routekit/routes` exports the Zod and Valibot route helpers.
+- `@mpen/routekit/middleware` exports built-in middleware.
+- `@mpen/routekit/handlers` exports `openapi()`.
+- `@mpen/routekit/client` exports generated-client transports, response wrappers, body codecs, and URL/header helpers.
+
+## Development
+
+From this repository:
+
+```bash
+bun run --cwd packages/routekit build
+bun test packages/routekit
+bun run --cwd packages/routekit gen
+bun run --cwd packages/routekit gen3
+```
+
+The generated example clients live under `packages/routekit/examples`.