rouzer 5.3.0 → 6.0.0

package/docs/middleware.md

@@ -0,0 +1,185 @@
+# Middleware and request context
+
+Rouzer includes request context and middleware composition in its root API, so
+most applications can import route, middleware, and adapter helpers from one
+package.
+
+```ts
+import {
+  chain,
+  filterRuntime,
+  type Middleware,
+  type MiddlewareContext,
+  type RequestContext,
+  type RequestHandler,
+} from 'rouzer'
+```
+
+## Middleware Chain
+
+`chain()` creates a `MiddlewareChain`. Rouzer routers are middleware chains too,
+so you can append middleware before attaching routes.
+
+```ts
+const requestInfo = chain().use(ctx => ({
+  requestId: ctx.request.headers.get('x-request-id') ?? crypto.randomUUID(),
+}))
+
+const router = createRouter()
+  .use(requestInfo)
+  .use(routes, {
+    getProfile(ctx) {
+      return loadProfile(ctx.path.id, ctx.requestId)
+    },
+  })
+```
+
+Middleware runs in order. A middleware can:
+
+- return `void` or `undefined` to continue without adding context
+- return a `Response` to stop the chain and send that response
+- return a request plugin object whose properties are merged into the downstream
+  context
+- call `ctx.passThrough()` to skip the rest of the current chain
+
+## Request Context
+
+Every middleware and Rouzer handler receives a `RequestContext`.
+
+| Property                     | Purpose                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `ctx.request`                | The Web `Request`.                                                            |
+| `ctx.url`                    | Lazily parsed `URL` for `ctx.request.url`.                                    |
+| `ctx.host`                   | Host data such as `ip`, `runtime`, `env`, and `waitUntil`.                    |
+| `ctx.env(name)`              | Typed environment lookup backed by `ctx.host.env` and middleware env plugins. |
+| `ctx.waitUntil(promise)`     | Delegates background work to `ctx.host.waitUntil` when available.             |
+| `ctx.setHeader(name, value)` | Sets a response header from request middleware.                               |
+| `ctx.onResponse(callback)`   | Registers a callback that can mutate or replace the final response.           |
+| `ctx.passThrough()`          | Chain-local control flow for unresolved requests.                             |
+
+Host-provided values live under `ctx.host`.
+
+```ts
+const runtimeName = ctx.host.runtime?.name
+const ip = ctx.host.ip
+```
+
+Runtime-specific request data should stay behind `ctx.host.runtime`.
+
+## Adding Context Properties
+
+Return a plain object to make properties available to downstream middleware and
+handlers.
+
+```ts
+const sessionMiddleware = chain().use(async ctx => {
+  const token = ctx.request.headers.get('authorization')
+  const session = token ? await readSession(token) : null
+
+  if (!session) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  return { session }
+})
+```
+
+Attach the middleware before route handlers that need the property.
+
+```ts
+createRouter()
+  .use(sessionMiddleware)
+  .use(routes, {
+    me(ctx) {
+      return ctx.session.user
+    },
+  })
+```
+
+Treat context property names as owned by the middleware that introduces them.
+Avoid collisions between unrelated middleware.
+
+## Environment Bindings
+
+Return an `env` object to add typed variables behind `ctx.env(...)`.
+
+```ts
+const envMiddleware = chain().use(() => ({
+  env: {
+    DATABASE_URL: process.env.DATABASE_URL,
+  },
+}))
+
+const router = createRouter()
+  .use(envMiddleware)
+  .use(routes, {
+    health(ctx) {
+      return { configured: Boolean(ctx.env('DATABASE_URL')) }
+    },
+  })
+```
+
+The `env` key is reserved for environment bindings. Values are accessed through
+`ctx.env(name)`, not as `ctx.env.DATABASE_URL`.
+
+## Runtime Type Markers
+
+The `runtime` request plugin key is reserved as a type-level marker for
+`ctx.host.runtime`; it does not add `ctx.runtime`.
+
+```ts
+const nodeOnly = chain()
+  .use(filterRuntime<{ name: 'node' }>('node'))
+  .use(ctx => {
+    ctx.host.runtime?.name
+  })
+```
+
+`filterRuntime(name)` checks `ctx.host.runtime?.name`. If the runtime name does
+not match, it calls `ctx.passThrough()`.
+
+## Response Callbacks
+
+Use `ctx.onResponse(callback)` or return `{ onResponse }` when middleware needs
+to finalize a response after a route handler runs.
+
+```ts
+const timing = chain().use(ctx => {
+  const startedAt = Date.now()
+
+  ctx.onResponse(response => {
+    response.headers.set('server-timing', `app;dur=${Date.now() - startedAt}`)
+  })
+})
+```
+
+Use `ctx.setHeader(name, value)` from request middleware for simple headers.
+Inside response callbacks, mutate `response.headers` directly or return a new
+`Response`.
+
+## Isolation
+
+Use `.isolate()` when you want to run a chain for side effects or early
+responses without leaking its plugin properties into the parent chain.
+
+```ts
+const optionalAuth = chain()
+  .use(readOptionalSession)
+  .use(auditSession)
+  .isolate()
+
+const router = createRouter().use(optionalAuth).use(routes, handlers)
+```
+
+An isolated chain can still return a `Response`. Its context additions stay
+inside the isolated chain.
+
+## Pass Through
+
+`ctx.passThrough()` is chain-local control flow. In a nested or isolated chain,
+it skips the rest of that chain and lets the parent chain continue. In a final
+fetch handler, an unresolved request becomes the default `404 Not Found`
+response.
+
+Use `passThrough` for optional middleware branches or runtime filters. Use a
+`Response` when you want to deliberately stop the request.

