rouzer 5.3.1 → 6.0.1

package/docs/concepts.md

@@ -0,0 +1,118 @@
+# Framework concepts
+
+> Use the route tree as the shared contract, then decide which behavior belongs
+> in routes, handlers, clients, or middleware.
+
+Rouzer is for applications that can share a TypeScript HTTP contract between
+server and client code. The central object is an HTTP route tree. That tree
+describes URL paths, action names, request schemas, and response contracts once,
+then the router and generated client reuse it.
+
+Rouzer is not an OpenAPI generator, a response validator, or a full application
+framework. It focuses on shared route contracts, request validation, typed
+handlers, typed clients, response helpers, middleware, and request context.
+
+## The Main Objects
+
+Route tree:
+
+- a plain object whose leaves are HTTP actions and whose branches are resources
+- exported from a shared module that server and client code can both import
+- passed to `createRouter().use(routes, handlers)` and
+  `createClient({ routes, baseURL })`
+
+Action:
+
+- a concrete HTTP operation declared with `http.get`, `http.post`, `http.put`,
+  `http.patch`, or `http.delete`
+- owns an optional action-local path, request schemas, and an optional response
+  marker or response map
+- becomes one handler function on the server and one generated client function
+
+Resource:
+
+- a path-scoped namespace declared with `http.resource(path, children)`
+- contributes path params to child actions
+- creates nested handler and client objects
+
+Router:
+
+- a fetch-compatible request handler returned by `createRouter(...)`
+- accepts middleware with `.use(middleware)`
+- accepts route trees with `.use(routes, handlers)`
+- validates matched requests before handlers run
+
+Client:
+
+- a typed fetch wrapper returned by `createClient({ baseURL, routes })`
+- mirrors the route tree shape
+- validates client input before sending requests
+- parses responses according to the route response contract
+
+Middleware:
+
+- functions that receive a shared `RequestContext`
+- can add typed properties, environment bindings, response callbacks, or runtime
+  type markers
+- run before route handlers when attached before `.use(routes, handlers)`
+
+## What Validation Covers
+
+Rouzer validates request inputs:
+
+- path params from route patterns or a `path` Zod object
+- URL query values on `GET` actions with a `query` schema
+- JSON request bodies on mutation actions with a Zod `body` schema
+- request headers with a `headers` schema
+
+Path, query, and header values arrive as strings. Rouzer adds string parsing for
+Zod number and boolean schemas in those locations, including nested object and
+array schemas. JSON request bodies are parsed from the request body and then
+validated as JSON values.
+
+> [!IMPORTANT]
+> Rouzer does not validate handler return values just because a route uses
+> `$type<T>()`, `$error<T>()`, or `ndjson.$type<T>()`. Those markers are
+> TypeScript contracts. Validate untrusted response data where it enters your
+> system.
+
+## Lifecycle
+
+```ts
+// shared/routes.ts
+export const routes = {
+  profiles: http.resource('profiles/:id', {
+    get: http.get({ response: $type<Profile>() }),
+  }),
+}
+
+// server.ts
+export const router = createRouter()
+  .use(requestMiddleware)
+  .use(routes, handlers)
+
+// client.ts
+export const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+})
+```
+
+The same action key becomes:
+
+- `handlers.profiles.get(ctx)` on the server
+- `client.profiles.get(input, options)` on the client
+- a route name such as `profiles.get` in client lifecycle hook events
+
+## Rouzer Middleware
+
+Rouzer's router is both callable as a request handler and chainable with
+middleware helpers.
+
+Use route contracts for HTTP handler/client behavior. Use middleware when you
+need request-scoped state, authentication, environment bindings, host runtime
+data, response callbacks, background work, or custom adapter contexts.
+
+The common middleware API is exported from `rouzer`, including `chain`,
+`toFetchHandler`, `createContext`, `filterRuntime`, `RequestContext`, and
+`RequestHandler`.

package/docs/config.json

