rouzer 5.3.1 → 6.0.0

package/README.md

@@ -1,278 +1,160 @@
 # Rouzer
 
-Rouzer lets you declare an HTTP route tree once and share its TypeScript types
-and Zod validation between a Hattip-compatible server and a typed fetch client.
-The client is always created from that route tree.
+Rouzer is a small TypeScript HTTP framework for projects that can share one
+route tree between server and client code. The route tree defines URL patterns,
+named actions, request validation, and response contracts once, then Rouzer uses
+it to build a fetch-compatible router and a typed fetch client.
 
-## What it does
+Rouzer also includes a chainable middleware layer for request-scoped state,
+host/runtime data, background work, response callbacks, and adapter helpers that
+turn a router into a Fetch API handler.
 
-A Rouzer HTTP route tree defines URL patterns, named actions, method schemas, and
-optional JSON, error, or newline-delimited JSON response types once, then reuses
-that contract to:
+## Use It When
 
-- validate client arguments before `fetch`
-- match and validate server requests before handlers run
-- type handler context from path, query/body, headers, and middleware
-- attach typed client action functions such as `client.profiles.get(...)`
-- send JSON object request bodies or raw `BodyInit` payloads
-- parse typed JSON responses, declared error responses, and NDJSON streams
+Use Rouzer when:
 
-Rouzer optimizes for shared TypeScript route modules over language-agnostic API
-schemas or generated SDKs.
+- your server and client can import the same TypeScript route module
+- you want Zod validation before client requests and before server handlers
+- a fetch-compatible handler fits your runtime or adapter
+- named resource/action calls are a better fit than generated SDK classes
 
-## Is this for you?
+Consider another tool when you need OpenAPI-first schemas, generated clients for
+other languages, server-side response validation for every handler return, or a
+framework that owns rendering, deployment, and data loading.
 
-Use Rouzer if:
-
-- your server and client can import the same TypeScript route tree
-- you want Zod request validation on both sides of an HTTP boundary
-- response data is validated at data/client boundaries, not by re-checking every
-  handler return
-- a Hattip-compatible handler fits your server runtime
-- you prefer named resource/action functions over a generated client class
-
-Consider something else if:
-
-- you need OpenAPI-first workflows, schema files, or generated clients for other
-  languages
-- you want the router to validate every response body at the server boundary;
-  `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are type contracts
-- you want a framework that owns controllers, data loading, rendering, and
-  deployment adapters
-- you cannot use ESM or Zod v4+
-
-## Requirements
-
-- ESM runtime and tooling
-- Zod v4 or newer
-- a Hattip adapter when using `createRouter(...)`
-- a Fetch API implementation when using `createClient(...)`
-- an absolute `baseURL` and shared `routes` tree for generated client URLs
-
-## Installation
+## Install
 
 ```sh
 pnpm add rouzer zod
 ```
 
-Import the primary API from the root package and declare routes through the HTTP
-subpath:
+Rouzer requires ESM, Zod v4 or newer, a Fetch API implementation for clients,
+and a fetch-compatible server or adapter for routers.
 
 ```ts
-import { $error, $type, chain, createClient, createRouter, metadata } from 'rouzer'
+import {
+  $error,
+  $type,
+  chain,
+  createClient,
+  createRouter,
+  metadata,
+  toFetchHandler,
+} from 'rouzer'
 import * as http from 'rouzer/http'
+import * as ndjson from 'rouzer/ndjson'
 ```
 
-`chain` is re-exported from `alien-middleware` for typed server middleware.
-
-## Quick example
+`chain`, `toFetchHandler`, request context types, and related middleware helpers
+are part of the root Rouzer API.
 
-This example shows the core loop: one HTTP action contract defines validation,
-server handler types, and the typed client call.
+## Small Example
 
 ```ts
 import * as z from 'zod'
-import { $type, createClient, createRouter } from 'rouzer'
+import {
+  $type,
+  chain,
+  createClient,
+  createRouter,
+  toFetchHandler,
+} from 'rouzer'
 import * as http from 'rouzer/http'
 