package/docs/migration-v5-to-v6.md

@@ -0,0 +1,200 @@
+# Migrating from v5 to v6
+
+Rouzer v6 moves the server runtime boundary from Hattip-compatible handlers to
+fetch-compatible Rouzer handlers. Route declarations, handler maps, generated
+clients, response maps, response plugins, raw bodies, and NDJSON routes keep the
+same Rouzer shape.
+
+Most applications only need to update server mounting code, tests, and any
+explicit Hattip handler/context types.
+
+## Replace Hattip adapters with Fetch handlers
+
+Remove Hattip packages that were used only to mount Rouzer handlers.
+
+```sh
+pnpm remove @hattip/core @hattip/adapter-node @hattip/adapter-test
+pnpm add rouzer zod
+```
+
+Use Rouzer's root `toFetchHandler` helper when a server or test harness expects
+a function that receives a Web `Request` and returns a `Response`.
+
+```ts
+import { createRouter, toFetchHandler } from 'rouzer'
+
+const router = createRouter({ basePath: 'api/' }).use(routes, handlers)
+
+export const fetch = toFetchHandler(router)
+```
+
+If your server already accepts a Fetch API handler, mount `fetch` directly. If
+your server exposes host metadata such as client IP, runtime data, environment
+lookups, or background work, pass it through `toFetchHandler`.
+
+```ts
+const fetch = toFetchHandler(router, {
+  host: request => ({
+    ip: request.headers.get('x-forwarded-for') ?? undefined,
+    runtime: { name: 'node' },
+    env: name => process.env[name],
+    waitUntil: promise => {
+      void promise
+    },
+  }),
+})
+```
+
+## Replace Hattip types
+
+Rouzer no longer requires Hattip types in application code.
+
+```ts
+// v5
+import type { AdapterRequestContext, HattipHandler } from '@hattip/core'
+
+// v6
+import type { RequestContext, RequestHandler } from 'rouzer'
+```
+
+Rouzer routers are `RequestHandler` values. Middleware and route handlers receive
+`RequestContext` plus the route-specific fields that Rouzer infers from your
+route tree.
+
+## Update tests
+
+If tests used `@hattip/adapter-test`, replace it with a small local fetch
+wrapper.
+
+```ts
+// v5
+import { createTestClient } from '@hattip/adapter-test'
+
+const client = createClient({
+  baseURL,
+  routes,
+  fetch: createTestClient({
+    handler,
+    baseUrl: baseURL,
+  }),
+})
+```
+
+```ts
+// v6
+import { createClient, toFetchHandler, type RequestHandler } from 'rouzer'
+
+function createLocalFetch(handler: RequestHandler): typeof fetch {
+  const fetchHandler = toFetchHandler(handler)
+  return (input, init) => fetchHandler(new Request(input, init))
+}
+
+const client = createClient({
+  baseURL,
+  routes,
+  fetch: createLocalFetch(handler),
+})
+```
+
+The wrapper matters because generated clients call `fetch(input, init)`, while a
+Rouzer fetch handler receives one `Request`.
+
+## Use `ctx.host` for host data
+
+Host-provided values now live under `ctx.host`.
+
+```ts
+const ip = ctx.host.ip
+const runtimeName = ctx.host.runtime?.name
+```
+
+If old code read adapter-specific fields directly from the context, move those
+values behind the `host` option when creating the fetch handler.
+
+```ts
+const fetch = toFetchHandler(router, {
+  host: request => ({
+    ip: request.headers.get('x-forwarded-for') ?? undefined,
+    runtime: { name: 'custom' },
+  }),
+})
+```
+
+## Rename runtime filters
+
+If code used the old platform filter helper from Rouzer's root exports, use
+`filterRuntime`.
+
+```ts
+// v5
+import { filterPlatform } from 'rouzer'
+
+const middleware = chain().use(filterPlatform('node'))
+```
+
+```ts
+// v6
+import { filterRuntime } from 'rouzer'
+
+const middleware = chain().use(filterRuntime<{ name: 'node' }>('node'))
+```
+
+`filterRuntime(name)` checks `ctx.host.runtime?.name` and narrows the downstream
+runtime type.
+
+## Update custom contexts
+
+If tests or custom adapters constructed request contexts directly, use
+`createContext` with a Web `Request` and optional `host` data.
+
+```ts
+import { createContext } from 'rouzer'
+
+const context = createContext({
+  request: new Request('https://example.test/api/health'),
+  host: {
+    ip: '127.0.0.1',
+    runtime: { name: 'test' },
+    env: name => process.env[name],
+    waitUntil: promise => {
+      void promise
+    },
+  },
+})
+
+const response = await router(context)
+```
+
+## Update pass-through assumptions
+
+`ctx.passThrough()` is middleware-chain control flow. It skips the rest of the
+current chain and lets the parent chain continue. In a final fetch handler, an
+unresolved request becomes Rouzer's default `404 Not Found` response.
+
+Use `ctx.passThrough()` for optional middleware branches and runtime filters.
+Return a `Response` when you want to stop the request deliberately.
+
+## What stays the same
+
+These Rouzer APIs keep the same shape:
+
+- `rouzer/http` resources and actions
+- `createRouter().use(routes, handlers)` route registration
+- middleware added with `.use(middleware)`
+- generated clients from `createClient({ baseURL, routes })`
+- flat client action input objects
+- `$type<T>()`, `$error<T>()`, and response maps
+- response plugins such as `ndjson.routerPlugin` and `ndjson.clientPlugin`
+- `http.rawBody()` request bodies
+
+## Checklist
+
+1. Remove Hattip packages that were only used for Rouzer serving or tests.
+2. Mount routers with `toFetchHandler(router)`.
+3. Replace Hattip handler/context types with Rouzer `RequestHandler` and
+   `RequestContext`.
+4. Replace test adapters with a local fetch wrapper.
+5. Move host metadata into the `host` option and read it from `ctx.host`.
+6. Replace platform filters with `filterRuntime`.
+7. Keep route trees, handler maps, clients, responses, and plugins unchanged
+   unless your application code was also changing them.

