ts-procedures 5.16.0 → 6.0.0

package/src/implementations/http/hono-rpc/error-taxonomy.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test, vi } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import { RPCConfig } from '../../types.js'
+import { HonoRPCAppBuilder, defineErrorTaxonomy } from './index.js'
+
+class UseCaseError extends Error {
+  constructor(
+    readonly externalMsg: string,
+    readonly internalMsg: string
+  ) {
+    super(externalMsg)
+    this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+describe('HonoRPCAppBuilder — error taxonomy', () => {
+  test('taxonomy catches user error thrown from RPC handler', async () => {
+    const errors = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new UseCaseError('ext', 'int')
+      }
+    )
+
+    const app = new HonoRPCAppBuilder({ errors }).register(RPC, () => ({})).build()
+    const res = await app.request('/test/boom/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    })
+    expect(res.status).toBe(422)
+    expect(await res.json()).toEqual({ name: 'UseCaseError', message: 'ext' })
+  })
+
+  test('unknownError catches unmapped errors', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('db down')
+      }
+    )
+    const app = new HonoRPCAppBuilder({
+      unknownError: { statusCode: 503, toResponse: () => ({ name: 'ServiceUnavailable' }) },
+    })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(res.status).toBe(503)
+    expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
+  })
+
+  test('onError callback runs when taxonomy does not match', async () => {
+    const onError = vi.fn(async (_p: any, c: any) => c.json({ legacy: true }, 418))
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('legacy')
+      }
+    )
+    const app = new HonoRPCAppBuilder({ onError }).register(RPC, () => ({})).build()
+    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(res.status).toBe(418)
+    expect(onError).toHaveBeenCalledOnce()
+  })
+})

package/src/implementations/http/hono-rpc/index.ts

@@ -8,10 +8,19 @@ import {
   RPCConfig,
   RPCHttpRouteDoc,
 } from '../../types.js'
+import {
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  defineErrorTaxonomy,
+  resolveErrorResponse,
+} from '../error-taxonomy.js'
 import { castArray } from 'es-toolkit/compat'
 import { HonoFactoryItem } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
+export { defineErrorTaxonomy }
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
 
 export type HonoRPCAppBuilderConfig = {
   /**
@@ -25,16 +34,39 @@ export type HonoRPCAppBuilderConfig = {
   onRequestEnd?: (c: Context) => void
   onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
   /**
-   * Error handler called when a procedure throws an error.
-   * @param procedure
-   * @param c
-   * @param error
+   * Declarative error-to-response mapping (one of the two peer error modes).
+   * See hono-api for the full taxonomy contract. User entries take precedence
+   * over the framework default taxonomy.
+   */
+  errors?: ErrorTaxonomy
+  /** Fallback serializer for errors not matched by the taxonomy. */
+  unknownError?: UnknownErrorConfig
+  /**
+   * Imperative error callback — the other peer error mode. Receives every
+   * error directly and returns the HTTP response. Use this when you want full
+   * control over the response shape, or alongside `errors` for the tail of
+   * errors the taxonomy doesn't cover.
    */
   onError?: (
     procedure: TProcedureRegistration,
     c: Context,
     error: Error
   ) => Response | Promise<Response>
+  /**
+   * Cross-cutting observer — fires for every caught error, BEFORE dispatch.
+   * Awaited. Cannot mutate the response. Intended for logging, tracing, and
+   * metrics. Thrown errors inside the observer are swallowed and logged.
+   */
+  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
+}
+
+/**
+ * Context passed to the `onRequestError` observer.
+ */
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: TProcedureRegistration
+  raw: Context
 }
 
 /**
@@ -80,11 +112,13 @@ export class HonoRPCAppBuilder {
 
   /**
    * Generates the RPC route path based on the RPC configuration.
-   * The RPCConfig name can be a string or an array of strings to form nested paths.
+   * `RPCConfig.scope` can be a string or an array of strings to form nested paths.
    *
    * Example
-   *  name: ['string', 'string-string', 'string']
-   *  path: /string/string-string/string/version
+   *  name:  'GetUser'
+   *  scope: ['users', 'profile']
+   *  version: 1
+   *  path: /users/profile/get-user/1
    * @param config
    */
   static makeRPCHttpRoutePath({
@@ -178,10 +212,29 @@ export class HonoRPCAppBuilder {
             // Hono returns Response objects via c.json()
             return c.json(result)
           } catch (error) {
+            if (this.config?.onRequestError) {
+              try {
+                await this.config.onRequestError({ err: error, procedure, raw: c })
+              } catch (observerErr) {
+                console.error('[ts-procedures hono-rpc] onRequestError threw — swallowed:', observerErr)
+              }
+            }
+            if (this.config?.errors || this.config?.unknownError) {
+              const resolved = resolveErrorResponse({
+                err: error,
+                userTaxonomy: this.config.errors,
+                unknownError: this.config.unknownError,
+                procedure,
+                raw: c,
+              })
+              if (resolved) {
+                await resolved.runOnCatch()
+                return c.json(resolved.body, resolved.statusCode as never)
+              }
+            }
             if (this.config?.onError) {
               return this.config.onError(procedure, c, error as Error)
             }
-            // Default error handling
             return c.json({ error: (error as Error).message }, 500)
           }
         })
