rouzer 3.1.0 → 4.0.0

package/README.md

@@ -2,18 +2,19 @@
 
 Rouzer lets you declare an HTTP route tree once and share its TypeScript types
 and Zod validation between a Hattip-compatible server and a typed fetch client.
+The client is always created from that route tree.
 
 ## 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 +25,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 +34,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+
@@ -43,7 +46,7 @@ Consider something else if:
 - Zod v4 or newer
 - a Hattip adapter when using `createRouter(...)`
 - a Fetch API implementation when using `createClient(...)`
-- an absolute `baseURL` for generated client URLs
+- an absolute `baseURL` and shared `routes` tree for generated client URLs
 
 ## Installation
 
@@ -55,7 +58,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'
 ```
 
@@ -99,9 +102,52 @@ const { message } = await client.hello({
 })
 ```
 
-`handler` can be mounted with any Hattip adapter. Client action calls validate
-route arguments before `fetch`; server handlers validate matched path, query,
-headers, and JSON bodies before your handler runs.
+`handler` can be mounted with any Hattip adapter. Generated client action calls
+validate 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
 
@@ -141,6 +187,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

@@ -2,7 +2,6 @@ import { Promisable } from '../common.js';
 import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js';
 import { type ClientResponsePlugin } from '../response.js';
 import type { RouteArgs } from '../types/args.js';
-import type { RouteRequest } from '../types/request.js';
 import type { InferRouteResponse } from '../types/response.js';
 import type { RouteSchema } from '../types/schema.js';
 /** Client type inferred from an HTTP route tree passed to `createClient`. */
@@ -10,9 +9,8 @@ export type RouzerClient<TRoutes extends HttpRouteTree = Record<string, never>>
 /**
  * Create a typed fetch client for an HTTP route tree.
  *
- * @remarks The returned client always includes `request(...)` for raw responses
- * and `json(...)` for parsed JSON. Passing `routes` also mirrors the resource
- * tree and attaches direct action functions such as `client.users.list(...)`.
+ * @remarks The returned client mirrors the resource tree and attaches direct
+ * action functions such as `client.users.list(...)`.
  */
 export declare function createClient<TRoutes extends HttpRouteTree = Record<string, never>>(config: {
     /**
@@ -38,22 +36,22 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
      * await client.users.list({ query: { page: 1 } })
      * ```
      */
-    routes?: TRoutes;
+    routes: TRoutes;
     /** Response codec plugins used by generated action functions. */
     plugins?: readonly ClientResponsePlugin[];
     /**
-     * Custom handler for non-2xx responses from `.json()` and generated response
-     * helpers.
+     * Custom handler for non-2xx responses from generated client action
+     * functions.
      *
-     * @remarks When provided, the return value is returned from the response
-     * helper as-is; Rouzer does not automatically parse a `Response` returned by
-     * this hook.
+     * @remarks When provided, the return value is returned from the client action
+     * as-is; Rouzer does not automatically parse a `Response` returned by this
+     * hook.
      */
     onJsonError?: (response: Response) => Promisable<unknown>;
     /** Custom `fetch` implementation to use for requests. */
     fetch?: typeof globalThis.fetch;
 }): ClientTree<TRoutes, ""> & {
-    config: {
+    clientConfig: {
         /**
          * Absolute base URL used for generated request URLs.
          *
@@ -77,25 +75,21 @@ export declare function createClient<TRoutes extends HttpRouteTree = Record<stri
          * await client.users.list({ query: { page: 1 } })
          * ```
          */
-        routes?: TRoutes;
+        routes: TRoutes;
         /** Response codec plugins used by generated action functions. */
         plugins?: readonly ClientResponsePlugin[];
         /**
-         * Custom handler for non-2xx responses from `.json()` and generated response
-         * helpers.
+         * Custom handler for non-2xx responses from generated client action
+         * functions.
          *
-         * @remarks When provided, the return value is returned from the response
-         * helper as-is; Rouzer does not automatically parse a `Response` returned by
-         * this hook.
+         * @remarks When provided, the return value is returned from the client action
+         * as-is; Rouzer does not automatically parse a `Response` returned by this
+         * hook.
          */
         onJsonError?: (response: Response) => Promisable<unknown>;
         /** Custom `fetch` implementation to use for requests. */
         fetch?: typeof globalThis.fetch;
     };
-    request: <T extends RouteRequest>({ path: pathBuilder, method, args, schema, }: T) => Promise<Response & {
-        json(): Promise<T['$result']>;
-    }>;
-    json: <T extends RouteRequest>(props: T) => Promise<T['$result']>;
 };
 type Join<A extends string, B extends string> = A extends '' ? B : B extends '' ? A : `${A}/${B}`;
 /** Client object shape produced from an HTTP route tree. */
@@ -106,8 +100,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,21 +2,19 @@ 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.
  *
- * @remarks The returned client always includes `request(...)` for raw responses
- * and `json(...)` for parsed JSON. Passing `routes` also mirrors the resource
- * tree and attaches direct action functions such as `client.users.list(...)`.
+ * @remarks The returned client mirrors the resource tree and attaches direct
+ * action functions such as `client.users.list(...)`.
  */
 export function createClient(config) {
     const baseURL = config.baseURL.replace(/\/?$/, '/');
     const defaultHeaders = config.headers && shake(config.headers);
     const fetch = config.fetch ?? globalThis.fetch;
     const responsePlugins = createResponsePluginMap(config.plugins, 'client response');
-    if (config.routes) {
-        validateClientResponsePlugins(config.routes, responsePlugins);
-    }
+    validateClientResponsePlugins(config.routes, responsePlugins);
     async function request({ path: pathBuilder, method, args, schema, }) {
         let { path, query, body, headers, ...init } = args;
         if (schema.path) {
@@ -60,26 +58,48 @@ export function createClient(config) {
             headers: (headers ?? defaultHeaders),
         });
     }
-    async function json(props) {
-        const response = await request(props);
-        if (!response.ok) {
-            return handleResponseError(response, props);
-        }
-        return response.json();
-    }
     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,
             });
         }