package/docs/patterns.md

@@ -0,0 +1,139 @@
+# Patterns, constraints, and migrations
+
+Use this page as a checklist when designing route modules, middleware, and
+client usage. For the current server-boundary upgrade, use
+[Migration from v5 to v6](migration-v5-to-v6.md).
+
+## Preferred Patterns
+
+- Export route trees from small shared modules and import them from server and
+  client code.
+- Keep route declarations close to domain boundaries, not scattered through
+  handler implementations.
+- Use `http.resource(...)` for resource namespaces and shared path params.
+- Name actions after domain operations such as `get`, `list`, `update`,
+  `archive`, and `stream`.
+- Let `http.get`, `http.post`, `http.put`, `http.patch`, and `http.delete` own
+  the transport method.
+- Add Zod schemas when runtime guarantees matter; rely on inferred path params
+  only when string params are enough.
+- Use `$type<T>()` for typed JSON success responses.
+- Use response maps with `$error<T>()` for declared application errors that
+  callers should handle as data.
+- Use `Response` returns for redirects, binary payloads, custom non-JSON error
+  bodies, or unusual headers.
+- Use `ndjson.$type<T>()` only for response streams where each line is a JSON
+  value.
+- Put shared auth, tracing, request IDs, environment bindings, and host-runtime
+  checks in middleware before route registration.
+
+## Constraints And Gotchas
+
+- `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time type
+  contracts. They do not re-validate handler return values.
+- Client action input is flat across path, query, and JSON body fields. Avoid
+  duplicate field names across those schemas.
+- Per-request `RequestInit` fields belong in the second client action argument.
+  Rouzer reserves `method`.
+- Raw-body actions with path or query input accept `body` in the second
+  argument. Raw-body actions without route input accept the body as the first
+  argument.
+- `GET` actions do not accept request bodies. Mutation actions do not accept
+  query schemas.
+- The action API has no `ALL` fallback route. Declare concrete actions for
+  supported HTTP methods.
+- Pathname route patterns expect an absolute client `baseURL`.
+- Resource and action keys are API names only. URL paths come from the pattern
+  strings passed to resources and actions.
+- Routes that use response plugin markers require matching router and client
+  plugins.
+- Declared `$error<T>()` responses are JSON responses. Use a custom `Response`
+  for non-JSON error payloads.
+- Rouzer CORS support does not set `Access-Control-Allow-Credentials`.
+
+## Middleware Constraints
+
+- Host data is under `ctx.host`, including `ctx.host.ip` and
+  `ctx.host.runtime`.
+- The `env`, `runtime`, and `onResponse` request plugin keys are reserved.
+- `runtime` is a type-level marker for `ctx.host.runtime`; it does not create
+  `ctx.runtime`.
+- Use `ctx.setHeader` from request middleware and `response.headers.set(...)`
+  inside response callbacks.
+- `ctx.passThrough()` skips the rest of the current chain. It is not an adapter
+  pass-through mechanism.
+- Use `.isolate()` when a chain should run without leaking context properties to
+  the parent chain.
+
+## Project Shape
+
+A common layout:
+
+```text
+src/
+  routes/
+    profiles.ts
+  server/
+    middleware.ts
+    router.ts
+  client/
+    api.ts
+```
+
+`routes/profiles.ts` exports route contracts. `server/router.ts` imports those
+contracts and attaches handlers. `client/api.ts` imports the same contracts and
+creates the typed client.
+
+Keep route modules free of server-only dependencies when browser clients import
+them.
+
+## v2 To v3 Route Shape
+
+Older Rouzer code used method-map routes. Current Rouzer uses action/resource
+route trees.
+
+```ts
+// Old shape
+export const profileRoute = route('profiles/:id', {
+  GET: { response: $type<Profile>() },
+  PATCH: { body: updateProfileSchema, response: $type<Profile>() },
+})
+```
+
+Use named actions instead:
+
+```ts
+export const profiles = http.resource('profiles/:id', {
+  get: http.get({ response: $type<Profile>() }),
+  update: http.patch({
+    body: updateProfileSchema,
+    response: $type<Profile>(),
+  }),
+})
+
+export const routes = { profiles }
+```
+
+Handler maps and clients mirror those action names.
+
+```ts
+createRouter().use(routes, {
+  profiles: {
+    get(ctx) {
+      return loadProfile(ctx.path.id)
+    },
+    update(ctx) {
+      return updateProfile(ctx.path.id, ctx.body)
+    },
+  },
+})
+
+await client.profiles.get({ id: '42' })
+await client.profiles.update({ id: '42', name: 'Ada' })
+```
+
+## Runtime Context Notes
+
+Use `ctx.host.runtime` for host runtime metadata and `filterRuntime(...)` for
+runtime-specific branches. Keep runtime checks at the middleware boundary so
+route handlers stay focused on request validation and application behavior.

package/docs/responses.md

@@ -0,0 +1,183 @@
+# Responses, errors, and plugins
+
+Rouzer response schemas shape handler return types and generated client result
+types. They do not automatically validate handler return values at runtime.
+
+## Plain JSON Success
+
+Use `$type<T>()` for JSON responses that should be typed on the server and
+client.
+
+```ts
+export const getProfile = http.get('profiles/:id', {
+  response: $type<Profile>(),
+})
+
+createRouter().use(
+  { getProfile },
+  {
+    getProfile(ctx) {
+      return { id: ctx.path.id, name: 'Ada' }
+    },
+  }
+)
+
+const profile = await client.getProfile({ id: '42' })
+```
+
+Handlers may return a plain JSON-serializable value or a custom `Response`.
+Plain values are sent with `Response.json(value)`.
+
+## Raw Response
+
+If an action has no `response` marker, generated client action functions resolve
+to the raw `Response`.
+
+```ts
+export const download = http.get('exports/:id', {})
+
+const response = await client.download({ id: 'exp_123' })
+const blob = await response.blob()
+```
+
+Return a `Response` from handlers for redirects, custom headers, binary bodies,
+non-JSON content, or custom status handling.
+
+## Declared Error Responses
+
+Use `$error<T>()` inside a response map when an error status is part of the route
+contract and callers should handle it as typed data instead of an exception.
+
+```ts
+type User = { id: string; name: string }
+type NotFound = { code: 'NOT_FOUND'; message: string }
+
+export const getUser = http.get('users/:id', {
+  response: {
+    200: $type<User>(),
+    404: $error<NotFound>(),
+  },
+})
+```
+
+Response-map handlers can return a default success value directly or use helper
+methods.
+
+```ts
+createRouter().use(
+  { getUser },
+  {
+    getUser(ctx) {
+      const user = users.get(ctx.path.id)
+      if (!user) {
+        return ctx.error(404, {
+          code: 'NOT_FOUND',
+          message: 'User not found',
+        })
+      }
+      return user
+    },
+  }
+)
+```
+
+Generated clients resolve declared statuses as tuples:
+
+- success: `[null, value, status]`
+- error: `[error, null, status]`
+
+```ts
+const [error, user, status] = await client.getUser({ id: 'missing' })
+
+if (status === 404) {
+  console.log(error.message)
+} else {
+  console.log(user.name)
+}
+```
+
+Declared error statuses do not reject the client promise. Undeclared statuses
+still go through `onJsonError` or throw the default error.
+
+## Multiple Success Statuses
+
+When a response map declares multiple success statuses, return a plain value for
+the default success status or use `ctx.success(status, body)` to choose a
+specific declared success status.
+
+```ts
+export const createUser = http.post('users', {
+  body: createUserSchema,
+  response: {
+    200: $type<User>(),
+    201: $type<User>(),
+    409: $error<Conflict>(),
+  },
+})
+
+createRouter().use(
+  { createUser },
+  {
+    createUser(ctx) {
+      if (alreadyExists(ctx.body.email)) {
+        return ctx.error(409, {
+          code: 'CONFLICT',
+          message: 'Email already exists',
+        })
+      }
+
+      return ctx.success(201, create(ctx.body))
+    },
+  }
+)
+```
+
+The helpers only accept statuses and bodies declared in the map.
+
+## Response Plugins
+
+Response plugins add non-JSON response codecs without changing route matching or
+request validation. A plugin has:
+
+- a compile-time response marker
+- a router plugin that encodes handler results into `Response` objects
+- a client plugin that decodes successful `Response` objects into client results
+
+NDJSON is the built-in example:
+
+```ts
+export const events = http.get('events', {
+  response: ndjson.$type<Event>(),
+})
+
+createRouter({
+  plugins: [ndjson.routerPlugin],
+})
+
+createClient({
+  baseURL,
+  routes,
+  plugins: [ndjson.clientPlugin],
+})
+```
+
+Rouzer validates plugin registration when routes are attached to a router or
+client. Routes that use an unregistered response marker fail fast instead of
+falling back to JSON.
+
+Plugin markers can be used directly as an action response or as success entries
+in a response map. `$error<T>()` entries are JSON error responses.
+
+## Runtime Validation Boundary
+
+`$type<T>()`, `$error<T>()`, and plugin markers are TypeScript contracts. Rouzer
+does not re-check handler return values against those types at the server
+boundary.
+
+Validate untrusted data where it enters your system, such as:
+
+- external API clients
+- database decoders
+- queue/event consumers
+- form-data or file-processing layers
+- UI/client boundaries that consume untrusted responses