rouzer 3.1.0 → 3.2.0

package/README.md

@@ -6,14 +6,14 @@ and Zod validation between a Hattip-compatible server and a typed fetch client.
 ## What it does
 
 A Rouzer HTTP route tree defines URL patterns, named actions, method schemas, and
-optional JSON or newline-delimited JSON response types once, then reuses that
-contract to:
+optional JSON, error, or newline-delimited JSON response types once, then reuses
+that contract to:
 
 - 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(...)`
-- parse typed JSON responses and typed NDJSON response streams
+- parse typed JSON responses, declared error responses, and NDJSON streams
 
 Rouzer optimizes for shared TypeScript route modules over language-agnostic API
 schemas or generated SDKs.
@@ -24,6 +24,8 @@ 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
 
@@ -31,8 +33,8 @@ Consider something else if:
 
 - you need OpenAPI-first workflows, schema files, or generated clients for other
   languages
-- you need runtime response-body validation; `response: $type<T>()` and
-  `response: ndjson.$type<T>()` are compile-time only
+- 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+
@@ -55,7 +57,7 @@ Import the primary API from the root package and declare routes through the HTTP
 subpath:
 
 ```ts
-import { $type, chain, createClient, createRouter } from 'rouzer'
+import { $error, $type, chain, createClient, createRouter } from 'rouzer'
 import * as http from 'rouzer/http'
 ```
 
@@ -103,6 +105,49 @@ const { message } = await client.hello({
 route arguments before `fetch`; server handlers validate matched path, query,
 headers, and JSON bodies before your handler runs.
 
+### 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({ path: { id: '42' } })
+```
+
+Success entries resolve as `[null, value, status]`; declared error entries
+resolve as `[error, null, status]`.
+
 ### NDJSON response streams
 
 Use `response: ndjson.$type<T>()` for endpoints that stream
