ts-procedures 5.16.0 → 6.0.0

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

@@ -6,8 +6,28 @@ import { TStreamProcedureRegistration } from '../../../index.js'
 import { ExtractConfig, ExtractContext, ProceduresFactory, RPCConfig } from '../../types.js'
 import { HonoStreamFactoryItem, StreamHttpRouteDoc, StreamMode } from './types.js'
 import { ProcedureValidationError } from '../../../errors.js'
+import {
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  defineErrorTaxonomy,
+  resolveErrorResponse,
+} from '../error-taxonomy.js'
 
 export type { StreamHttpRouteDoc, StreamMode }
+export { defineErrorTaxonomy }
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
+
+/**
+ * Context passed to the `onRequestError` observer. `raw` is the Hono
+ * `Context` for the in-flight request — cast at the use site if you need
+ * framework-specific fields.
+ */
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: TStreamProcedureRegistration
+  raw: Context
+}
 
 export type SSEOptions = {
   event?: string
@@ -54,14 +74,38 @@ export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
   onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   /**
-   * Called for errors BEFORE streaming starts (validation, auth, context resolution).
-   * Return value IS used as the HTTP response.
+   * Declarative error-to-response mapping (one of the two peer error modes).
+   * Thrown error classes map to status codes + bodies declaratively. Mid-stream
+   * errors still go through `onMidStreamError` — the HTTP status is already
+   * committed once streaming starts. See hono-api for the full taxonomy
+   * contract.
+   */
+  errors?: ErrorTaxonomy
+  /**
+   * Fallback serializer when a taxonomy is configured but no entry matches.
    */
-  onPreStreamError?: (
+  unknownError?: UnknownErrorConfig
+  /**
+   * Imperative pre-stream error callback — the other peer error mode.
+   * Receives every pre-stream error directly and returns the HTTP response.
+   * Use this instead of `errors` when you want full control over the response
+   * shape, or alongside it for the tail of errors the taxonomy doesn't cover.
+   *
+   * Mid-stream errors always go through `onMidStreamError`.
+   */
+  onError?: (
     procedure: TStreamProcedureRegistration,
     c: Context,
     error: ProcedureValidationError | Error
   ) => Response | Promise<Response>
+  /**
+   * Cross-cutting observer — fires for every caught pre-stream error, BEFORE
+   * dispatch to the taxonomy or `onError`. Awaited. Cannot mutate the
+   * response. Intended for logging, tracing, and metrics (Sentry, Datadog,
+   * OpenTelemetry). Any error thrown inside the observer is swallowed and
+   * logged so the primary dispatch flow is never disrupted.
+   */
+  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
   /**
    * Called for errors DURING streaming (generator throws).
    * Return value is written to the stream as a yield.
@@ -195,20 +239,17 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
             ? Object.fromEntries(new URL(c.req.url).searchParams)
             : await c.req.json().catch(() => ({}))
 
-        // Validate params BEFORE starting the stream
+        // Validate params BEFORE starting the stream. Throw so both the
+        // validation path and the outer-catch (context resolution) path flow
+        // through one dispatch site.
         if (procedure.config.validation?.params) {
           const { errors } = procedure.config.validation.params(params)
           if (errors) {
-            const error = new ProcedureValidationError(
+            throw new ProcedureValidationError(
               procedure.name,
               `Validation error for ${procedure.name}`,
               errors
             )
-            // Use onPreStreamError if provided
-            if (this.config?.onPreStreamError) {
-              return this.config.onPreStreamError(procedure, c, error)
-            }
-            return c.json({ error: error.message }, 400)
           }
         }
 
@@ -222,9 +263,34 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           return this.handleTextStream(procedure, context, params, c)
         }
       } catch (error) {
-        // Use onPreStreamError for context resolution errors
-        if (this.config?.onPreStreamError) {
-          return this.config.onPreStreamError(procedure, c, error as Error)
+        // Observer fires first — cross-cutting, cannot alter dispatch or the
+        // response. Swallow any throw from the observer so the primary flow
+        // never breaks because of instrumentation.
+        if (this.config?.onRequestError) {
+          try {
+            await this.config.onRequestError({ err: error, procedure, raw: c })
+          } catch (observerErr) {
+            console.error('[ts-procedures hono-stream] onRequestError threw — swallowed:', observerErr)
+          }
+        }
+
+        // Dispatch: taxonomy → onError → hard default. The two modes are
+        // peers; developers configure whichever fits their app.
+        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)
         }
         return c.json({ error: (error as Error).message }, 500)
       }
@@ -442,6 +508,10 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
       jsonSchema,
     }
 
+    if (config.errors && config.errors.length > 0) {
+      base.errors = [...config.errors]
+    }
+
     let extendedDoc: object = {}
 
     if (extendProcedureDoc) {

package/src/implementations/http/on-request-error.test.ts

@@ -0,0 +1,201 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+/**
+ * Cross-builder tests for the `onRequestError` observer hook.
+ *
+ * Invariants verified once per builder:
+ *   1. Fires exactly once for every caught error.
+ *   2. Runs BEFORE dispatch (taxonomy / onError / hard default).
+ *   3. Is awaited — async observer work completes before the response is sent.
+ *   4. Doesn't replace dispatch — response shape when observer is configured
+ *      matches the response shape when it's not.
+ *   5. Thrown errors inside the observer are swallowed — the primary dispatch
+ *      path still produces a response.
+ */
+import { describe, expect, test, vi } from 'vitest'
+import request from 'supertest'
+import { Type } from 'typebox'
+import { Procedures } from '../../index.js'
+import { APIConfig, RPCConfig } from '../types.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'
+
+describe('onRequestError — HonoAPIAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoAPIAppBuilder>[0]) {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new HonoAPIAppBuilder(config).register(API, () => ({})).build()
+  }
+
+  test('fires exactly once and before dispatch', async () => {
+    const order: string[] = []
+    const onRequestError = vi.fn(() => {
+      order.push('observer')
+    })
+    const onError = vi.fn((_p: any, c: any) => {
+      order.push('onError')
+      return c.json({ handled: true }, 418)
+    })
+
+    const app = boomApp({ onRequestError, onError })
+    await app.request('/boom')
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(order).toEqual(['observer', 'onError'])
+  })
+
+  test('is awaited — async work completes before response is sent', async () => {
+    const log: string[] = []
+    const onRequestError = async () => {
+      await new Promise((r) => setTimeout(r, 5))
+      log.push('observer-done')
+    }
+    const app = boomApp({
+      onRequestError,
+      onError: (_p, c) => {
+        log.push('onError-called')
+        return c.json({ ok: true }, 500)
+      },
+    })
+    await app.request('/boom')
+    expect(log).toEqual(['observer-done', 'onError-called'])
+  })
+
+  test('observer-thrown errors are swallowed — dispatch still produces a response', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer exploded')
+      },
+    })
+    const res = await app.request('/boom')
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+
+  test('omitting observer preserves existing behavior', async () => {
+    const app = boomApp({ onError: (_p, c) => c.json({ ok: true }, 418) })
+    const res = await app.request('/boom')
+    expect(res.status).toBe(418)
+  })
+})
+
+describe('onRequestError — HonoRPCAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoRPCAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new HonoRPCAppBuilder(config).register(RPC, () => ({})).build()
+  }
+
+  test('fires once; runs before onError', async () => {
+    const order: string[] = []
+    const onRequestError = vi.fn(() => {
+      order.push('observer')
+    })
+    const onError = vi.fn((_p: any, c: any) => {
+      order.push('onError')
+      return c.json({}, 500)
+    })
+
+    const app = boomApp({ onRequestError, onError })
+    await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(order).toEqual(['observer', 'onError'])
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('boom in observer')
+      },
+    })
+    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})
+
+describe('onRequestError — ExpressRPCAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof ExpressRPCAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new ExpressRPCAppBuilder(config).register(RPC, () => ({})).build()
+  }
+
+  test('fires once; raw is { req, res }', async () => {
+    let rawSeen: any
+    const app = boomApp({
+      onRequestError: (ctx) => {
+        rawSeen = ctx.raw
+      },
+    })
+    await request(app).post('/test/boom/1').send({})
+    expect(rawSeen.req).toBeDefined()
+    expect(rawSeen.res).toBeDefined()
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer bug')
+      },
+    })
+    const res = await request(app).post('/test/boom/1').send({})
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})
+
+describe('onRequestError — HonoStreamAppBuilder (pre-stream)', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoStreamAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { ok: true }
+    })
+    return new HonoStreamAppBuilder(config)
+      .register(RPC, () => {
+        throw new TypeError('context failed')
+      })
+      .build()
+  }
+
+  test('fires once for pre-stream errors', async () => {
+    const onRequestError = vi.fn()
+    const app = boomApp({ onRequestError })
+    await app.request('/test/stream/1')
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(onRequestError.mock.calls[0]![0].err).toBeInstanceOf(TypeError)
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer fail')
+      },
+    })
+    const res = await app.request('/test/stream/1')
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})

