rouzer 6.0.0 → 6.0.1

package/docs/client.md

@@ -1,5 +1,8 @@
 # Typed client
 
+> Turn the shared route tree into action functions with validated input,
+> per-request Fetch options, and response types that match each route contract.
+
 `createClient({ baseURL, routes })` creates a typed fetch client from the same
 route tree used by the server.
 
@@ -70,9 +73,12 @@ await client.updateProfile({
 })
 ```
 
-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.
+Per-request `RequestInit` options are the second argument. Headers are typed from
+the route header schema when one exists.
+
+> [!IMPORTANT]
+> Rouzer reserves `method` and owns JSON body encoding. Do not override either
+> through per-request options.
 
 ```ts
 await client.profiles.get(
@@ -84,9 +90,10 @@ await client.profiles.get(
 )
 ```
 
-Avoid duplicate keys across path, query, and JSON body schemas. The flat client
-input cannot distinguish duplicate field names from different request
-locations.
+> [!IMPORTANT]
+> Keep keys unique across path, query, and JSON body schemas. The flat client
+> input cannot distinguish duplicate field names from different request
+> locations.
 
 ## Raw Body Routes
 
@@ -100,6 +107,10 @@ await client.uploadAvatar(
 )
 ```
 
+> [!NOTE]
+> Raw-body argument placement changes when the route has no path or query input:
+> pass the body as the first argument instead of `options.body`.
+
 For raw-body routes without route input, pass the body as the first argument.
 
 ```ts
@@ -178,9 +189,10 @@ 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.
+> [!NOTE]
+> For streaming response plugins, `request.success` is emitted when the action
+> resolves to the stream object. Errors that happen while consuming the stream
+> are outside the client hook lifecycle.
 
 ## Testing With Local Fetch
 

package/docs/concepts.md

@@ -1,9 +1,12 @@
 # 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 it is reused by the router and generated client.
+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
@@ -67,9 +70,11 @@ 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.
+> [!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
 

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

@@ -1,5 +1,8 @@
 # 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.
 
@@ -97,9 +100,10 @@ For a matched route, Rouzer validates before the handler runs:
 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.
+> [!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.
@@ -183,8 +187,9 @@ When an allowed request includes an `Origin` header, Rouzer sets
 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.
+> [!WARNING]
+> Rouzer does not set `Access-Control-Allow-Credentials`. Set that header
+> yourself before relying on credentialed cross-origin requests.
 
 ## Middleware Ordering
 

package/docs/index.md

@@ -1,9 +1,11 @@
 # 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. 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.
+router, a typed fetch client, and request context composition. The guides keep
+those concerns separate while showing where they meet.
 
 ## Learning Path
 
@@ -21,10 +23,13 @@ you can do and how the pieces fit together.
    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.
+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
 
@@ -43,20 +48,40 @@ you can do and how the pieces fit together.
 
 ## 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.
+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
 

package/docs/middleware.md

@@ -1,5 +1,8 @@
 # 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.
@@ -119,13 +122,15 @@ const router = createRouter()
   })
 ```
 
-The `env` key is reserved for environment bindings. Values are accessed through
-`ctx.env(name)`, not as `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
 
-The `runtime` request plugin key is reserved as a type-level marker for
-`ctx.host.runtime`; it does not add `ctx.runtime`.
+> [!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()
@@ -176,10 +181,11 @@ 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.
+> [!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.

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

@@ -1,12 +1,17 @@
 # Migrating from v5 to v6
 
+> Move a v5 application from Hattip-compatible server integration to Rouzer's
+> Fetch-compatible handler boundary without rewriting its route contract.
+
 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.
+> [!IMPORTANT]
+> Most applications only need to update server mounting code, tests, and any
+> explicit Hattip handler or context types. Keep the shared route tree unchanged
+> unless the application API is changing too.
 
 ## Replace Hattip adapters with Fetch handlers
 

package/docs/patterns.md

@@ -1,8 +1,15 @@
 # Patterns, constraints, and migrations
 
+> Review the stable project patterns and sharp edges that matter when route
+> contracts, middleware, handlers, and clients are composed in one application.
+
 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).
+client usage.
+
+> [!IMPORTANT]
+> For the v5 server-boundary upgrade, follow
+> [Migration from v5 to v6](migration-v5-to-v6.md) instead of treating this
+> checklist as a migration procedure.
 
 ## Preferred Patterns
 
@@ -84,8 +91,9 @@ src/
 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.
+> [!IMPORTANT]
+> Keep shared route modules free of server-only dependencies when browser
+> clients import them.
 
 ## v2 To v3 Route Shape
 

package/docs/responses.md

@@ -1,7 +1,14 @@
 # Responses, errors, and plugins
 
+> Choose whether callers receive typed JSON, a raw Web `Response`, a declared
+> status tuple, or a plugin-decoded value.
+
 Rouzer response schemas shape handler return types and generated client result
-types. They do not automatically validate handler return values at runtime.
+types.
+
+> [!IMPORTANT]
+> Response markers do not validate handler return values at runtime. They are
+> TypeScript contracts between handlers and generated clients.
 
 ## Plain JSON Success
 
@@ -161,9 +168,10 @@ createClient({
 })
 ```
 
-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.
+> [!IMPORTANT]
+> Register the matching response plugin on both the router and client. Rouzer
+> fails fast when attaching routes with an unregistered marker 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.

package/docs/routes.md

@@ -1,5 +1,8 @@
 # Route contracts
 
+> Define each HTTP operation once so its URL, validated input, handler type, and
+> generated client call stay aligned.
+
 Declare route contracts with the `rouzer/http` subpath. A route contract is the
 shared source of truth for server handler types, client action types, URL
 construction, and request validation.
@@ -127,8 +130,11 @@ export const updateProfile = http.patch('profiles/:id', {
 ```
 
 On the client, path, query, and JSON body fields are flattened into the first
-action argument. Avoid duplicate field names across those schemas because a flat
-object cannot represent separate values for the same key.
+action argument.
+
+> [!IMPORTANT]
+> Keep field names unique across path, query, and JSON body schemas. A flat
+> client input cannot represent separate values for the same key.
 
 ```ts
 await client.updateProfile({
@@ -157,6 +163,11 @@ await client.uploadAvatar(
 )
 ```
 
+> [!NOTE]
+> Raw-body argument placement depends on route input. With path or query input,
+> pass the body as `options.body`; without route input, pass the body as the
+> first argument.
+
 For a raw-body route without path or query input, the generated client accepts
 the body as the first argument.
 

package/docs/runtime.md

@@ -1,5 +1,8 @@
 # Runtime and adapters
 
+> Adapt a Rouzer request handler to a Fetch runtime while keeping host-specific
+> data behind the request context boundary.
+
 Rouzer routers are request handlers. Use adapter helpers to turn them into
 functions accepted by your HTTP server, framework, or tests.
 
@@ -116,8 +119,9 @@ For allowed non-preflight requests, Rouzer sets
 `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, and
 `Access-Control-Allow-Headers`.
 
-Rouzer does not set `Access-Control-Allow-Credentials`; set it yourself when
-credentialed requests need it.
+> [!WARNING]
+> Rouzer does not set `Access-Control-Allow-Credentials`. Set it yourself before
+> relying on credentialed cross-origin requests.
 
 ## Background Work
 
@@ -134,3 +138,8 @@ ctx.waitUntil(
 ```
 
 The adapter delegates to `host.waitUntil` when you provide it.
+
+> [!NOTE]
+> Without `host.waitUntil`, the request context has no runtime-specific lifetime
+> extension to delegate to. Provide it when background work must outlive the
+> response.

package/docs/streaming.md

@@ -1,5 +1,8 @@
 # NDJSON streaming
 
+> Stream a sequence of JSON values through a typed route while preserving
+> incremental delivery, cancellation, and explicit error modeling.
+
 Rouzer includes a response plugin for newline-delimited JSON response streams.
 Use it when a route should send a sequence of JSON values without buffering the
 whole response.
@@ -45,10 +48,11 @@ resolves to an `AsyncIterable<T>`.
 
 ## Plugin Registration
 
-Register both sides when a route tree contains `ndjson.$type<T>()`:
+> [!IMPORTANT]
+> Register both sides when a route tree contains `ndjson.$type<T>()`:
 
-- `ndjson.routerPlugin` in `createRouter({ plugins })`
-- `ndjson.clientPlugin` in `createClient({ plugins })`
+> - `ndjson.routerPlugin` in `createRouter({ plugins })`
+> - `ndjson.clientPlugin` in `createClient({ plugins })`
 
 Rouzer fails fast if a route uses a response plugin marker and the matching
 plugin is not registered.
@@ -89,8 +93,10 @@ adds a newline. The response content type defaults to
 and parses each line with `JSON.parse`. A final line does not need a trailing
 newline. Malformed JSON throws a `SyntaxError` with the line number.
 
-Streamed items are not validated against a Zod schema. If item validation is
-needed, validate before yielding on the server or while consuming on the client.
+> [!NOTE]
+> Streamed items are not validated against a Zod schema. If item validation is
+> needed, validate before yielding on the server or while consuming on the
+> client.
 
 ## Cancellation
 
@@ -98,8 +104,9 @@ 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
-cleanup needs to run while an awaited operation is still pending.
+> [!TIP]
+> Make waits for future events abort-aware when cleanup must run while an
+> awaited operation is still pending.
 
 ```ts
 async function readFirst<T>(source: AsyncIterable<T>) {
@@ -114,9 +121,10 @@ async function readFirst<T>(source: AsyncIterable<T>) {
 
 ## Stream Errors
 
-Rouzer does not convert handler or generator failures into extra NDJSON items.
-If an async generator throws after the response starts, the response stream
-errors and the client's `for await` loop throws.
+> [!NOTE]
+> Rouzer does not convert handler or generator failures into extra NDJSON items.
+> If an async generator throws after the response starts, the response stream
+> errors and the client's `for await` loop throws.
 
 Model application-level stream errors as part of your item type when clients
 should receive them as data.
@@ -127,5 +135,5 @@ type StreamItem =
   | { type: 'error'; message: string }
 ```
 
-The complete runnable version is
-[examples/ndjson-stream.ts](../examples/ndjson-stream.ts).
+The [complete runnable NDJSON example](https://github.com/alloc/rouzer/blob/main/examples/ndjson-stream.ts)
+includes the shared route, router, client, and stream consumption loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "packageManager": "pnpm@11.5.1",
   "type": "module",
   "exports": {
@@ -30,6 +30,7 @@
     "@alloc/prettier-config": "^1.0.0",
     "@types/node": "^25.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260515.1",
+    "lildocs": "^0.1.15",
     "prettier": "^3.8.3",
     "rouzer": "link:.",
     "tsc-lint": "^0.1.9",