@@ -97,12 +117,8 @@ export function createClient(config) {
         throw error;
     }
     return {
-        ...(config.routes
-            ? connectTree(config.routes, '', request, response)
-            : null),
-        config,
-        request,
-        json,
+        ...connectTree(config.routes, '', request, response),
+        clientConfig: config,
     };
 }
 function connectTree(tree, prefix, request, response) {
@@ -133,9 +149,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.d.ts

@@ -1,5 +1,4 @@
 import { RoutePattern } from '@remix-run/route-pattern';
-import type { RouteRequestFactory } from './types/request.js';
 import type { RouteSchema } from './types/schema.js';
 /** HTTP methods supported by Rouzer action declarations. */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -18,8 +17,6 @@ export type HttpAction<P extends string = string, T extends RouteSchema = RouteS
     method: M;
     /** Request validation and optional response type schema. */
     schema: T;
-    /** Low-level request descriptor factory for this action. */
-    request: RouteRequestFactory<T, P>;
 };
 /**
  * Path-scoped namespace in an HTTP route tree.

package/dist/http.js

@@ -30,14 +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,
-        path: path ?? RoutePattern.parse(''),
-        method,
-        args,
-        $result: undefined,
-    }));
-    return { kind: 'action', path, method, schema, request };
+    return { kind: 'action', path, method, 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,19 @@
 import type { Promisable } from './common.js';
-import type { RouteRequest } from './types/request.js';
+import type { RoutePattern } from '@remix-run/route-pattern';
+import type { RouteArgs } from './types/args.js';
+import type { RouteSchema } from './types/schema.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;
@@ -22,9 +26,16 @@ export type ClientResponsePlugin = {
     /** Decode a successful `Response` into the client action result. */
     decode(response: Response, context: {
         marker: ResponsePluginMarker<any, any>;
-        request: RouteRequest;
+        request: ClientResponsePluginRequest;
     }): Promisable<unknown>;
 };
+/** Request metadata passed to client response plugins. */
+export type ClientResponsePluginRequest = {
+    schema: RouteSchema;
+    path: RoutePattern;
+    method: string;
+    args: RouteArgs;
+};
 /** Router-side response plugin used by `createRouter({ plugins })`. */
 export type RouterResponsePlugin = {
     /** Stable response codec id matched against route response markers. */

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