rouzer 3.1.0 → 4.0.0

package/dist/type.js

@@ -1,9 +1,12 @@
 /**
  * Create a compile-time-only marker for an action's JSON response payload type.
  *
- * @remarks `$type<T>()` does not perform runtime validation. It lets Rouzer type
- * server handler return values and client action functions for HTTP actions
- * whose responses are expected to be JSON.
+ * @remarks `$type<T>()` does not validate handler return values at the server
+ * boundary. It lets Rouzer type server handler return values and client action
+ * functions for HTTP actions whose responses are expected to be JSON. Use it
+ * directly as `response` for one JSON success shape, or as a success entry in a
+ * status-keyed response map. Validate response data where it enters your server
+ * or client code when runtime integrity is required.
  *
  * @example
  * ```ts
@@ -19,3 +22,29 @@ export function $type() {
     return $type.symbol;
 }
 $type.symbol = Symbol();
+/**
+ * Create a compile-time-only marker for a declared error response type.
+ *
+ * @remarks `$error<T>()` marks a non-success response branch in a status-keyed
+ * response map. It is a type contract, not a runtime validator. On the server,
+ * handlers use `ctx.error(status, body)` to return declared errors. On the
+ * client, declared error responses resolve as `[error, null, status]` tuple
+ * entries instead of rejecting the promise.
+ *
+ * @example
+ * ```ts
+ * import { $type, $error } from 'rouzer'
+ * import * as http from 'rouzer/http'
+ *
+ * const getUser = http.get('users/:id', {
+ *   response: {
+ *     200: $type<User>(),
+ *     404: $error<{ code: string; message: string }>(),
+ *   },
+ * })
+ * ```
+ */
+export function $error() {
+    return $error.symbol;
+}
+$error.symbol = Symbol();

package/dist/types/args.d.ts

