ts-procedures 5.16.0 → 6.0.0

package/build/implementations/http/route-errors.test.js

@@ -0,0 +1,140 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest';
+import { Type } from 'typebox';
+import { Procedures } from '../../index.js';
+import { HonoAPIAppBuilder } from './hono-api/index.js';
+import { HonoRPCAppBuilder } from './hono-rpc/index.js';
+import { ExpressRPCAppBuilder } from './express-rpc/index.js';
+import { HonoStreamAppBuilder } from './hono-stream/index.js';
+import { DocRegistry } from './doc-registry.js';
+import { defineErrorTaxonomy } from './error-taxonomy.js';
+class UseCaseError extends Error {
+    externalMsg;
+    constructor(externalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+class AuthError extends Error {
+}
+const appErrors = defineErrorTaxonomy({
+    UseCaseError: { class: UseCaseError, statusCode: 422 },
+    AuthError: { class: AuthError, statusCode: 401 },
+});
+describe('per-route errors declaration', () => {
+    test('hono-api copies config.errors onto the route doc', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError', 'AuthError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('hono-api route doc omits errors when not declared', () => {
+        const API = Procedures();
+        API.Create('Health', { path: '/health', method: 'get', schema: { returnType: Type.Object({}) } }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toBeUndefined();
+    });
+    test('hono-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['UseCaseError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new HonoRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError']);
+    });
+    test('express-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['AuthError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new ExpressRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('hono-stream copies config.errors onto the route doc', () => {
+        const Stream = Procedures();
+        Stream.CreateStream('Watch', { scope: 'watch', version: 1, errors: ['AuthError'] }, async function* () {
+            yield { ok: true };
+        });
+        const builder = new HonoStreamAppBuilder().register(Stream, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('compile-time: errors typed as keyof taxonomy narrows valid keys', () => {
+        const _valid = ['UseCaseError', 'AuthError'];
+        // @ts-expect-error - 'NotRegistered' is not in the taxonomy
+        const _invalid = ['NotRegistered'];
+        expect(_valid).toBeDefined();
+        expect(_invalid).toBeDefined();
+    });
+});
+describe('DocRegistry.fromTaxonomy', () => {
+    test('seeds envelope errors from the taxonomy + framework defaults', () => {
+        const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' });
+        const envelope = registry.toJSON();
+        const names = envelope.errors.map((e) => e.name);
+        expect(names).toContain('UseCaseError');
+        expect(names).toContain('AuthError');
+        expect(names).toContain('ProcedureValidationError');
+        expect(names).toContain('ProcedureRegistrationError');
+        expect(envelope.basePath).toBe('/api');
+    });
+    test('includeDefaults: false omits framework entries', () => {
+        const registry = DocRegistry.fromTaxonomy(appErrors, { includeDefaults: false });
+        const names = registry.toJSON().errors.map((e) => e.name);
+        expect(names).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('user entry with same key as default takes precedence (deduped)', () => {
+        const overridden = defineErrorTaxonomy({
+            ProcedureError: {
+                class: Error,
+                statusCode: 418,
+                description: 'custom override',
+            },
+        });
+        const envelope = DocRegistry.fromTaxonomy(overridden).toJSON();
+        const proc = envelope.errors.find((e) => e.name === 'ProcedureError');
+        expect(proc?.statusCode).toBe(418);
+        expect(proc?.description).toBe('custom override');
+        // no duplicates
+        const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length;
+        expect(count).toBe(1);
+    });
+    test('registered route errors survive DocRegistry composition', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const app = new HonoAPIAppBuilder().register(API, () => ({}));
+        app.build();
+        const envelope = DocRegistry.fromTaxonomy(appErrors).from(app).toJSON();
+        const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser');
+        expect(route?.errors).toEqual(['UseCaseError']);
+    });
+});
+//# sourceMappingURL=route-errors.test.js.map

package/build/implementations/http/route-errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-errors.test.js","sourceRoot":"","sources":["../../../src/implementations/http/route-errors.test.ts"],"names":[],"mappings":"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"}

package/build/implementations/types.d.ts

@@ -1,7 +1,18 @@
 import { Procedures } from '../index.js';
-export interface RPCConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
+ * (unconstrained). Narrow it by passing `keyof typeof yourTaxonomy & string`
+ * to get compile-time typo protection on `errors`.
+ */
+export interface RPCConfig<TErrorKey extends string = string> {
     scope: string | string[];
     version: number;
+    /**
+     * Taxonomy keys for errors this procedure may emit. Purely informational at
+     * runtime (nothing is rejected), but populates the DocEnvelope per-route
+     * error list so generated clients can narrow their catch types.
+     */
+    errors?: TErrorKey[];
 }
 export type FactoryItem<C> = {
     factory: ReturnType<typeof Procedures<C, RPCConfig>>;
@@ -16,10 +27,17 @@ export interface RPCHttpRouteDoc extends RPCConfig {
         body?: Record<string, unknown>;
         response?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit. */
+    errors?: string[];
 }
 export type StreamMode = 'sse' | 'text';
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head';
-export interface APIConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`.
+ * Narrow it by passing `keyof typeof yourTaxonomy & string` for compile-time
+ * typo protection on `errors`.
+ */
+export interface APIConfig<TErrorKey extends string = string> {
     /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
     path: string;
     /** HTTP method for this endpoint */
@@ -28,6 +46,12 @@ export interface APIConfig {
     successStatus?: number;
     /** Optional scope for grouping API routes in generated client files */
     scope?: string;
+    /**
+     * Taxonomy keys for errors this procedure may emit. Purely informational at
+     * runtime (nothing is rejected), but populates the DocEnvelope per-route
+     * error list so generated clients can narrow their catch types.
+     */
+    errors?: TErrorKey[];
 }
 export interface APIHttpRouteDoc extends APIConfig {
     kind: 'api';
@@ -41,6 +65,8 @@ export interface APIHttpRouteDoc extends APIConfig {
         headers?: Record<string, unknown>;
         response?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit. */
+    errors?: string[];
 }
 /**
  * Constrains schema.input channel names to valid HTTP input sources.
@@ -76,6 +102,8 @@ export interface StreamHttpRouteDoc extends RPCConfig {
         yieldType?: Record<string, unknown>;
         returnType?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit (pre-stream only). */
+    errors?: string[];
 }
 /**
  * Extracts the TContext type from a Procedures factory return type.

package/docs/client-and-codegen.md

@@ -20,14 +20,14 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 
 **Step 3 — Use the client:**
 
+The recommended entrypoint is the generated `create${Service}Client` factory. It calls `createClient` under the hood with the generated error registry pre-wired, so non-2xx responses arrive as typed class instances you can catch with `instanceof`.
+
 ```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createApiBindings, Api } from './generated/api'
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated/api'
 
-const client = createClient({
+const api = createApiClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
-  scopes: createApiBindings,
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -36,11 +36,32 @@ const client = createClient({
   },
 })
 
-// Fully typed — params and response inferred from server schemas
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
+try {
+  const user = await api.users.GetUser({ pathParams: { id: '123' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body, err.status, err.procedureName, err.scope all typed
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any service error (shared base class)
+  }
+}
 
-// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.ProcedureError, etc.
-// Pass --service-name <Name> to rename `Api` → `<Name>` (factory becomes create<Name>Bindings).
+// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.UseCaseError, etc.
+// Pass --service-name <Name> to rename `Api` → `<Name>` throughout.
+```
+
+For advanced control (sharing one `ClientInstance` across services, composing with a custom registry), use `createClient` + `create${Service}Bindings` directly:
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createApiBindings, ApiErrors } from './generated/api'
+
+const api = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  errorRegistry: ApiErrors.ApiErrorRegistry,  // opt in to typed dispatch — omit to get the plain ClientRequestError transport shape
+})
 ```
 
 ## Generated File Structure
@@ -54,8 +75,8 @@ generated/
   notifications.ts   # Types + callables for stream procedures
   _types.ts          # Client type definitions (self-contained mode)
   _client.ts         # Client runtime bundle (self-contained mode)
-  _errors.ts         # Typed error classes + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureErrorUnion)
-  index.ts           # Service namespace (`export namespace ${ServiceName}`) + create${ServiceName}Bindings factory (default: Api / createApiBindings)
+  _errors.ts         # Runtime error classes extending ${ServiceName}ProcedureError + static fromResponse + ${ServiceName}ErrorRegistry + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureError / ApiErrorRegistry / ApiProcedureErrorUnion)
+  index.ts           # Service namespace + create${ServiceName}Bindings (manual wiring) and create${ServiceName}Client (convenience; registry pre-wired). Default: Api / createApiBindings / createApiClient.
 ```
 
 ## CLI Reference
@@ -217,6 +238,68 @@ await client.users.GetUser(
 
 If `RequestMeta` declares required fields, the merged meta (defaults + per-call) must contain them at runtime. TypeScript can't statically verify this across the merge boundary, so supply required fields in `defaults.meta` or per-call `options.meta`.
 
+## Typed Error Handling
+
+Non-2xx responses whose body has a `name` field matching a registry key are dispatched into typed class instances. The generated `_errors.ts` exports:
+
+- A shared base class `${ServiceName}ProcedureError<TBody>` — carries `status`, `procedureName`, `scope`, and `body`. Catch any service error with `instanceof ${ServiceName}Errors.${ServiceName}ProcedureError`.
+- One concrete class per taxonomy entry in the envelope, each with a static `fromResponse(body, meta)` factory.
+- `${ServiceName}ErrorRegistry` — a `{ [name]: ErrorClass }` object consumed by the client's `dispatchTypedError`.
+- `${ServiceName}ProcedureErrorUnion` — a type union of every generated class for annotating catch clauses.
+
+```typescript
+import { createApiClient, ApiErrors } from './generated/api'
+
+const api = createApiClient({ adapter, basePath: '...' })
+
+try {
+  await api.users.GetUser({ pathParams: { id: 'x' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body is typed to UseCaseErrorBody; err.status, err.procedureName, err.scope available
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any generated service error
+  } else if (err instanceof ClientRequestError) {
+    // Transport-level error (unmatched body.name, or non-JSON response)
+  }
+}
+```
+
+### Per-route error narrowing
+
+When a server route declares `errors: ['UseCaseError', 'AuthError']` on its config, the generated scope file emits an `Errors` type union inside that route's namespace:
+
+```typescript
+// Generated scope file:
+export namespace Users {
+  export namespace GetUser {
+    export type Params = { /* ... */ }
+    export type Response = { /* ... */ }
+    export type Errors = ApiErrors.UseCaseError | ApiErrors.AuthError
+  }
+}
+
+// Consumer:
+try { await api.users.GetUser({ pathParams: { id: 'x' } }) }
+catch (err) {
+  const e = err as Users.GetUser.Errors | ClientRequestError   // TS has no typed-throws; manual annotation
+  if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
+}
+```
+
+Route-errors that reference keys missing from `_errors.ts` are filtered out at codegen time so generated code never references undefined types.
+
+### How dispatch works
+
+`src/client/error-dispatch.ts` exports a pure `dispatchTypedError(registry, body, meta)` helper. The client's `call.ts` invokes it on non-2xx responses:
+
+1. If no registry, or body isn't an object with a string `name`, or no registry key matches → returns `null`.
+2. Otherwise calls `registry[body.name].fromResponse(body, meta)` and returns the typed `Error` instance.
+
+When the helper returns `null`, the call falls back to `ClientRequestError` — the plain transport-error shape, used for unmatched names, non-JSON bodies, and when no registry is configured.
+
+Stream endpoints get the same treatment for **pre-stream** errors (thrown before the first yield — e.g. validation or auth). The fetch adapter's `stream()` eagerly parses a JSON body when status is non-2xx and exposes it via `AdapterStreamResponse.errorBody`, which `executeStream` passes through the registry. **Mid-stream** SSE error events continue to flow through `onMidStreamError` on the server and re-throw on the client without registry dispatch.
+
 ## Hooks
 
 Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks run after global ones for a single invocation.
@@ -307,12 +390,22 @@ import { createClient, createFetchAdapter } from './generated/_client'
 import { createClient, createFetchAdapter } from 'ts-procedures/client'
 ```
 
+- **`_client.ts`** also bundles `error-dispatch.ts`, so registry-based typed error dispatch works without importing `ts-procedures/client` at runtime.
+
 ## Type Exports
 
 ```typescript
 // Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+import { createClient, createFetchAdapter, dispatchTypedError } from 'ts-procedures/client'
+import type {
+  ClientAdapter,
+  ClientHooks,
+  TypedStream,
+  ClientInstance,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
+} from 'ts-procedures/client'
 
 // Code Generation
 import { generateClient } from 'ts-procedures/codegen'

package/docs/core.md

@@ -31,7 +31,7 @@ Create(name, config, handler)
 **Returns:**
 - `{ [name]: handler }` - Named export for the handler
 - `procedure` - Generic reference to the handler
-- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
+- `info` - Procedure metadata (name, description, schema, `TExtendedConfig` properties, etc.)
 
 ## Structured Input with schema.input
 
@@ -234,7 +234,8 @@ Create(
   async (ctx, params) => {
     const resource = await db.find(params.id)
     if (!resource) {
-      throw ctx.error(404, 'Resource not found', { id: params.id })
+      // Signature: ctx.error(message: string, meta?: object) => ProcedureError
+      throw ctx.error('Resource not found', { code: 'NOT_FOUND', id: params.id })
     }
     return resource
   },
@@ -249,6 +250,7 @@ Create(
 | ProcedureValidationError | Schema validation failure (params) |
 | ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
 | ProcedureRegistrationError | Invalid schema at registration |
+| `${Service}ProcedureError` (client-side) | Base class for every generated error class on the client — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) |
 
 ### Error Properties
 
@@ -264,6 +266,12 @@ try {
 }
 ```
 
+### Error Taxonomy (HTTP builders)
+
+For structured HTTP error responses, declare an error taxonomy once with `defineErrorTaxonomy` and pass it to any HTTP builder via the `errors` option — handlers `throw` their classes and the builder serializes to the configured status + body. `ctx.error()` continues to work as the ad-hoc ProcedureError path.
+
+The taxonomy also drives typed `catch` blocks on generated clients and per-route error documentation. See [HTTP Integrations → Error Handling](./http-integrations.md#error-handling) for the full contract, and [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) for the client-side surface.
+
 ## Abort Signal
 
 For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
@@ -394,10 +402,11 @@ describe('GetUser', () => {
   })
 
   test('has correct schema', () => {
+    // `info.schema.params` is the JSON Schema derived from the TypeBox
+    // definition above: `Type.Object({ hideName: Type.Optional(Type.Boolean()) })`.
     expect(info.schema.params).toEqual({
       type: 'object',
-      properties: { id: { type: 'string' } },
-      required: ['id'],
+      properties: { hideName: { type: 'boolean' } },
     })
   })
 })
@@ -431,7 +440,7 @@ Defines a procedure.
 **Returns:**
 - `{ [name]: handler }` - Named handler export
 - `procedure` - Generic handler reference
-- `info` - Procedure metareturnType
+- `info` - Procedure metadata (name, description, schema, extended-config properties)
 
 ### Type Exports
 

package/docs/http-integrations.md

@@ -13,7 +13,7 @@ For a full cross-framework comparison (config interfaces, path generation, conte
 | Express RPC | `ts-procedures/express-rpc` | RPC (POST routes) | [README](../src/implementations/http/express-rpc/README.md) |
 | Hono RPC | `ts-procedures/hono-rpc` | RPC (POST routes) | [README](../src/implementations/http/hono-rpc/README.md) |
 | Hono Stream | `ts-procedures/hono-stream` | SSE/text streaming | [README](../src/implementations/http/hono-stream/README.md) |
-| Hono API | `ts-procedures/hono-api` | REST (method-based) | [Below](#hono-api-integration) |
+| Hono API | `ts-procedures/hono-api` | REST (method-based) | [README](../src/implementations/http/hono-api/README.md) |
 
 ## Express RPC
 
@@ -27,7 +27,7 @@ const RPC = Procedures<AppContext, RPCConfig>()
 RPC.Create(
   'GetUser',
   {
-    name: ['users', 'get'],
+    scope: ['users', 'get'],
     version: 1,
     schema: {
       params: Type.Object({ id: Type.String() }),
@@ -44,7 +44,7 @@ const app = new ExpressRPCAppBuilder()
   .build()
 
 app.listen(3000)
-// Route created: POST /rpc/users/get/1
+// Route created: POST /users/get/get-user/1
 ```
 
 See the [Express RPC Integration Guide](../src/implementations/http/express-rpc/README.md) for complete setup including lifecycle hooks, error handling, and route documentation.
@@ -139,7 +139,7 @@ API.Create('CreateUser', {
   return await createUser(body)
 })
 
-const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
   .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
   .build()
 
@@ -148,6 +148,129 @@ const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
 // POST /api/users      -> 201
 ```
 
+See the [Hono API Integration Guide](../src/implementations/http/hono-api/README.md) for the full surface: `schema.input` channels, query parsing, success-status defaults, and error handling.
+
+## Error Handling
+
+Every HTTP builder supports **two peer error-handling modes** — neither is "primary" or "fallback". Pick whichever fits your app, or combine them.
+
+| Mode | When to pick | What you configure |
+|---|---|---|
+| **Declarative — the taxonomy** | Structured errors, typed client dispatch, DocEnvelope integration | `errors` (taxonomy) + optional `unknownError` |
+| **Imperative — the `onError` callback** | Simple apps, gradual migration, full response control, no typed client contract | `onError` only |
+
+Both modes also expose `onRequestError` — a cross-cutting observer for logging, tracing, and metrics that fires for every error regardless of dispatch outcome.
+
+### Declarative — the taxonomy
+
+```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string, readonly internalMsg: string) {
+    super(externalMsg); this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+const appErrors = defineErrorTaxonomy({
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ message: err.externalMsg }),        // `name: 'UseCaseError'` auto-injected
+    onCatch: (err) => logger.error(err.internalMsg),
+  },
+  // 3rd-party errors without a subclassable type use `match:` instead of `class:`.
+  MongoDuplicateKey: {
+    match: (err): err is Error =>
+      err instanceof Error && err.name === 'MongoServerError' && (err as any).code === 11000,
+    statusCode: 409,
+    toResponse: () => ({ message: 'Resource already exists' }),
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => logger.error({ procedure: procedure.name, err }),
+  },
+}).register(API, /* ... */).build()
+```
+
+The identical `errors` + `unknownError` shape plugs into `HonoRPCAppBuilder`, `ExpressRPCAppBuilder`, and `HonoStreamAppBuilder` (pre-stream only — mid-stream uses `onMidStreamError`).
+
+### Imperative — the `onError` callback
+
+For apps that don't need typed client dispatch or declarative docs, configure `onError` directly and handle every error in one place:
+
+```typescript
+new HonoAPIAppBuilder({
+  onError: (procedure, c, error) => {
+    logger.error(`[${procedure.name}]`, error)
+    return c.json({ error: error.message ?? 'unknown error' }, 500)
+  },
+}).register(API, /* ... */).build()
+```
+
+(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md).)
+
+Signatures (differ by framework):
+
+| Builder | `onError` signature |
+|---|---|
+| `HonoAPIAppBuilder`, `HonoRPCAppBuilder` | `(procedure, c: Context, error) => Response \| Promise<Response>` |
+| `ExpressRPCAppBuilder` | `(procedure, req, res, error) => void` (write to `res`) |
+| `HonoStreamAppBuilder` | `(procedure, c: Context, error) => Response \| Promise<Response>` — pre-stream only |
+
+Picking between modes isn't irreversible: you can start with `onError`, migrate chunks to the taxonomy as your error model stabilizes, and leave the rest in `onError`. Both modes coexist in the dispatch order below.
+
+### Per-route error narrowing (taxonomy mode)
+
+`APIConfig` and `RPCConfig` are generic over a `TErrorKey extends string` parameter so you can declare which errors a specific route may emit:
+
+```typescript
+import type { APIConfig } from 'ts-procedures/http'
+
+type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+const API = Procedures<Ctx, MyAPIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  errors: ['UseCaseError'],   // typo-checked against the taxonomy keys
+  schema: { /* ... */ },
+}, /* handler */)
+```
+
+These per-route declarations flow into the DocEnvelope and drive typed `catch` blocks on generated clients — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling).
+
+### Cross-cutting observability — `onRequestError`
+
+`onRequestError` fires for every caught error, **before** dispatch. It's an observer — it can't mutate the response. Use it for APM, distributed tracing, custom logging, or metrics where you want one hook that sees every error regardless of which mode dispatched it.
+
+```typescript
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  onRequestError: async ({ err, procedure, raw }) => {
+    sentry.captureException(err, { procedure: procedure.name })
+  },
+})
+```
+
+The observer is awaited before the response is sent, and any error it throws is swallowed (logged to the console) so a broken instrumentation hook can't corrupt the primary flow.
+
+### Dispatch order inside each builder's catch block
+
+1. **`onRequestError`** (observer) — awaited, can't alter dispatch or response
+2. **`errors` taxonomy** — user entries checked, then framework defaults, then `unknownError`
+3. **`onError` callback** — imperative handler receives anything the taxonomy didn't match
+4. **Hard default** — `{ error: message }` at status 500 (produced only when nothing above handled the error)
+
+Configuring only the taxonomy, only `onError`, both, or neither are all valid. When neither is configured the builder goes straight from step 1 to step 4.
+
 ## DocRegistry — Composing Docs from Multiple Builders
 
 Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
@@ -169,6 +292,14 @@ app.get('/docs', (c) => c.json(docs.toJSON()))
 
 `from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
 
+`DocRegistry.fromTaxonomy(taxonomy, config?)` is a convenience constructor that seeds `envelope.errors` from your taxonomy plus framework defaults in one call (deduped — your entries win when keys overlap):
+
+```typescript
+const docs = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+  .from(rpcBuilder)
+  .from(apiBuilder)
+```
+
 The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
 
 ## Type Exports

package/docs/streaming.md

@@ -168,7 +168,9 @@ For the built-in Hono streaming integration, see the [Hono Stream README](../src
 
 ## Stream Errors
 
-Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)):
+Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)).
+
+For HTTP stream endpoints, pre-stream errors (validation, context resolution, anything thrown before the first yield) go through the same two peer error-handling modes as every other HTTP builder — either the declarative `errors` / `unknownError` taxonomy (from `defineErrorTaxonomy`) or the imperative `onError` callback on `HonoStreamAppBuilder`. Cross-cutting `onRequestError` observer fires for every pre-stream error. See [HTTP Integrations → Error Handling](./http-integrations.md#error-handling) for the full contract. Mid-stream errors (thrown after the first yield) still flow through `onMidStreamError` and are surfaced to the client as SSE error events — the HTTP status is already committed once streaming begins, so mid-stream is outside the peer error modes.
 
 ```typescript
 const { StreamWithErrors } = CreateStream(