rouzer 5.3.0 → 6.0.0

package/docs/client.md

@@ -0,0 +1,203 @@
+# Typed client
+
+`createClient({ baseURL, routes })` creates a typed fetch client from the same
+route tree used by the server.
+
+```ts
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+})
+
+const profile = await client.profiles.get({
+  id: '42',
+  includePosts: true,
+})
+```
+
+The returned client mirrors resources and actions from the route tree. Each
+action function validates input before calling `fetch`.
+
+## Configuration
+
+```ts
+const client = createClient({
+  baseURL: new URL('/api/', window.location.origin).href,
+  routes,
+  headers: {
+    'content-type': 'application/json',
+  },
+  fetch: globalThis.fetch,
+  plugins: [ndjson.clientPlugin],
+  onJsonError(response) {
+    return response.json()
+  },
+  clientHook(event) {
+    console.log(event.type, event.routeName)
+  },
+})
+```
+
+| Option        | Purpose                                                                               |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `baseURL`     | Absolute base URL used to build request URLs. A trailing slash is added when missing. |
+| `routes`      | Shared HTTP route tree. Required.                                                     |
+| `headers`     | Default headers merged into every request.                                            |
+| `fetch`       | Custom fetch implementation for tests or non-browser runtimes.                        |
+| `plugins`     | Client response plugins such as `ndjson.clientPlugin`.                                |
+| `onJsonError` | Custom handler for non-2xx responses not declared in a response map.                  |
+| `clientHook`  | Best-effort lifecycle observer for generated action calls.                            |
+
+The returned client exposes the original options as `client.clientConfig`, so a
+route action named `config` remains available as `client.config(...)`.
+
+## Action Arguments
+
+Generated action functions use a flat first argument for path, query, and JSON
+body fields.
+
+```ts
+export const updateProfile = http.patch('profiles/:id', {
+  body: z.object({
+    name: z.string(),
+  }),
+  response: $type<Profile>(),
+})
+
+await client.updateProfile({
+  id: '42',
+  name: 'Ada',
+})
+```
+
+Per-request `RequestInit` options are the second argument. Rouzer reserves
+`method` and owns JSON body encoding. Headers are typed from the route header
+schema when one exists.
+
+```ts
+await client.profiles.get(
+  { id: '42', includePosts: false },
+  {
+    signal: abortController.signal,
+    headers: { 'x-request-id': 'docs' },
+  }
+)
+```
+
+Avoid duplicate keys across path, query, and JSON body schemas. The flat client
+input cannot distinguish duplicate field names from different request
+locations.
+
+## Raw Body Routes
+
+For raw-body routes with path or query input, pass the `BodyInit` as
+`options.body`.
+
+```ts
+await client.uploadAvatar(
+  { id: '42' },
+  { body: file, headers: { 'content-type': file.type } }
+)
+```
+
+For raw-body routes without route input, pass the body as the first argument.
+
+```ts
+await client.upload(file, {
+  headers: { 'content-type': file.type },
+})
+```
+
+Rouzer does not JSON encode or validate raw bodies.
+
+## Response Results
+
+Generated action return types depend on the action response schema:
+
+| Route response            | Client result                                                    |
+| ------------------------- | ---------------------------------------------------------------- |
+| No `response` marker      | Raw `Response`.                                                  |
+| `response: $type<T>()`    | Parsed JSON typed as `T`.                                        |
+| Status-keyed response map | Tuple union: `[null, value, status]` or `[error, null, status]`. |
+| Response plugin marker    | Plugin-decoded value, such as `AsyncIterable<T>` for NDJSON.     |
+
+Non-2xx responses reject unless the status is declared in a response map or
+`onJsonError` returns a value.
+
+## Error Handling
+
+By default, undeclared non-2xx responses throw an `Error` with the HTTP status
+in the message. If the response has a JSON content type, Rouzer copies parsed
+JSON properties onto the thrown error.
+
+Use `onJsonError` to override that behavior:
+
+```ts
+const client = createClient({
+  baseURL,
+  routes,
+  async onJsonError(response) {
+    return {
+      status: response.status,
+      body: await response.json(),
+    }
+  },
+})
+```
+
+Rouzer returns the `onJsonError` result as-is. It does not automatically parse a
+`Response` returned by `onJsonError`.
+
+## Lifecycle Hooks
+
+Use `clientHook` for observability without wrapping every generated action.
+
+```ts
+const client = createClient({
+  baseURL,
+  routes,
+  clientHook(event) {
+    if (event.type === 'request.success') {
+      console.log(event.routeName, event.durationMs)
+    }
+  },
+})
+```
+
+Rouzer emits:
+
+- `request.start` before client-side validation
+- `request.success` when the generated action resolves
+- `request.error` when the generated action rejects
+
+Each event includes an opaque `opId`, `routeName`, HTTP `method`,
+`pathPattern`, and original `payload`. Terminal events include `durationMs` and
+either `response` or `error`. If an HTTP response was received, terminal events
+also include `status`.
+
+Hook errors are swallowed. Lifecycle hooks are observability-only and must not
+change request behavior.
+
+For streaming response plugins, `request.success` is emitted when the generated
+action resolves to the stream object. Errors that happen while consuming the
+stream are outside the first lifecycle hook surface.
+
+## Testing With Local Fetch
+
+Rouzer handlers accept a request context, while `fetch` accepts `(input, init)`.
+Use `toFetchHandler` plus a small wrapper in tests.
+
+```ts
+import { 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: 'https://example.test/api/',
+  routes,
+  fetch: createLocalFetch(router),
+})
+```

package/docs/concepts.md

@@ -0,0 +1,113 @@
+# Framework concepts
+
+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 it is reused by the router and generated client.
+
+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.
+
+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/handlers.md

@@ -0,0 +1,202 @@
+# Routers and handlers
+
+`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
+
+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`.
+
+Rouzer does not automatically set `Access-Control-Allow-Credentials`. Set that
+header yourself when credentialed cross-origin requests need it.
+
+## 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,78 @@
+# Rouzer documentation
+
+Rouzer combines a shared TypeScript route tree, a fetch-compatible server
+router, a typed fetch client, and request context composition. These guides are
+organized by concern so the docs directory is the complete entry point for what
+you can do and how the pieces fit together.
+
+## 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 [Migration from v5 to v6](migration-v5-to-v6.md) when upgrading
+   from the Hattip-compatible server boundary.
+9. Read [Patterns, constraints, and migrations](patterns.md) for conventions,
+   gotchas, and upgrade notes.
+
+## 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
+
+1. A shared route module exports resources and actions.
+2. Server code creates a router, appends middleware, and attaches the route tree
+   with a handler map.
+3. Runtime code mounts the router with `toFetchHandler` or an adapter-specific
+   helper.
+4. Client code creates a generated client from the same route tree.
+5. A client action validates route input, builds a `fetch` request, and sends
+   it.
+6. The router matches the request, validates path/query/body/header data, and
+   calls the typed handler.
+7. The handler returns JSON data, a custom `Response`, a declared response-map
+   helper, or a response-plugin value such as an NDJSON source.
+8. Response callbacks registered by middleware can finalize headers or replace
+   the response before it leaves the chain.
+
+## 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`