@@ -32,7 +32,7 @@ type MutationArgs<T> = T extends MutationRouteSchema ? T extends {
     body?: unknown;
 } : unknown;
 /**
- * Arguments accepted by a client action function or low-level request factory.
+ * Arguments accepted by a generated client action function.
  *
  * @remarks The type is derived from an action schema and route pattern. `path`,
  * `query`, `body`, and `headers` are validated by the client before `fetch` when

package/dist/types/handler.d.ts

@@ -3,11 +3,61 @@ import type { AnyMiddlewareChain, MiddlewareContext } from 'alien-middleware';
 import type * as z from 'zod';
 import { Promisable } from '../common.js';
 import type { HttpAction } from '../http.js';
-import type { InferRouteHandlerResult } from './response.js';
-import type { RouteSchema } from './schema.js';
+import type { InferRouteHandlerResult, InferResponseMapErrors, InferResponseMapSuccesses } from './response.js';
+import type { RouteResponseMap, RouteSchema } from './schema.js';
 type RequestContext<TMiddleware extends AnyMiddlewareChain> = MiddlewareContext<TMiddleware>;
-export type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult> = (context: RequestContext<TMiddleware> & TArgs) => Promisable<TResult | Response>;
-export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction extends HttpAction, TPath extends string> = TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
+/**
+ * Error response returned by `ctx.error(status, body)` in route handlers.
+ *
+ * @remarks This is an opaque branded type returned by the error helper. Route
+ * handlers may return it to signal a declared error response.
+ */
+export type RouteErrorResponse = Response & {
+    __routeError__: true;
+};
+/** Response returned by `ctx.success(status, body)` in route handlers. */
+export type RouteSuccessResponse = Response & {
+    __routeSuccess__: true;
+};
+export type RouteRequestHandler<TMiddleware extends AnyMiddlewareChain, TArgs extends object, TResult, TErrors = never, TSuccesses = never> = (context: RequestContext<TMiddleware> & TArgs & ([TErrors] extends [never] ? {} : {
+    /**
+     * Return a declared error response.
+     *
+     * @remarks Only statuses declared with `$error<T>()` in the response
+     * map are accepted.
+     */
+    error: <TEntry extends TErrors>(...args: TEntry extends [infer S extends number, infer B] ? [status: S, body: B] : never) => RouteErrorResponse;
+}) & ([TSuccesses] extends [never] ? {} : {
+    /**
+     * Return a declared success response with an explicit status.
+     *
+     * @remarks Useful when a response map declares multiple 2xx statuses.
+     */
+    success: <TEntry extends TSuccesses>(...args: TEntry extends [infer S extends number, infer B] ? [status: S, body: B] : never) => RouteSuccessResponse;
+})) => Promisable<TResult | Response>;
+export type InferActionHandler<TMiddleware extends AnyMiddlewareChain, TAction extends HttpAction, TPath extends string> = TAction['schema'] extends {
+    response: infer R extends RouteResponseMap;
+} ? TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
+        path: any;
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    query: TAction['schema'] extends {
+        query: any;
+    } ? z.infer<TAction['schema']['query']> : undefined;
+    headers: TAction['schema'] extends {
+        headers: any;
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>, InferResponseMapErrors<R>, InferResponseMapSuccesses<R>> : RouteRequestHandler<TMiddleware, {
+    path: TAction['schema'] extends {
+        path: any;
+    } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;
+    body: TAction['schema'] extends {
+        body: any;
+    } ? z.infer<TAction['schema']['body']> : undefined;
+    headers: TAction['schema'] extends {
+        headers: any;
+    } ? z.infer<TAction['schema']['headers']> : undefined;
+}, InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>, InferResponseMapErrors<R>, InferResponseMapSuccesses<R>> : TAction['method'] extends 'GET' ? RouteRequestHandler<TMiddleware, {
     path: TAction['schema'] extends {
         path: any;
     } ? z.infer<TAction['schema']['path']> : MatchParams<TPath>;

package/dist/types/index.d.ts

@@ -1,7 +1,6 @@
 export type * from './args.js';
 export type * from './handler.js';
 export type * from './infer.js';
-export type * from './request.js';
 export type * from './response.js';
 export type * from './schema.js';
 export type * from './server.js';

package/dist/types/infer.d.ts

@@ -1,19 +1,14 @@
 import type * as z from 'zod';
 import type { MutationRouteSchema, RouteSchema } from './schema.js';
-import type { RouteRequestFactory } from './request.js';
 type InferRouteSchemaBody<TSchema> = TSchema extends MutationRouteSchema ? TSchema extends {
     body: infer TBody;
 } ? z.infer<TBody> : unknown : never;
-type InferRouteArgsBody<TArgs> = TArgs extends {
-    body?: infer TBody;
-} ? TBody : never;
 /**
- * Infer the request body type from an action schema or request factory.
+ * Infer the request body type from an action schema.
  *
  * @remarks HTTP action schemas can be inspected with
- * `InferRouteBody<typeof action.schema>`. Request factories for mutation actions
- * infer their `body` argument type. Schemas without a body schema infer
+ * `InferRouteBody<typeof action.schema>`. Schemas without a body schema infer
  * `unknown`.
  */
-export type InferRouteBody<T> = T extends RouteRequestFactory<any, any> ? InferRouteArgsBody<T['$args']> : T extends RouteSchema ? InferRouteSchemaBody<T> : never;
+export type InferRouteBody<T> = T extends RouteSchema ? InferRouteSchemaBody<T> : never;
 export {};

package/dist/types/response.d.ts

@@ -1,17 +1,57 @@
-import type { ResponsePluginMarker, RouteSchema, Unchecked } from './schema.js';
+import type { Unchecked, UncheckedError } from '../common.js';
+import type { ResponsePluginMarker } from '../response.js';
+import type { RouteResponseMap, RouteSchema } from './schema.js';
 /** `Response` whose `.json()` method resolves to a known payload type. */
 export type RouteResponse<TResult = any> = Response & {
     json(): Promise<TResult>;
 };
-/** Infer the client response type from an action schema. */
+/**
+ * Helper: given a status-keyed response map, produce the discriminated tuple
+ * union for the client.
+ *
+ * Each entry becomes:
+ * - `$type<T>()` → `[null, T, Status]`
+ * - `$error<T>()` → `[T, null, Status]`
+ */
+type InferResponseMapClient<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends UncheckedError<infer TError> ? [TError, null, K] : T[K] extends Unchecked<infer TSuccess> ? [null, TSuccess, K] : T[K] extends ResponsePluginMarker<infer TClient, any> ? [null, TClient, K] : never;
+}[keyof T & number];
+/**
+ * Infer the generated client action result type from an action schema.
+ *
+ * @remarks Direct JSON markers infer their payload type, plugin markers infer
+ * their client result type, and status-keyed response maps infer a tuple union
+ * of `[null, value, status]` success entries and `[error, null, status]` error
+ * entries.
+ */
 export type InferRouteResponse<T extends RouteSchema> = T extends {
-    response: ResponsePluginMarker<infer TClient, any>;
-} ? TClient : T extends {
-    response: Unchecked<infer TResponse>;
-} ? TResponse : void;
-/** Infer the non-`Response` handler result type from an action schema. */
+    response: infer R;
+} ? R extends ResponsePluginMarker<infer TClient, any> ? TClient : R extends Unchecked<infer TResponse> ? TResponse : R extends RouteResponseMap ? InferResponseMapClient<R> : void : void;
+/**
+ * Helper: given a status-keyed response map, produce the union of handler
+ * result types (success values the handler can return directly).
+ */
+type InferResponseMapHandlerResult<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends Unchecked<infer TSuccess> ? TSuccess : T[K] extends ResponsePluginMarker<any, infer TRouter> ? TRouter : never;
+}[keyof T & number];
+/**
+ * Infer the non-`Response` handler result type from an action schema.
+ *
+ * @remarks For status-keyed response maps, this includes only success result
+ * values. Declared error responses are returned with `ctx.error(status, body)`.
+ */
 export type InferRouteHandlerResult<T extends RouteSchema> = T extends {
-    response: ResponsePluginMarker<any, infer TRouter>;
-} ? TRouter : T extends {
-    response: Unchecked<infer TResponse>;
-} ? TResponse : void;
+    response: infer R;
+} ? R extends ResponsePluginMarker<any, infer TRouter> ? TRouter : R extends Unchecked<infer TResponse> ? TResponse : R extends RouteResponseMap ? InferResponseMapHandlerResult<R> : void : void;
+/**
+ * Helper: given a status-keyed response map, extract error entries as a union
+ * of `[status, body]` pairs for typing `ctx.error(status, body)`.
+ */
+export type InferResponseMapErrors<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends UncheckedError<infer TError> ? [K, TError] : never;
+}[keyof T & number];
+/** Extract success entries as a union of `[status, body]` pairs. */
+export type InferResponseMapSuccesses<T extends RouteResponseMap> = {
+    [K in keyof T & number]: T[K] extends Unchecked<infer TSuccess> ? [K, TSuccess] : T[K] extends ResponsePluginMarker<any, infer TRouter> ? [K, TRouter] : never;
+}[keyof T & number];
+export {};

