rouzer 5.3.0 → 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/http.d.ts

@@ -1,5 +1,5 @@
 import { RoutePattern } from '@remix-run/route-pattern';
-import { type RouteMetadata, type RouteMetadataMarker } from './metadata.js';
+import { type RouteMetadata } from './metadata.js';
 import type { RawBodySchema, RouteSchema } from './types/schema.js';
 /** HTTP methods supported by Rouzer action declarations. */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -43,7 +43,6 @@ export type HttpNode = HttpAction | HttpResource;
 export type HttpRouteTree = {
     [key: string]: HttpNode;
 };
-type RouteDeclaration<T extends object> = T & Partial<RouteMetadataMarker>;
 type StringKeys<T> = Pick<T, Extract<keyof T, string>>;
 /**
  * Declare an HTTP resource namespace.
@@ -52,22 +51,22 @@ type StringKeys<T> = Pick<T, Extract<keyof T, string>>;
  * property names are API names only; they do not affect the URL unless the child
  * is another resource or an action with an explicit path.
  */
-export declare function resource<const P extends string, const TChildren extends HttpRouteTree>(path: P, children: RouteDeclaration<TChildren>): HttpResource<P, StringKeys<TChildren>>;
+export declare function resource<const P extends string, const TChildren extends HttpRouteTree>(path: P, children: TChildren): HttpResource<P, StringKeys<TChildren>>;
 /** Declare a GET action, optionally with an action-local path segment. */
-export declare function get<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'GET'>;
-export declare function get<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'GET'>;
+export declare function get<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'GET'>;
+export declare function get<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'GET'>;
 /** Declare a POST action, optionally with an action-local path segment. */
-export declare function post<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'POST'>;
-export declare function post<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'POST'>;
+export declare function post<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'POST'>;
+export declare function post<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'POST'>;
 /** Declare a PUT action, optionally with an action-local path segment. */
-export declare function put<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'PUT'>;
-export declare function put<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'PUT'>;
+export declare function put<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PUT'>;
+export declare function put<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PUT'>;
 /** Declare a PATCH action, optionally with an action-local path segment. */
-export declare function patch<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'PATCH'>;
-export declare function patch<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'PATCH'>;
+export declare function patch<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'PATCH'>;
+export declare function patch<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'PATCH'>;
 /** Declare a DELETE action, optionally with an action-local path segment. */
-declare function deleteAction<const P extends string, const T extends RouteSchema>(path: P, schema: RouteDeclaration<T>): HttpAction<P, T, 'DELETE'>;
-declare function deleteAction<const T extends RouteSchema>(schema: RouteDeclaration<T>): HttpAction<'', T, 'DELETE'>;
+declare function deleteAction<const P extends string, const T extends RouteSchema>(path: P, schema: T): HttpAction<P, T, 'DELETE'>;
+declare function deleteAction<const T extends RouteSchema>(schema: T): HttpAction<'', T, 'DELETE'>;
 export { deleteAction as delete };
 /**
  * Declare a request body that is passed through to `fetch` without JSON encoding.

package/dist/metadata.d.ts

@@ -6,11 +6,8 @@ export type RouteMetadata = {
     /** Human-readable route description for generated tooling. */
     description?: string;
 };
-export type RouteMetadataMarker = {
-    readonly [routeMetadataKey]: RouteMetadata;
-};
 /** Attach runtime metadata to a route declaration. */
-export declare function metadata(value: RouteMetadata): RouteMetadataMarker;
+export declare function metadata(value: RouteMetadata): object;
 export declare function getRouteMetadata(value: unknown): RouteMetadata | undefined;
 export declare function stripRouteMetadata<T extends object>(value: T): Omit<T, typeof routeMetadataKey>;
 export {};

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 = {}) {