@@ -0,0 +1,18 @@
+{
+  "projectName": "Rouzer",
+  "navigation": {
+    "order": [
+      "index.md",
+      "concepts.md",
+      "routes.md",
+      "middleware.md",
+      "handlers.md",
+      "client.md",
+      "responses.md",
+      "streaming.md",
+      "runtime.md",
+      "patterns.md",
+      "migration-v5-to-v6.md"
+    ]
+  }
+}

package/docs/handlers.md

@@ -0,0 +1,207 @@
+# Routers and handlers
+
+> Attach a shared route tree to its handler map, then order middleware so every
+> handler receives the validated request context it expects.
+
+`createRouter()` returns a fetch-compatible Rouzer handler with chain methods.
+Use it to compose middleware and attach route trees.
+
+```ts
+import { createRouter } from 'rouzer'
+
+export const router = createRouter({ basePath: 'api/' })
+  .use(requestMiddleware)
+  .use(routes, handlers)
+```
+
+The router is also a `RequestHandler`, so it can be mounted with
+`toFetchHandler(router)` or runtime-specific adapter helpers.
+
+## Handler Maps
+
+The handler object mirrors the route tree. Resource nodes become nested objects.
+Action nodes become handler functions.
+
+```ts
+export const routes = {
+  profiles: http.resource('profiles/:id', {
+    get: http.get({ response: $type<Profile>() }),
+    update: http.patch({
+      body: updateProfileSchema,
+      response: $type<Profile>(),
+    }),
+    posts: http.resource('posts', {
+      list: http.get({ response: $type<Post[]>() }),
+    }),
+  }),
+}
+
+createRouter().use(routes, {
+  profiles: {
+    get(ctx) {
+      return loadProfile(ctx.path.id)
+    },
+    update(ctx) {
+      return updateProfile(ctx.path.id, ctx.body)
+    },
+    posts: {
+      list(ctx) {
+        return listPosts(ctx.path.id)
+      },
+    },
+  },
+})
+```
+
+## Handler Context
+
+Handlers receive the Rouzer request context plus values inferred from the
+matched route.
+
+`GET` handlers receive:
+
+- `ctx.path`
+- `ctx.query`
+- `ctx.headers`
+
+Mutation handlers receive:
+
+- `ctx.path`
+- `ctx.body`
+- `ctx.headers`
+
+All handlers also receive middleware-provided properties and base context fields
+such as `ctx.request`, `ctx.url`, `ctx.host`, `ctx.env(...)`,
+`ctx.waitUntil(...)`, `ctx.setHeader(...)`, and `ctx.onResponse(...)`.
+
+```ts
+const requestInfo = chain().use(ctx => ({
+  requestId: ctx.request.headers.get('x-request-id') ?? 'local',
+}))
+
+createRouter()
+  .use(requestInfo)
+  .use(routes, {
+    getProfile(ctx) {
+      return {
+        id: ctx.path.id,
+        requestId: ctx.requestId,
+      }
+    },
+  })
+```
+
+## Validation Order
+
+For a matched route, Rouzer validates before the handler runs:
+
+1. path params, if a `path` schema is declared
+2. headers, if a `headers` schema is declared
+3. query string, for `GET` actions with a `query` schema
+4. JSON body, for mutation actions with a non-raw `body` schema
+
+> [!NOTE]
+> If validation fails, Rouzer returns a `400` JSON response and does not call
+> the handler. In `debug` mode, validation responses include more specific Zod
+> error messages.
+
+If no `path` schema is declared, `ctx.path` is inferred from the route pattern
+and contains string params.
+
+## Return Values
+
+Handlers can return:
+
+- a plain value, which Rouzer sends with `Response.json(value)`
+- a Web `Response`, which Rouzer passes through unchanged
+- `ctx.error(status, body)` for a declared error response-map entry
+- `ctx.success(status, body)` for a declared non-default success response-map
+  entry
+- a response-plugin value, such as an NDJSON iterable, when the route response
+  marker and router plugin match
+
+Return a `Response` when you need custom status codes, headers, redirects,
+non-JSON payloads, or hand-written error bodies.
+
+## Response Maps In Handlers
+
+Routes with a status-keyed response map add `ctx.error` and `ctx.success`
+helpers.
+
+```ts
+export const getUser = http.get('users/:id', {
+  response: {
+    200: $type<User>(),
+    201: $type<User>(),
+    404: $error<NotFound>(),
+  },
+})
+
+createRouter().use(
+  { getUser },
+  {
+    getUser(ctx) {
+      if (ctx.path.id === 'created') {
+        return ctx.success(201, { id: 'created', name: 'Grace' })
+      }
+
+      const user = users.get(ctx.path.id)
+      if (!user) {
+        return ctx.error(404, {
+          code: 'NOT_FOUND',
+          message: 'User not found',
+        })
+      }
+
+      return user
+    },
+  }
+)
+```
+
+The helpers only accept statuses and body types declared in the response map.
+
+## Router Configuration
+
+`createRouter(config)` accepts:
+
+| Option              | Purpose                                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `basePath`          | Prepends a normalized path prefix to all route patterns.                                                       |
+| `debug`             | Adds matched-route debug headers, logs missing route handlers, and includes more specific validation messages. |
+| `plugins`           | Router response plugins such as `ndjson.routerPlugin`.                                                         |
+| `cors.allowOrigins` | Restricts requests with an `Origin` header.                                                                    |
+
+```ts
+createRouter({
+  basePath: 'api/',
+  debug: process.env.NODE_ENV === 'development',
+  cors: {
+    allowOrigins: ['example.net', 'https://*.example.com'],
+  },
+})
+```
+
+When an allowed request includes an `Origin` header, Rouzer sets
+`Access-Control-Allow-Origin` to that origin. For preflight requests, Rouzer
+returns `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, and
+`Access-Control-Allow-Headers`.
+
+> [!WARNING]
+> Rouzer does not set `Access-Control-Allow-Credentials`. Set that header
+> yourself before relying on credentialed cross-origin requests.
+
+## Middleware Ordering
+
+Attach middleware before route handlers that depend on it.
+
+```ts
+createRouter().use(authMiddleware).use(routes, secureHandlers)
+```
+
+Middleware attached after a route tree only runs if an earlier route handler
+does not produce a response. Most applications put shared middleware before
+route registration.
+
+Use a middleware `Response` return for cross-cutting rejection, such as auth or
+rate limits. Use route handlers for route-specific application results.

package/docs/index.md

@@ -0,0 +1,103 @@
+# Rouzer documentation
+
+> Choose the guide that matches your next Rouzer decision, from defining a
+> shared route contract to mounting the completed router in a Fetch runtime.
+
+Rouzer combines a shared TypeScript route tree, a fetch-compatible server
+router, a typed fetch client, and request context composition. The guides keep
+those concerns separate while showing where they meet.
+
+## Learning Path
+
+1. Read [Framework concepts](concepts.md) for the lifecycle and boundaries.
+2. Read [Route contracts](routes.md) to declare resources, actions, schemas, and
+   metadata.
+3. Read [Middleware and request context](middleware.md) before writing shared
+   context, auth, environment, tracing, or runtime-specific middleware.
+4. Read [Routers and handlers](handlers.md) to attach route trees and implement
+   handlers.
+5. Read [Typed client](client.md) to call the same route tree from application
+   code.
+6. Read [Responses, errors, and plugins](responses.md) and
+   [NDJSON streaming](streaming.md) when routes need more than a simple JSON
+   success body.
+7. Read [Runtime and adapters](runtime.md) when mounting Rouzer in a server or
+   test harness.
+8. Read [Patterns, constraints, and migrations](patterns.md) before settling on
+   a project structure or reviewing an integration.
+
+> [!IMPORTANT]
+> Upgrading an existing v5 application is a different path. Start with
+> [Migration from v5 to v6](migration-v5-to-v6.md), then return to the focused
+> guides when a changed boundary needs more detail.
+
+## Guide Map
+
+| Guide                                                | Concern                                                                                                                                             |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Framework concepts](concepts.md)                    | The high-level model, request lifecycle, and Rouzer's framework responsibilities.                                                                   |
+| [Route contracts](routes.md)                         | `rouzer/http` resources, actions, Zod schemas, raw bodies, path patterns, and metadata.                                                             |
+| [Middleware and request context](middleware.md)      | `chain`, request plugins, `RequestContext`, `context.host`, env access, `waitUntil`, `onResponse`, `passThrough`, isolation, and runtime filtering. |
+| [Routers and handlers](handlers.md)                  | `createRouter`, route handler maps, validated handler context, CORS, debug mode, middleware ordering, and handler return values.                    |
+| [Typed client](client.md)                            | `createClient`, generated action functions, flat input objects, headers, custom fetch, `onJsonError`, and lifecycle hooks.                          |
+| [Responses, errors, and plugins](responses.md)       | `$type`, `$error`, response maps, status tuples, custom `Response` returns, and response plugin contracts.                                          |
+| [NDJSON streaming](streaming.md)                     | Streaming response markers, router/client plugin registration, cancellation, and stream error modeling.                                             |
+| [Runtime and adapters](runtime.md)                   | Root `toFetchHandler`, fetch-compatible mounting, custom host data, tests, CORS, and background work.                                               |
+| [Patterns, constraints, and migrations](patterns.md) | Preferred project structure, common constraints, and migration notes from older Rouzer shapes.                                                      |
+| [Migration from v5 to v6](migration-v5-to-v6.md)     | Hattip-compatible to fetch-compatible server mounting, type, test, host data, and runtime-filter updates.                                           |
+
+## Request Lifecycle
+
+The route tree is the shared contract. The client uses it to construct the
+request, and the router uses it to validate and dispatch that request.
+
+```mermaid
+flowchart TD
+  routes["Shared route tree"]
+  client["Generated client"]
+  router["Router and handler map"]
+  request["Validated fetch request"]
+  middleware["Middleware chain"]
+  handler["Typed route handler"]
+  response["JSON, Response, response map, or plugin value"]
+  finalize["Response callbacks"]
+
+  routes --> client
+  routes --> router
+  client -->|"validate input and fetch"| request
+  request --> middleware
+  middleware --> router
+  router -->|"match and validate"| handler
+  handler --> response
+  response --> finalize
+```
+
+After response callbacks finish, the Fetch-compatible handler returns the final
+Web `Response` to the runtime.
+
+## Runnable Examples
+
+| Example                                                                                               | Shows                                                         |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| [Shared route, router, and client](https://github.com/alloc/rouzer/blob/main/examples/basic-usage.ts) | A complete JSON route from declaration through a client call. |
+| [Declared status responses](https://github.com/alloc/rouzer/blob/main/examples/error-responses.ts)    | Typed success and error tuples from a response map.           |
+| [NDJSON response stream](https://github.com/alloc/rouzer/blob/main/examples/ndjson-stream.ts)         | Plugin registration, streaming, and incremental consumption.  |
+
+## Framework Surface
+
+Rouzer owns:
+
+- route tree declarations and handler/client type inference
+- request validation from route schemas
+- route matching and handler dispatch
+- response markers, response maps, and response plugin integration
+- generated client action functions
+
+Rouzer middleware and runtime helpers cover:
+
+- middleware chaining and short-circuit behavior
+- request context creation and extension
+- host data such as `context.host.ip` and `context.host.runtime`
+- typed environment access through `context.env(...)`
+- `waitUntil`, `setHeader`, `onResponse`, `passThrough`, and chain isolation
+- adapter helpers such as `toFetchHandler`

package/docs/middleware.md

@@ -0,0 +1,191 @@
+# Middleware and request context
+
+> Put cross-cutting request behavior in an ordered chain and expose only the
+> typed context values that downstream middleware and handlers need.
+
+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')) }
+    },
+  })
+```
+
+> [!IMPORTANT]
+> The `env` key is reserved for environment bindings. Read its values through
+> `ctx.env(name)`, not as `ctx.env.DATABASE_URL`.
+
+## Runtime Type Markers
+
+> [!IMPORTANT]
+> The `runtime` request plugin key is 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
+
+> [!NOTE]
+> `ctx.passThrough()` is chain-local control flow, not an adapter pass-through.
+> 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.