package/dist/types/schema.d.ts

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import type { Unchecked } from '../common.js';
+import type { Unchecked, UncheckedError } from '../common.js';
 import type { ResponsePluginMarker } from '../response.js';
 /**
  * Compile-time-only marker used by `$type<T>()` for unchecked JSON response
@@ -8,10 +8,21 @@ import type { ResponsePluginMarker } from '../response.js';
  * @remarks Application code should usually call `$type<T>()` instead of naming
  * this marker directly.
  */
-export type { Unchecked };
-export type { ResponsePluginMarker };
+export type { ResponsePluginMarker, Unchecked, UncheckedError };
+/** Single response marker accepted by status-keyed response maps. */
+export type RouteResponseMarker = Unchecked<any> | UncheckedError<any> | ResponsePluginMarker<any, any>;
+/**
+ * Status-keyed response map for declaring multiple response types.
+ *
+ * @remarks Numeric keys are HTTP status codes. Use `$type<T>()` or a response
+ * plugin marker for success responses and `$error<T>()` for declared error
+ * JSON responses.
+ */
+export type RouteResponseMap = {
+    [status: number]: RouteResponseMarker;
+};
 /** Response marker accepted by HTTP action schemas. */
-export type RouteResponseSchema = Unchecked<any> | ResponsePluginMarker<any, any>;
+export type RouteResponseSchema = Unchecked<any> | ResponsePluginMarker<any, any> | RouteResponseMap;
 /** Schema shape for `GET` route methods. */
 export type QueryRouteSchema = {
     /** Optional Zod object used to validate path params. */

package/docs/context.md

@@ -2,8 +2,8 @@
 
 Rouzer is for applications that want one TypeScript HTTP route tree to drive
 both the server and the client that calls it. A route tree combines URL
-patterns, named actions, HTTP method schemas, and optional compile-time JSON or
-NDJSON response types.
+patterns, named actions, HTTP method schemas, and optional compile-time success,
+error, or plugin response types.
 
 ## When to use Rouzer
 
@@ -17,9 +17,12 @@ Use Rouzer when:
 - generated clients should stay close to route definitions instead of being
   produced by a separate OpenAPI build step
 
-Rouzer is not a response validation library, an OpenAPI generator, or a complete
+Rouzer is not a server response validator, an OpenAPI generator, or a complete
 server framework. It focuses on typed route contracts, request validation,
-routing, and a small client wrapper.
+routing, and a small client wrapper. Response markers are type contracts; if
+response data comes from an untrusted source, validate it where it enters your
+server or client code instead of relying on the router to re-check handler
+returns.
 
 ## Core abstractions
 
@@ -92,11 +95,47 @@ The HTTP action API models explicit operations. It does not expose the old
 method-map `ALL` fallback route shape; declare the concrete methods your client
 and server support.
 
-### `$type<T>()` and `ndjson.$type<T>()`
+### Response markers and maps
 
-`response: $type<T>()` is a TypeScript-only marker for JSON response payloads.
-It tells handlers and client action functions what response payload type to
-expect, but Rouzer does not validate response bodies at runtime.
+`response: $type<T>()` is a TypeScript-only marker for JSON success payloads. It
+tells handlers and client action functions what payload type to expect, but
+Rouzer does not validate handler return values at the server boundary. Validate
+response data where it enters your system, such as an external API client,
+database decoder, or UI/client boundary, when runtime integrity is required.
+
+Use a status-keyed response map when callers need to branch on declared statuses:
+
+```ts
+import { $error, $type } 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>(),
+    201: $type<User>(),
+    404: $error<NotFound>(),
+  },
+})
+```
+
+Success entries use `$type<T>()` or a response plugin marker. Error entries use
+`$error<T>()` and are encoded as JSON. Generated client action functions resolve
+declared statuses as tuples:
+
+- success: `[null, value, status]`
+- error: `[error, null, status]`
+
+Declared error statuses do not reject the client promise. Undeclared statuses
+still go through `onJsonError` or throw the default error.
+
+Handlers for response-map actions may return the default success value directly,
+use `ctx.success(status, body)` to choose a declared success status, or use
+`ctx.error(status, body)` to return a declared error status. The `ctx.error` and
+`ctx.success` helpers only accept statuses and bodies declared in the response
+map.
 
 `response: ndjson.$type<T>()` is a TypeScript-only marker for newline-delimited
 JSON response streams from the `rouzer/ndjson` subpath. Register
@@ -109,8 +148,8 @@ response body. Streamed items are parsed as JSON but are not validated against a
 Zod schema.
 
 Actions without a `response` marker return a raw `Response` from client action
-functions. Actions with `response: $type<T>()` use `client.json(...)` under the
-hood and return parsed JSON typed as `T`.
+functions. Actions with `response: $type<T>()` return parsed JSON typed as `T`.
+Actions with a response map return the tuple union described by that map.
 
 ### Response plugins
 
@@ -121,10 +160,11 @@ matching runtime plugins. For NDJSON, those are `ndjson.$type<T>()`,
 
 The router plugin encodes non-`Response` handler results into an HTTP `Response`.
 The client plugin decodes successful HTTP responses for generated client action
-functions. Rouzer validates plugin registration when routes are attached to a
-router or client, so routes that use an unregistered response marker fail fast
-instead of falling back to JSON. Response plugins do not automatically validate
-response payloads unless the plugin itself implements validation.
+functions. Plugin markers can also be success entries in a status-keyed response
+map. Rouzer validates plugin registration when routes are attached to a router or
+client, so routes that use an unregistered response marker fail fast instead of
+falling back to JSON. Response plugins do not automatically validate response
+payloads unless the plugin itself implements validation.
 
 ### Router
 
@@ -157,6 +197,8 @@ Handlers receive a context typed from middleware plus the action schema:
 - `GET` handlers receive `ctx.path`, `ctx.query`, and `ctx.headers`
 - mutation handlers receive `ctx.path`, `ctx.body`, and `ctx.headers`
 - handlers may return a plain JSON-serializable value or a `Response`
+- response-map handlers can return a default success value directly or use
+  `ctx.success(status, body)` and `ctx.error(status, body)`
 - `ndjson.$type<T>()` handlers return an `Iterable<T>` or `AsyncIterable<T>`
   unless they return a custom `Response`
 - plain values are returned with `Response.json(value)`
@@ -169,16 +211,16 @@ requests with an `Origin` header.
 
 ### Client
 
-`createClient({ baseURL, routes })` creates:
+`createClient({ baseURL, routes })` creates a client tree that mirrors
+`routes`, with action functions such as `client.profiles.get(args)`.
+Generated action functions include:
 
-- `client.request(action.request(args))` for a raw `Response` when the action
-  request factory contains the full path you want to call
-- `client.json(action.request(args))` for parsed JSON and default non-2xx
-  throwing
-- response plugin support for generated client action functions, such as
-  `ndjson.clientPlugin` for NDJSON response streams
-- a client tree that mirrors `routes`, with action functions such as
-  `client.profiles.get(args)` when `routes` is supplied
+- raw `Response` results for actions without a response schema
+- parsed JSON and default non-2xx throwing for `$type<T>()` responses
+- response-map support, returning `[error, value, status]` tuples for declared
+  statuses
+- response plugin support, such as `ndjson.clientPlugin` for NDJSON response
+  streams
 
 Prefer an absolute `baseURL` for generated client URLs:
 
@@ -191,7 +233,8 @@ const client = createClient({
 
 Default headers can be supplied with `headers`, per-request headers are merged on
 top, and a custom `fetch` implementation can be supplied for tests or non-browser
-runtimes.
+runtimes. The returned client exposes the original options as `clientConfig`, so
+route actions named `config` remain available as `client.config(...)`.
 
 ## Lifecycle
 
@@ -205,9 +248,9 @@ runtimes.
    `fetch`.
 5. The router matches the request, validates the matched inputs, and calls the
    handler.
-6. Plain handler results become JSON responses, plugin handler results become
-   plugin-encoded responses, and explicit `Response` objects pass through
-   unchanged.
+6. Plain handler results become JSON responses, response-map helpers choose
+   declared statuses, plugin handler results become plugin-encoded responses, and
+   explicit `Response` objects pass through unchanged.
 
 On the server, `path`, `query`, and `headers` values originate as strings. Rouzer
 coerces Zod `number` schemas with `Number(value)` and Zod `boolean` schemas from
@@ -216,9 +259,9 @@ string-coercion step.
 
 ## Common tasks
 
-### Choose a client call style
+### Call client actions
 
-Use client action functions for normal application calls:
+Use generated client action functions for application calls:
 
 ```ts
 await client.profiles.get({ path: { id: '42' } })
@@ -228,28 +271,60 @@ await client.profiles.update({
 })
 ```
 
-Use longhand calls when you need to choose response handling explicitly. The
-action request factory must include the full path you want to call, so this style
-is most convenient for top-level actions:
+### Handle declared error responses
+
+Use `$error<T>()` inside a response map when an error status is part of the route
+contract:
 
 ```ts
-export const getProfile = http.get('profiles/:id', {
-  response: $type<Profile>(),
+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 = { getProfile }
+export const routes = { getUser }
 
-const response = await client.request(
-  routes.getProfile.request({ path: { id: '42' } })
-)
+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 json = await client.json(
-  routes.getProfile.request({ path: { id: '42' } })
-)
+const client = createClient({
+  baseURL: 'https://example.com/api/',
+  routes,
+})
+
+const [error, user, status] = await client.getUser({
+  path: { id: 'missing' },
+})
+
+if (status === 404) {
+  console.log(error.message)
+} else {
+  console.log(user.name)
+}
 ```
 
-Response plugins are applied by generated client action functions. For longhand
-calls to plugin-backed routes, use `client.request(...)` for the raw `Response`
-and call the plugin subpath's decoder yourself.
+A complete runnable version lives in
+[`examples/error-responses.ts`](../examples/error-responses.ts).
+
+When a response map declares multiple success statuses, return a plain value for
+the default success status or use `ctx.success(status, body)` to choose a
+specific declared success status.
 
 ### Stream newline-delimited JSON
 
@@ -321,9 +396,9 @@ custom headers. Return a plain value for the default `Response.json(value)` path
 
 ### Customize JSON errors
 
-By default, `client.json(...)` and generated client action functions throw for
-non-2xx responses. If the response body is JSON, its properties are copied onto
-the thrown `Error`.
+By default, generated client action functions throw for
+non-2xx responses that are not declared in a response map. If the response body
+is JSON, its properties are copied onto the thrown `Error`.
 
 `onJsonError` can override that behavior. Its return value is returned from the
 response helper as-is; Rouzer does not automatically parse a returned `Response`
@@ -385,11 +460,13 @@ await client.profiles.update({
 - Export route trees from a small shared module and import that module on both
   server and client.
 - Use `rouzer/http` actions for routes that are registered with
-  `createRouter().use(...)` or `createClient({ routes })`.
+  `createRouter().use(...)` or the required `createClient({ routes })` option.
 - Add Zod schemas when you need runtime guarantees; rely on inferred path params
   only when string params are sufficient.
 - Use `response: $type<T>()` for JSON endpoints that should have typed client
   action functions.
+- Use response maps with `$error<T>()` when callers should handle declared error
+  statuses as typed data instead of exceptions.
 - Use `response: ndjson.$type<T>()` plus `ndjson.routerPlugin` and
   `ndjson.clientPlugin` for response streams where each line is a JSON value and
   the client should consume an `AsyncIterable<T>`.
@@ -400,20 +477,22 @@ await client.profiles.update({
 
 ## Constraints and gotchas
 
-- `$type<T>()` and `ndjson.$type<T>()` are compile-time only and do not validate
-  response payloads or streamed items.
+- `$type<T>()`, `$error<T>()`, and `ndjson.$type<T>()` are compile-time-only type
+  contracts. Rouzer does not re-validate handler return values at the server
+  boundary.
 - NDJSON support is for response streams; request bodies still use the existing
   JSON body schema path.
+- Declared `$error<T>()` responses are JSON responses. Use a custom `Response`
+  for non-JSON error payloads.
 - Routes that use a response plugin fail fast if the matching client or router
   plugin is not registered.
 - Pathname route patterns expect an absolute client `baseURL`.
 - Resource and action keys are API names only; paths come from the pattern
   strings passed to `http.resource(...)` and action helpers.
-- Nested action `.request(...)` factories do not include parent resource paths;
-  prefer client action functions for nested resources.
 - Extra `RequestInit` fields in route args, such as `signal` or `credentials`,
-  are forwarded by `createClient`; `method`, `body`, and `headers` are reserved
-  for Rouzer's action metadata and validated call arguments.
+  are forwarded by `createClient`; `method` and `body` are reserved for Rouzer's
+  action metadata and validated call arguments. Use route args or client defaults
+  for request headers.
 - The HTTP action API has no `ALL` fallback route. Declare explicit actions for
   supported methods.
 - Rouzer does not automatically set `Access-Control-Allow-Credentials`; set it in

package/examples/error-responses.ts

@@ -0,0 +1,98 @@
+import type { HattipHandler } from '@hattip/core'
+import { $error, $type, createClient, createRouter } from 'rouzer'
+import * as http from 'rouzer/http'
+
+type User = {
+  id: string
+  name: string
+}
+
+type AuthError = {
+  code: 'UNAUTHORIZED'
+  message: string
+}
+
+type NotFoundError = {
+  code: 'NOT_FOUND'
+  message: string
+}
+
+export const getUser = http.get('users/:id', {
+  response: {
+    200: $type<User>(),
+    201: $type<User>(),
+    401: $error<AuthError>(),
+    404: $error<NotFoundError>(),
+  },
+})
+
+export const routes = { getUser }
+
+/**
+ * Tiny Hattip adapter used only to keep this example self-contained. Real apps
+ * mount the handler with a Hattip adapter for their runtime.
+ */
+function createLocalFetch(handler: HattipHandler): typeof fetch {
+  return async (input, init) => {
+    const request = new Request(input, init)
+    const response = await handler({
+      request,
+      ip: '127.0.0.1',
+      platform: undefined,
+      env() {
+        return undefined
+      },
+      passThrough() {},
+      waitUntil(promise) {
+        void promise
+      },
+    })
+
+    return response ?? new Response(null, { status: 404 })
+  }
+}
+
+export async function runErrorResponsesExample() {
+  const users = new Map([['42', { id: '42', name: 'Ada' }]])
+
+  const handler = createRouter({ basePath: 'api/' }).use(routes, {
+    getUser(ctx) {
+      if (ctx.path.id === 'unauthorized') {
+        return ctx.error(401, {
+          code: 'UNAUTHORIZED',
+          message: 'Login required',
+        })
+      }
+
+      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
+    },
+  })
+
+  const client = createClient({
+    baseURL: 'https://example.test/api/',
+    routes,
+    fetch: createLocalFetch(handler),
+  })
+
+  const found = await client.getUser({ path: { id: '42' } })
+  const created = await client.getUser({ path: { id: 'created' } })
+  const missing = await client.getUser({ path: { id: 'missing' } })
+  const unauthorized = await client.getUser({ path: { id: 'unauthorized' } })
+
+  return { found, created, missing, unauthorized }
+}