package/src/implementations/http/route-errors.test.ts

@@ -0,0 +1,177 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../index.js'
+import { APIConfig, RPCConfig } from '../types.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 {
+  constructor(readonly externalMsg: string) {
+    super(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<{}, APIConfig<keyof typeof appErrors & string>>()
+    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<{}, APIConfig>()
+    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<{}, RPCConfig<keyof typeof appErrors & string>>()
+    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<{}, RPCConfig<keyof typeof appErrors & string>>()
+    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<{}, RPCConfig<keyof typeof appErrors & string>>()
+    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', () => {
+    // TS-only: this test compiles only if the generic narrows correctly.
+    type Narrow = APIConfig<keyof typeof appErrors & string>['errors']
+    const _valid: Narrow = ['UseCaseError', 'AuthError']
+    // @ts-expect-error - 'NotRegistered' is not in the taxonomy
+    const _invalid: Narrow = ['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<{}, APIConfig<keyof typeof appErrors & string>>()
+    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'])
+  })
+})

package/src/implementations/types.ts

@@ -1,9 +1,20 @@
 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 or scopes (scope segments) required to access the RPC
   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> = {
@@ -20,6 +31,8 @@ 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'
@@ -30,7 +43,12 @@ 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 */
@@ -39,6 +57,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 {
@@ -53,6 +77,8 @@ export interface APIHttpRouteDoc extends APIConfig {
     headers?: Record<string, unknown>
     response?: Record<string, unknown>
   }
+  /** Taxonomy keys for errors this route may emit. */
+  errors?: string[]
 }
 
 /**
@@ -90,6 +116,8 @@ export interface StreamHttpRouteDoc extends RPCConfig {
     yieldType?: Record<string, unknown> // Schema for each streamed value
     returnType?: Record<string, unknown> // Final return (optional)
   }
+  /** Taxonomy keys for errors this route may emit (pre-stream only). */
+  errors?: string[]
 }
 
 // ================