ts-procedures 5.16.0 → 6.0.1

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:
@@ -158,7 +281,7 @@ import { DocRegistry } from 'ts-procedures/http-docs'
 const docs = new DocRegistry({
   basePath: '/api',
   headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-  errors: DocRegistry.defaultErrors(),
+  errors: appErrors,  // your ErrorTaxonomy — auto-converted to ErrorDocs, framework defaults merged
 })
   .from(rpcBuilder)
   .from(apiBuilder)
@@ -167,6 +290,16 @@ const docs = new DocRegistry({
 app.get('/docs', (c) => c.json(docs.toJSON()))
 ```
 
+`errors` accepts either your runtime `ErrorTaxonomy` (the common case) or a raw `ErrorDoc[]`. Framework defaults (`ProcedureError`, `ProcedureValidationError`, `ProcedureYieldValidationError`, `ProcedureRegistrationError`) are merged in automatically and deduped — user entries win when keys overlap. Pass `includeDefaults: false` to opt out.
+
+For errors that aren't in your taxonomy (middleware-level, infrastructure, doc-only meta errors), use the fluent `.documentError()` method:
+
+```typescript
+const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
+  .from(rpcBuilder)
+  .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'too many requests' })
+```
+
 `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.
 
 The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).

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(