@@ -215,7 +268,7 @@ export class HonoRPCAppBuilder {
       jsonSchema.response = config.schema.returnType
     }
 
-    const base = {
+    const base: RPCHttpRouteDoc = {
       kind: 'rpc' as const,
       name: procedure.name,
       version: config.version,
@@ -224,6 +277,9 @@ export class HonoRPCAppBuilder {
       method,
       jsonSchema,
     }
+    if (config.errors && config.errors.length > 0) {
+      base.errors = [...config.errors]
+    }
     let extendedDoc: object = {}
 
     if (extendProcedureDoc) {

package/src/implementations/http/hono-stream/README.md

@@ -200,8 +200,11 @@ interface HonoStreamAppBuilderConfig<TErrorData = unknown> {
   onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
 
-  // Error handling callbacks (see Error Handling section)
-  onPreStreamError?: (procedure, c, error: ProcedureValidationError | Error) => Response | Promise<Response>
+  // Error handling (see Error Handling section)
+  errors?: ErrorTaxonomy
+  unknownError?: UnknownErrorConfig
+  onError?: (procedure, c, error: ProcedureValidationError | Error) => Response | Promise<Response>
+  onRequestError?: (ctx) => void | Promise<void>
   onMidStreamError?: (procedure, c, error) => MidStreamErrorResult<TErrorData> | undefined
 }
 ```
@@ -253,34 +256,27 @@ This design allows for:
 
 Streaming has two distinct error phases with different semantics:
 
-| Phase | When | Response Type | Callback |
-|-------|------|---------------|----------|
-| **Pre-stream** | Validation, auth, context resolution | HTTP Response (400/500) | `onPreStreamError` |
-| **Mid-stream** | Generator throws during iteration | Value written to stream | `onMidStreamError` |
+| Phase | When | Handling |
+|-------|------|---------|
+| **Pre-stream** | Validation, auth, context resolution | Declarative taxonomy via `errors` + `unknownError` — same shape as all other HTTP builders |
+| **Mid-stream** | Generator throws during iteration | `onMidStreamError` — writes a value into the open stream (status is already committed) |
 
-### Pre-Stream Errors (`onPreStreamError`)
-
-Errors that occur **before** the stream starts (validation failures, context resolution errors). The `error` parameter is typed as `ProcedureValidationError | Error`, allowing `instanceof` narrowing. The return value **IS** used as the HTTP response:
+### Pre-Stream — Error Taxonomy
 
 ```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/hono-stream'
+
 const builder = new HonoStreamAppBuilder({
-  onPreStreamError: (procedure, c, error) => {
-    if (error instanceof ProcedureValidationError) {
-      return c.json({
-        error: 'Invalid parameters',
-        details: error.errors,
-        procedure: procedure.name,
-      }, 400)
-    }
-    return c.json({ error: error.message }, 500)
-  },
+  errors: defineErrorTaxonomy({
+    AuthError: { class: AuthError, statusCode: 401 },
+  }),
+  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
+  onMidStreamError: (/* ... */) => ({ /* mid-stream only */ }),
 })
-
-// Without handler, returns default JSON response:
-// Status: 400 (validation) or 500 (other)
-// Body: { "error": "Validation error for ProcedureName - ..." }
 ```
 
+Full contract (both peer error modes, `onRequestError` observer, per-route `errors` narrowing): see **[docs/http-integrations.md § Error Handling](../../../../docs/http-integrations.md#error-handling)** — the canonical explanation shared across all four HTTP builders.
+
 ### Mid-Stream Errors (`onMidStreamError`)
 
 Errors that occur **during** streaming (generator throws). Since the stream is already open, HTTP status cannot change. Return `{ data, closeStream? }` — the `data` value is written as the SSE `data:` field content.
@@ -474,12 +470,19 @@ RPC.CreateStream('LongStream', config, async function* (ctx) {
 ```typescript
 import {
   HonoStreamAppBuilder,
+  defineErrorTaxonomy,
+  sse,                   // Helper to attach SSE metadata (event/id/retry) to yielded objects
+} from 'ts-procedures/hono-stream'
+import type {
   HonoStreamAppBuilderConfig, // Generic: HonoStreamAppBuilderConfig<TErrorData = unknown>
   StreamHttpRouteDoc,
   StreamMode,
-  sse,                   // Helper to attach SSE metadata (event/id/retry) to yielded objects
   SSEOptions,            // Type for sse() options: { event?, id?, retry? }
   MidStreamErrorResult,  // Generic: MidStreamErrorResult<TErrorData = unknown>
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  OnRequestErrorContext, // Passed to the onRequestError observer: { err, procedure, raw: Context }
 } from 'ts-procedures/hono-stream'
 ```
 
@@ -522,4 +525,20 @@ onStreamEnd: (procedure, c, streamMode) => { ... }
 
 **New: Generic `TErrorData` parameter** on `HonoStreamAppBuilder` and `MidStreamErrorResult` for type-safe `onMidStreamError` callbacks.
 
-**New: `onPreStreamError` error parameter** typed as `ProcedureValidationError | Error` for `instanceof` narrowing.
+**Breaking: `onPreStreamError` renamed to `onError`** for consistency with the other three HTTP builders. Signature unchanged.
+
+```typescript
+// Before (v5)
+new HonoStreamAppBuilder({
+  onPreStreamError: (proc, c, err) => c.json({ error: err.message }, 400),
+})
+
+// After (v6)
+new HonoStreamAppBuilder({
+  onError: (proc, c, err) => c.json({ error: err.message }, 400),
+})
+```
+
+**Breaking: hard-default status for `ProcedureValidationError` changed from 400 to 500.** Previously, `HonoStreamAppBuilder` special-cased validation errors to 400 when no `errors` / `onError` was configured. v6 drops this inconsistency — the hard default is now 500 across all four builders. To preserve the 400 response, configure the taxonomy (`errors: {}` engages framework defaults) or handle it in `onError`.
+
+**New: `onRequestError` cross-cutting observer.** Fires for every caught pre-stream error, before dispatch. Awaited, cannot mutate the response. Use for logging, tracing, metrics. See [docs/http-integrations.md § Error Handling](../../../../docs/http-integrations.md#error-handling).

package/src/implementations/http/hono-stream/error-taxonomy.test.ts

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test, vi } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import { RPCConfig } from '../../types.js'
+import { HonoStreamAppBuilder, defineErrorTaxonomy } from './index.js'
+
+class AuthError extends Error {
+  constructor(readonly reason: 'unauthenticated' | 'forbidden') {
+    super(reason)
+    this.name = 'AuthError'
+    Object.setPrototypeOf(this, AuthError.prototype)
+  }
+}
+
+describe('HonoStreamAppBuilder — error taxonomy (pre-stream)', () => {
+  test('taxonomy catches errors thrown during context resolution', async () => {
+    const errors = defineErrorTaxonomy({
+      AuthError: {
+        class: AuthError,
+        statusCode: 401,
+        toResponse: (err) => ({ name: 'AuthError', reason: err.reason }),
+      },
+    })
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'ok' }
+    })
+
+    const app = new HonoStreamAppBuilder({ errors })
+      .register(RPC, () => {
+        throw new AuthError('forbidden')
+      })
+      .build()
+
+    const res = await app.request('/test/stream/1')
+    expect(res.status).toBe(401)
+    expect(await res.json()).toEqual({ name: 'AuthError', reason: 'forbidden' })
+  })
+
+  test('default taxonomy serializes ProcedureValidationError at 400 when user opts in', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream(
+      'Stream',
+      {
+        scope: 'test',
+        version: 1,
+        schema: { params: Type.Object({ n: Type.Number() }) },
+      },
+      async function* () {
+        yield { ok: true }
+      }
+    )
+    const app = new HonoStreamAppBuilder({ errors: {} }).register(RPC, () => ({})).build()
+    const res = await app.request('/test/stream/1?n=not-a-number')
+    expect(res.status).toBe(400)
+    const body = (await res.json()) as any
+    expect(body.name).toBe('ProcedureValidationError')
+  })
+
+  test('onError callback runs when taxonomy does not match', async () => {
+    const onError = vi.fn(async (_p: any, c: any) => c.json({ handled: true }, 418))
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { ok: true }
+    })
+    const app = new HonoStreamAppBuilder({ onError })
+      .register(RPC, () => {
+        throw new TypeError('context failed')
+      })
+      .build()
+
+    const res = await app.request('/test/stream/1')
+    expect(res.status).toBe(418)
+    expect(onError).toHaveBeenCalledOnce()
+  })
+
+  test('unknownError is used for unmapped pre-stream errors', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { ok: true }
+    })
+    const app = new HonoStreamAppBuilder({
+      unknownError: {
+        statusCode: 503,
+        toResponse: () => ({ name: 'ServiceUnavailable' }),
+      },
+    })
+      .register(RPC, () => {
+        throw new TypeError('infra down')
+      })
+      .build()
+
+    const res = await app.request('/test/stream/1')
+    expect(res.status).toBe(503)
+    expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
+  })
+})

package/src/implementations/http/hono-stream/index.test.ts

@@ -503,7 +503,7 @@ describe('HonoStreamAppBuilder', () => {
         return c.json({ customError: error.message }, 400)
       })
 
-      const builder = new HonoStreamAppBuilder({ onPreStreamError: errorHandler })
+      const builder = new HonoStreamAppBuilder({ onError: errorHandler })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -575,8 +575,10 @@ describe('HonoStreamAppBuilder', () => {
       expect(JSON.parse(lines[1]!).error).toContain('Stream error')
     })
 
-    test('validation errors return 400 by default when no error handler', async () => {
-      const builder = new HonoStreamAppBuilder()
+    test('validation errors return 400 when the default taxonomy is engaged (via `errors: {}`)', async () => {
+      // Opting into the taxonomy (even an empty one) engages the framework
+      // default entries — ProcedureValidationError → 400.
+      const builder = new HonoStreamAppBuilder({ errors: {} })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -598,22 +600,53 @@ describe('HonoStreamAppBuilder', () => {
 
       const res = await app.request('/validated/validated-stream/1?count=not-a-number')
 
-      // Default: returns 400 JSON error
       expect(res.status).toBe(400)
       const body = await res.json()
+      expect(body.name).toBe('ProcedureValidationError')
+    })
+
+    test('validation errors return 500 by default with no builder config (hard-default path)', async () => {
+      // With no taxonomy and no onError configured, every error falls through
+      // to the flat 500 hard default — consistent with the other three
+      // builders. Previously hono-stream special-cased ProcedureValidationError
+      // to 400; that predated the taxonomy and was removed in v6.
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'ValidatedStream',
+        {
+          scope: 'validated',
+          version: 1,
+          schema: {
+            params: v.object({ count: v.number() }),
+          },
+        },
+        async function* (ctx, params) {
+          yield { count: params.count }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/validated/validated-stream/1?count=not-a-number')
+
+      expect(res.status).toBe(500)
+      const body = await res.json()
       expect(body.error).toContain('Validation error')
     })
 
-    // Tests for onPreStreamError and onMidStreamError callbacks
+    // Tests for onError and onMidStreamError callbacks
 
-    test('onPreStreamError handles validation errors with custom Response', async () => {
-      const onPreStreamError = vi.fn((procedure, c, error) => {
+    test('onError handles validation errors with custom Response', async () => {
+      const onError = vi.fn((procedure, c, error) => {
         return c.json(
           { customError: true, procedureName: procedure.name, details: error.message },
           422
         )
       })
-      const builder = new HonoStreamAppBuilder({ onPreStreamError })
+      const builder = new HonoStreamAppBuilder({ onError })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -641,14 +674,14 @@ describe('HonoStreamAppBuilder', () => {
       expect(body.procedureName).toBe('ValidatedStream')
       expect(body.details).toContain('Validation error')
 
-      expect(onPreStreamError).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledTimes(1)
     })
 
-    test('onPreStreamError handles context resolution errors', async () => {
-      const onPreStreamError = vi.fn((procedure, c, error) => {
+    test('onError handles context resolution errors', async () => {
+      const onError = vi.fn((procedure, c, error) => {
         return c.json({ contextError: error.message }, 401)
       })
-      const builder = new HonoStreamAppBuilder({ onPreStreamError })
+      const builder = new HonoStreamAppBuilder({ onError })
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 
       RPC.CreateStream('SecureStream', { scope: 'secure', version: 1 }, async function* (ctx) {
@@ -666,7 +699,7 @@ describe('HonoStreamAppBuilder', () => {
       const body = await res.json()
       expect(body.contextError).toBe('Authentication required')
 
-      expect(onPreStreamError).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledTimes(1)
     })
 
     test('onMidStreamError returns custom value written to SSE stream', async () => {
@@ -1257,7 +1290,10 @@ describe('HonoStreamAppBuilder', () => {
 
     test('invalid params are caught by HonoStreamAppBuilder before handler runs', async () => {
       let handlerCalled = false
-      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      // Opt into the taxonomy (empty) so the default ProcedureValidationError
+      // entry returns 400 — the recommended way to get a structured validation
+      // response now that the hard default is a flat 500.
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text', errors: {} })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -1283,7 +1319,7 @@ describe('HonoStreamAppBuilder', () => {
       expect(res.status).toBe(400)
 
       const body = await res.json()
-      expect(body.error).toContain('Validation error')
+      expect(body.name).toBe('ProcedureValidationError')
 
       // Handler should never be called since validation fails before streaming
       expect(handlerCalled).toBe(false)
@@ -1646,14 +1682,14 @@ describe('HonoStreamAppBuilder', () => {
   })
 
   // --------------------------------------------------------------------------
-  // ProcedureValidationError narrowing in onPreStreamError
+  // ProcedureValidationError narrowing in onError
   // --------------------------------------------------------------------------
   describe('ProcedureValidationError narrowing', () => {
-    test('instanceof check works in onPreStreamError', async () => {
+    test('instanceof check works in onError', async () => {
       let wasValidationError = false
 
       const builder = new HonoStreamAppBuilder({
-        onPreStreamError: (procedure, c, error) => {
+        onError: (procedure, c, error) => {
           if (error instanceof ProcedureValidationError) {
             wasValidationError = true
             return c.json({ validation: true, errors: error.errors }, 422)