-export const hello = http.get('hello/:name', {
-  query: z.object({
-    excited: z.optional(z.boolean()),
-  }),
-  response: $type<{ message: string }>(),
-})
-
-export const routes = { hello }
-
-export const handler = createRouter({ basePath: 'api/' }).use(routes, {
-  hello(ctx) {
-    return {
-      message: `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`,
-    }
-  },
-})
-
-const client = createClient({
-  baseURL: 'https://example.com/api/',
-  routes,
-})
-
-const { message } = await client.hello({
-  name: 'world',
-  excited: true,
-})
-```
-
-`handler` can be mounted with any Hattip adapter. Generated client action calls
-validate flat route arguments before `fetch`; server handlers validate matched
-path, query, headers, and JSON bodies before your handler runs. Per-request
-headers, abort signals, and other `RequestInit` options are passed as a second
-client action argument. Routes declared with `body: http.rawBody()` pass a
-`BodyInit` payload through to `fetch` without JSON encoding.
-
-### Typed status responses
-
-Use a response map when client code needs declared error statuses as data instead
-of exceptions.
-
-```ts
-import { $error, $type, createClient, createRouter } from 'rouzer'
-import * as http from 'rouzer/http'
-
-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>(),
-  },
-})
-export const routes = { getUser }
-
-createRouter().use(routes, {
-  getUser(ctx) {
-    if (ctx.path.id === 'missing') {
-      return ctx.error(404, {
-        code: 'NOT_FOUND',
-        message: 'User not found',
-      })
-    }
-    return { id: ctx.path.id, name: 'Ada' }
-  },
-})
-
-const client = createClient({
-  baseURL: 'https://example.com/api/',
-  routes,
-})
-
-const [error, user, status] = await client.getUser({ id: '42' })
-```
-
-Success entries resolve as `[null, value, status]`; declared error entries
-resolve as `[error, null, status]`.
-
-### Raw request bodies
-
-Use `http.rawBody()` when an action needs to send a `BodyInit` payload such as a
-`Blob`, `Uint8Array`, `ReadableStream`, `FormData`, or string without JSON
-encoding.
-
-```ts
-export const uploadAvatar = http.post('profiles/:id/avatar', {
-  body: http.rawBody(),
-})
-
-await client.uploadAvatar({ id: '42' }, { body: file })
-```
-
-For raw-body routes without path or query input, the generated client accepts the
-body as the first argument:
-
-```ts
-export const upload = http.post('upload', {
-  body: http.rawBody(),
-})
-
-await client.upload(file, { headers: { 'content-type': file.type } })
-```
-
-Server handlers for raw-body routes read from `ctx.request` directly with Fetch
-APIs such as `arrayBuffer()`, `blob()`, `formData()`, or `text()`.
-
-### Route metadata
-
-Use `metadata(...)` to attach optional runtime metadata to HTTP resources or
-actions. Metadata does not affect routing, validation, client typing, or handler
-behavior; it is preserved on route nodes for generated clients, CLIs, docs, and
-route inspectors.
+type Profile = {
+  id: string
+  name: string
+  requestId: string
+}
 
-```ts
-export const sessions = http.resource('sessions', {
-  ...metadata({
-    description: 'Daemon-managed session control.',
-  }),
-  list: http.post('list', {
-    ...metadata({
-      description: 'Lists daemon-managed sessions and pagination state.',
+export const profiles = http.resource('profiles/:id', {
+  get: http.get({
+    query: z.object({
+      includePosts: z.optional(z.boolean()),
     }),
-    response: $type<SessionList>(),
+    response: $type<Profile>(),
   }),
 })
-```
 
-The constructed nodes expose metadata as `node.metadata`.
+export const routes = { profiles }
 
-### Client lifecycle hooks
+const requestInfo = chain().use(ctx => ({
+  requestId: ctx.request.headers.get('x-request-id') ?? 'local',
+}))
 
-Pass `clientHook` to observe generated client action calls without wrapping the
-client tree:
+const router = createRouter({ basePath: 'api/' })
+  .use(requestInfo)
+  .use(routes, {
+    profiles: {
+      get(ctx) {
+        return {
+          id: ctx.path.id,
+          name: 'Ada',
+          requestId: ctx.requestId,
+        }
+      },
+    },
+  })
+
+const fetchHandler = toFetchHandler(router)
 
-```ts
 const client = createClient({
   baseURL: 'https://example.com/api/',
   routes,
-  clientHook(event) {
-    if (event.type === 'request.success') {
-      console.log(event.routeName, event.durationMs)
-    }
-  },
 })
-```
 
-Rouzer emits `request.start` before client-side validation, then
-`request.success` when the action resolves or `request.error` when it rejects.
-Terminal events include the parsed response or thrown error plus `durationMs`.
-Hook errors are swallowed.
+const profile = await client.profiles.get(
+  { id: '42', includePosts: false },
+  { headers: { 'x-request-id': 'docs' } }
+)
+```
 
-### NDJSON response streams
+The shared `routes` object drives the handler map and the generated client. The
+middleware output becomes part of the handler context, while the route schema
+adds typed `ctx.path`, `ctx.query`, `ctx.body`, and `ctx.headers` values.
 
-Use `response: ndjson.$type<T>()` for endpoints that stream
-newline-delimited JSON. Add `ndjson.routerPlugin` to the router and
-`ndjson.clientPlugin` to the client. Handlers return an `Iterable<T>` or
-`AsyncIterable<T>`; Rouzer wraps it in an `application/x-ndjson` response.
-Client action functions resolve to an `AsyncIterable<T>`.
+## Core Concepts
 
-```ts
-import { createClient, createRouter } from 'rouzer'
-import * as http from 'rouzer/http'
-import * as ndjson from 'rouzer/ndjson'
+Route contracts live in shared TypeScript modules. Use `rouzer/http` resources
+for path-scoped namespaces and actions such as `http.get`, `http.post`, and
+`http.patch` for concrete HTTP operations.
 
-export const events = http.get('events', {
-  response: ndjson.$type<{ id: number; message: string }>(),
-})
-export const routes = { events }
+Routers are chainable request handlers. `createRouter()` returns a handler;
+`.use(middleware)` appends middleware and `.use(routes, handlers)` attaches a
+route tree.
 
-createRouter({ plugins: [ndjson.routerPlugin] }).use(routes, {
-  async *events() {
-    yield { id: 1, message: 'ready' }
-  },
-})
+Handlers mirror the route tree. Rouzer validates the matched request before the
+handler runs, then lets the handler return JSON data, a custom `Response`,
+declared status helpers, or a response-plugin value such as an NDJSON stream.
 
-const client = createClient({
-  baseURL: 'https://example.com/api/',
-  routes,
-  plugins: [ndjson.clientPlugin],
-})
-for await (const event of await client.events()) {
-  console.log(event.message)
-}
-```
+Clients mirror the same route tree. `createClient({ baseURL, routes })` returns
+typed action functions with flat route input objects and optional per-request
+`RequestInit` options.
 
-If a client aborts the request signal or stops iteration early by breaking from
-`for await` or calling the iterator's `return()`, Rouzer cancels the response
-body and calls the server source iterator's `return()`. Sources that wait for
-future events should make those waits abort-aware when they need cleanup to run
-while an awaited operation is still pending.
+Response markers are type contracts. `$type<T>()`, `$error<T>()`, and
+`ndjson.$type<T>()` shape handler and client types, but they do not re-validate
+handler return values at the server boundary.
 
 ## Documentation
 
-- [Concepts, API selection, v5 client input notes, and migration notes](docs/context.md)
-- [Runnable shared-route example](examples/basic-usage.ts)
-- [Runnable typed error response example](examples/error-responses.ts)
-- [Runnable NDJSON response-stream example](examples/ndjson-stream.ts)
-- Generated declarations in the published package provide the exact signatures
-  for every public export, including the `rouzer/http` and `rouzer/ndjson`
-  subpaths.
-- Public TSDoc in `src/` owns symbol-level behavior and option details.
+- [Documentation map](docs/index.md)
+- [Framework concepts](docs/concepts.md)
+- [Route contracts](docs/routes.md)
+- [Middleware and request context](docs/middleware.md)
+- [Routers and handlers](docs/handlers.md)
+- [Typed client](docs/client.md)
+- [Responses, errors, and plugins](docs/responses.md)
+- [NDJSON streaming](docs/streaming.md)
+- [Runtime and adapters](docs/runtime.md)
+- [Patterns, constraints, and migrations](docs/patterns.md)
+- [Migration from v5 to v6](docs/migration-v5-to-v6.md)
+
+Runnable examples:
+
+- [Basic shared-route example](examples/basic-usage.ts)
+- [Typed status response example](examples/error-responses.ts)
+- [NDJSON response-stream example](examples/ndjson-stream.ts)
+
+Published declarations provide exact signatures for every public export,
+including the `rouzer/http` and `rouzer/ndjson` subpaths. Public TSDoc in `src/`
+owns symbol-level behavior and option details.

package/dist/server/router.d.ts

@@ -1,5 +1,4 @@
-import type { HattipHandler } from '@hattip/core';
-import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes } from 'alien-middleware';
+import { ApplyMiddleware, chain, ExtractMiddleware, MiddlewareChain, MiddlewareTypes, RequestHandler } from 'alien-middleware';
 import { type HttpRouteTree } from '../http.js';
 import { type RouterResponsePlugin } from '../response.js';
 import type { RouteRequestHandlerMap } from '../types/server.js';
@@ -46,10 +45,10 @@ export type RouterConfig = {
     };
 };
 /**
- * Hattip-compatible Rouzer handler with chainable middleware and route
+ * Fetch-compatible Rouzer handler with chainable middleware and route
  * registration.
  */
-export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T['platform']>, MiddlewareChain<T> {
+export interface Router<T extends MiddlewareTypes = any> extends RequestHandler<T>, MiddlewareChain<T> {
     /**
      * Clone this router and add the given middleware to the end of the chain.
      *
@@ -68,11 +67,11 @@ export interface Router<T extends MiddlewareTypes = any> extends HattipHandler<T
     use<TRoutes extends HttpRouteTree>(routes: TRoutes, handlers: RouteRequestHandlerMap<TRoutes, this>): Router<T>;
 }
 /**
- * Create a Rouzer router that can be mounted by any Hattip adapter.
+ * Create a Rouzer router that can be mounted as a fetch-compatible handler.
  *
  * @param config Optional router configuration for base path, debug behavior,
  * response plugins, and CORS origin restrictions.
- * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
+ * @returns A fetch-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */
-export declare function createRouter<TEnv extends object = {}, TProperties extends object = {}, TPlatform = unknown>(config?: RouterConfig): Router<MiddlewareTypes<TEnv, TProperties, TPlatform>>;
+export declare function createRouter<TEnv extends object = {}, TProperties extends object = {}, TRuntime = unknown>(config?: RouterConfig): Router<MiddlewareTypes<TEnv, TProperties, TRuntime>>;

package/dist/server/router.js

@@ -142,11 +142,11 @@ class RouterObject extends MiddlewareChain {
     }
 }
 /**
- * Create a Rouzer router that can be mounted by any Hattip adapter.
+ * Create a Rouzer router that can be mounted as a fetch-compatible handler.
  *
  * @param config Optional router configuration for base path, debug behavior,
  * response plugins, and CORS origin restrictions.
- * @returns A Hattip-compatible handler with `.use(...)` methods for middleware
+ * @returns A fetch-compatible handler with `.use(...)` methods for middleware
  * and route registration.
  */
 export function createRouter(config = {}) {

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),
+})
+```