@@ -141,6 +186,7 @@ for await (const event of await client.events()) {
 
 - [Concepts, API selection, and v2->v3 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`

package/dist/client/index.d.ts

@@ -106,8 +106,10 @@ export type ClientTree<T extends HttpRouteTree, TPrefix extends string = ''> = {
  * Client action function attached for each HTTP action leaf.
  *
  * @remarks Actions whose schema has `response: $type<T>()` return parsed JSON
- * as `T`. Actions whose schema has a plugin response marker return the plugin's
- * client result type. Actions without a response marker return the raw
+ * as `T`. Actions whose schema has a status-keyed response map return a tuple
+ * union of `[null, value, status]` success entries and `[error, null, status]`
+ * error entries. Actions whose schema has a plugin response marker return the
+ * plugin's client result type. Actions without a response marker return the raw
  * `Response`.
  */
 export type RouteFunction<T extends RouteSchema, P extends string> = (...p: RouteArgs<T, P> extends infer TArgs ? {} extends TArgs ? [args?: TArgs] : [args: TArgs] : never) => Promise<T extends {

package/dist/client/index.js

@@ -2,6 +2,7 @@ import { RoutePattern } from '@remix-run/route-pattern';
 import { createHref } from '@remix-run/route-pattern/href';
 import { shake } from '../common.js';
 import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
+import { getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
 /**
  * Create a typed fetch client for an HTTP route tree.
  *
@@ -69,17 +70,46 @@ export function createClient(config) {
     }
     async function response(props) {
         const httpResponse = await request(props);
+        const responseSchema = props.schema.response;
+        // Handle status-keyed response maps
+        if (isResponseMap(responseSchema)) {
+            const status = httpResponse.status;
+            if (status in responseSchema) {
+                const marker = responseSchema[status];
+                if (isErrorMarker(marker)) {
+                    return [await httpResponse.json(), null, status];
+                }
+                const pluginId = getResponsePluginMarkerId(marker);
+                if (pluginId) {
+                    const plugin = responsePlugins.get(pluginId);
+                    if (!plugin) {
+                        throw missingClientResponsePlugin(pluginId);
+                    }
+                    return [
+                        null,
+                        await plugin.decode(httpResponse, {
+                            marker: marker,
+                            request: props,
+                        }),
+                        status,
+                    ];
+                }
+                return [null, await httpResponse.json(), status];
+            }
+            // Undeclared status — reject
+            return handleResponseError(httpResponse, props);
+        }
         if (!httpResponse.ok) {
             return handleResponseError(httpResponse, props);
         }
-        const pluginId = getResponsePluginMarkerId(props.schema.response);
+        const pluginId = getResponsePluginMarkerId(responseSchema);
         if (pluginId) {
             const plugin = responsePlugins.get(pluginId);
             if (!plugin) {
                 throw missingClientResponsePlugin(pluginId);
             }
             return plugin.decode(httpResponse, {
-                marker: props.schema.response,
+                marker: responseSchema,
                 request: props,
             });
         }
@@ -133,9 +163,13 @@ function validateClientResponsePlugins(tree, plugins) {
             validateClientResponsePlugins(node.children, plugins);
         }
         else {
-            const pluginId = getResponsePluginMarkerId(node.schema.response);
-            if (pluginId && !plugins.has(pluginId)) {
-                throw missingClientResponsePlugin(pluginId);
+            const pluginIds = isResponseMap(node.schema.response)
+                ? getResponseMapPluginIds(node.schema.response)
+                : [getResponsePluginMarkerId(node.schema.response)].filter(pluginId => pluginId !== undefined);
+            for (const pluginId of pluginIds) {
+                if (!plugins.has(pluginId)) {
+                    throw missingClientResponsePlugin(pluginId);
+                }
             }
         }
     }

package/dist/common.d.ts

@@ -6,9 +6,19 @@ export type Promisable<T> = T | Promise<T>;
  * @remarks Consumers usually use `$type<T>()` instead of constructing this type
  * directly.
  */
-export type Unchecked<T> = {
+export type Unchecked<T> = Record<number, unknown> & {
     __unchecked__: T;
 };
+/**
+ * Compile-time-only marker used by `$error<T>()` to carry a declared error
+ * response type through route declarations.
+ *
+ * @remarks Consumers usually use `$error<T>()` instead of constructing this
+ * type directly.
+ */
+export type UncheckedError<T> = {
+    __uncheckedError__: T;
+};
 /**
  * Map over all the keys to create a new object.
  *

package/dist/http.js

@@ -30,7 +30,9 @@ function deleteAction(pathOrSchema, schema) {
 }
 export { deleteAction as delete };
 function action(method, pathOrSchema, schema) {
-    const path = typeof pathOrSchema === 'string' ? RoutePattern.parse(pathOrSchema) : undefined;
+    const path = typeof pathOrSchema === 'string'
+        ? RoutePattern.parse(pathOrSchema)
+        : undefined;
     schema ??= typeof pathOrSchema === 'string' ? {} : pathOrSchema;
     const request = ((args = {}) => ({
         schema,

package/dist/response-map.d.ts

@@ -0,0 +1,10 @@
+import type { RouteResponseMap, RouteSchema } from './types/schema.js';
+/** Return true when the response schema is a status-keyed response map. */
+export declare function isResponseMap(response: RouteSchema['response']): response is RouteResponseMap;
+/** Return true when the marker represents a declared error response. */
+export declare function isErrorMarker(marker: unknown): boolean;
+/** Return true when the marker represents a success response. */
+export declare function isSuccessMarker(marker: unknown): boolean;
+/** Find the default success status for a direct handler result. */
+export declare function getResponseMapPluginIds(responseMap: RouteResponseMap): string[];
+export declare function getDefaultSuccessStatus(responseMap: RouteResponseMap): number;

package/dist/response-map.js

@@ -0,0 +1,32 @@
+import { getResponsePluginMarkerId, responsePluginMarker, } from './response.js';
+import { $error } from './type.js';
+/** Return true when the response schema is a status-keyed response map. */
+export function isResponseMap(response) {
+    return (typeof response === 'object' &&
+        response !== null &&
+        !(responsePluginMarker in response));
+}
+/** Return true when the marker represents a declared error response. */
+export function isErrorMarker(marker) {
+    return marker === $error.symbol;
+}
+/** Return true when the marker represents a success response. */
+export function isSuccessMarker(marker) {
+    return marker !== undefined && !isErrorMarker(marker);
+}
+/** Find the default success status for a direct handler result. */
+export function getResponseMapPluginIds(responseMap) {
+    return Object.values(responseMap).flatMap(marker => {
+        const pluginId = getResponsePluginMarkerId(marker);
+        return pluginId ? [pluginId] : [];
+    });
+}
+export function getDefaultSuccessStatus(responseMap) {
+    for (const key of Object.keys(responseMap)) {
+        const marker = responseMap[Number(key)];
+        if (isSuccessMarker(marker)) {
+            return Number(key);
+        }
+    }
+    return 200;
+}

package/dist/response.d.ts

@@ -1,15 +1,17 @@
 import type { Promisable } from './common.js';
 import type { RouteRequest } from './types/request.js';
 /** Runtime key carried by response plugin markers. */
-export declare const responsePluginMarkerSymbol: unique symbol;
+export declare const responsePluginMarker: unique symbol;
 /**
  * Compile-time response marker handled by a client/router response plugin pair.
  *
  * @remarks `TClient` is the value returned by generated client action
  * functions. `TRouter` is the non-`Response` value accepted from route handlers.
+ * Plugin markers may be used directly as an action response or as success
+ * entries in a status-keyed response map.
  */
-export type ResponsePluginMarker<TClient, TRouter = TClient, TId extends string = string> = {
-    readonly [responsePluginMarkerSymbol]: {
+export type ResponsePluginMarker<TClient, TRouter = TClient, TId extends string = string> = Record<number, unknown> & {
+    readonly [responsePluginMarker]: {
         readonly id: TId;
         readonly client: TClient;
         readonly router: TRouter;

package/dist/response.js

@@ -1,9 +1,9 @@
 /** Runtime key carried by response plugin markers. */
-export const responsePluginMarkerSymbol = Symbol.for('rouzer.response-plugin');
+export const responsePluginMarker = Symbol.for('rouzer.response-plugin');
 /** Create a response marker for a response plugin. */
 export function createResponsePluginMarker(id) {
     return {
-        [responsePluginMarkerSymbol]: {
+        [responsePluginMarker]: {
             id,
             client: undefined,
             router: undefined,
@@ -13,14 +13,12 @@ export function createResponsePluginMarker(id) {
 /** Get the response plugin id from a plugin marker, if present. */
 export function getResponsePluginMarkerId(value) {
     return isResponsePluginMarker(value)
-        ? value[responsePluginMarkerSymbol].id
+        ? value[responsePluginMarker].id
         : undefined;
 }
 /** Return true when a route response marker is handled by a response plugin. */
 export function isResponsePluginMarker(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        responsePluginMarkerSymbol in value);
+    return (typeof value === 'object' && value !== null && responsePluginMarker in value);
 }
 /** Create a plugin lookup map and reject duplicate plugin ids. */
 export function createResponsePluginMap(plugins = [], label = 'response') {

package/dist/server/router.js

@@ -4,6 +4,7 @@ import { chain, MiddlewareChain, } from 'alien-middleware';
 import * as z from 'zod';
 import { mapValues } from '../common.js';
 import { createResponsePluginMap, getResponsePluginMarkerId, } from '../response.js';
+import { getDefaultSuccessStatus, getResponseMapPluginIds, isErrorMarker, isResponseMap, } from '../response-map.js';
 export { chain };
 // Internal prototype for the router instance.
 class RouterObject extends MiddlewareChain {
@@ -109,6 +110,11 @@ class RouterObject extends MiddlewareChain {
                         return httpClientError(error, 'Invalid request body', config);
                     }
                 }
+                if (isResponseMap(schema.response)) {
+                    ;
+                    context.error = createResponseHelper(schema.response, request, responsePlugins, true);
+                    context.success = createResponseHelper(schema.response, request, responsePlugins, false);
+                }
                 const result = await handler(context);
                 addDebugHeaders?.(context, route);
                 if (result instanceof Response) {
@@ -125,6 +131,10 @@ class RouterObject extends MiddlewareChain {
                         request,
                     });
                 }
+                if (isResponseMap(schema.response)) {
+                    const status = getDefaultSuccessStatus(schema.response);
+                    return encodeResponseMapResult(schema.response, status, result, request, responsePlugins);
+                }
                 return Response.json(result);
             }
         });
@@ -169,9 +179,13 @@ function flattenRoutes(tree, handlers, prefix, debug) {
 }
 function validateRouterResponsePlugins(routes, plugins) {
     for (const route of routes) {
-        const pluginId = getResponsePluginMarkerId(route.schema.response);
-        if (pluginId && !plugins.has(pluginId)) {
-            throw missingRouterResponsePlugin(pluginId);
+        const pluginIds = isResponseMap(route.schema.response)
+            ? getResponseMapPluginIds(route.schema.response)
+            : [getResponsePluginMarkerId(route.schema.response)].filter(pluginId => pluginId !== undefined);
+        for (const pluginId of pluginIds) {
+            if (!plugins.has(pluginId)) {
+                throw missingRouterResponsePlugin(pluginId);
+            }
         }
     }
 }
@@ -278,3 +292,39 @@ function createOriginPattern(origin) {
     }
     return new ExactPattern(origin);
 }
+/** Create `ctx.error(status, body)` or `ctx.success(status, body)`. */
+function createResponseHelper(responseMap, request, responsePlugins, error) {
+    return (status, body) => {
+        const marker = responseMap[status];
+        if (!marker || isErrorMarker(marker) !== error) {
+            throw new Error(`Undeclared ${error ? 'error' : 'success'} response status: ${status}`);
+        }
+        return encodeResponseMapResult(responseMap, status, body, request, responsePlugins);
+    };
+}
+async function encodeResponseMapResult(responseMap, status, value, request, responsePlugins) {
+    const marker = responseMap[status];
+    if (!marker) {
+        throw new Error(`Undeclared response status: ${status}`);
+    }
+    if (isErrorMarker(marker)) {
+        return Response.json(value, { status });
+    }
+    const pluginId = getResponsePluginMarkerId(marker);
+    if (!pluginId) {
+        return Response.json(value, { status });
+    }
+    const plugin = responsePlugins.get(pluginId);
+    if (!plugin) {
+        throw missingRouterResponsePlugin(pluginId);
+    }
+    const response = await plugin.encode(value, {
+        marker: marker,
+        request,
+    });
+    return new Response(response.body, {
+        status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}

package/dist/type.d.ts

@@ -1,10 +1,13 @@
-import type { Unchecked } from './common.js';
+import type { Unchecked, UncheckedError } from './common.js';
 /**
  * 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
@@ -20,3 +23,29 @@ export declare function $type<T>(): Unchecked<T>;
 export declare namespace $type {
     var 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 declare function $error<T>(): UncheckedError<T>;
+export declare namespace $error {
+    var symbol: symbol;
+}

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/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/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)`
@@ -175,6 +217,8 @@ requests with an `Origin` header.
   request factory contains the full path you want to call
 - `client.json(action.request(args))` for parsed JSON and default non-2xx
   throwing
+- response-map support for generated client action functions, returning
+  `[error, value, status]` tuples for declared statuses
 - 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
@@ -205,9 +249,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
@@ -247,9 +291,64 @@ const json = await client.json(
 )
 ```
 
-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.
+Response maps and response plugins are applied by generated client action
+functions. For longhand calls to mapped or plugin-backed routes, use
+`client.request(...)` for the raw `Response` and decode the response yourself.
+
+### Handle declared error responses
+
+Use `$error<T>()` inside a response map when an error status is part of the route
+contract:
+
+```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({
+  path: { id: 'missing' },
+})
+
+if (status === 404) {
+  console.log(error.message)
+} else {
+  console.log(user.name)
+}
+```
+
+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
 
@@ -322,8 +421,8 @@ 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`.
+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`
@@ -390,6 +489,8 @@ await client.profiles.update({
   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,10 +501,13 @@ 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`.

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 }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rouzer",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -52,6 +52,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsgo -b tsconfig.json",
+    "format": "prettier --write src test",
     "test": "vitest run"
   }
 }