ts-procedures 5.16.0 → 6.0.1

package/src/implementations/http/express-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 { ExpressFactoryItem } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
+export { defineErrorTaxonomy }
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
 
 export type ExpressRPCAppBuilderConfig = {
   /**
@@ -30,11 +39,18 @@ export type ExpressRPCAppBuilderConfig = {
     res: express.Response
   ) => void
   /**
-   * Error handler called when a procedure throws an error.
-   * @param procedure
-   * @param req
-   * @param res
-   * @param error
+   * Declarative error-to-response mapping (one of the two peer error modes).
+   * See hono-api for the full taxonomy contract. The `raw` field passed to
+   * taxonomy callbacks is `{ req, res }`.
+   */
+  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 writes the response via `res`. Use this when you want
+   * full control, or alongside `errors` for the tail of errors the taxonomy
+   * doesn't cover.
    */
   onError?: (
     procedure: TProcedureRegistration,
@@ -42,6 +58,23 @@ export type ExpressRPCAppBuilderConfig = {
     res: express.Response,
     error: Error
   ) => void
+  /**
+   * Cross-cutting observer — fires for every caught error, BEFORE dispatch.
+   * Awaited. Cannot write to `res` (observer only — check `res.headersSent`
+   * if you must touch it). Thrown errors inside the observer are swallowed
+   * and logged.
+   */
+  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
+}
+
+/**
+ * Context passed to the `onRequestError` observer. `raw` is `{ req, res }`
+ * for the in-flight request.
+ */
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: TProcedureRegistration
+  raw: { req: express.Request; res: express.Response }
 }
 
 /**
@@ -92,11 +125,13 @@ export class ExpressRPCAppBuilder {
 
   /**
    * 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({
@@ -200,16 +235,39 @@ export class ExpressRPCAppBuilder {
               res.status(200)
             }
           } catch (error) {
+            if (this.config?.onRequestError) {
+              try {
+                await this.config.onRequestError({ err: error, procedure, raw: { req, res } })
+              } catch (observerErr) {
+                console.error('[ts-procedures express-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: { req, res },
+              })
+              if (resolved) {
+                await resolved.runOnCatch()
+                if (!res.headersSent) {
+                  res.status(resolved.statusCode).json(resolved.body)
+                }
+                return
+              }
+            }
             if (this.config?.onError) {
               this.config.onError(procedure, req, res, error as Error)
               return
             }
-            if (!res.status) {
-              res.status(500)
-            }
-            // if no res.json set, set default error message
+            // Hard default — `res.status` is always truthy (it's a method),
+            // so the previous `if (!res.status)` guard never ran. Set status
+            // and body together unconditionally, respecting an already-sent
+            // response.
             if (!res.headersSent) {
-              res.json({ error: (error as Error).message })
+              res.status(500).json({ error: (error as Error).message })
             }
           }
         })
@@ -243,7 +301,7 @@ export class ExpressRPCAppBuilder {
       jsonSchema.response = config.schema.returnType
     }
 
-    const base = {
+    const base: RPCHttpRouteDoc = {
       kind: 'rpc' as const,
       name: procedure.name,
       version: config.version,
@@ -252,6 +310,9 @@ export class ExpressRPCAppBuilder {
       method,
       jsonSchema,
     }
+    if (config.errors && config.errors.length > 0) {
+      base.errors = [...config.errors]
+    }
     let extendedDoc: object = {}
 
     if (extendProcedureDoc) {

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

@@ -0,0 +1,284 @@
+# Hono API (REST-style) Integration
+
+REST-style HTTP integration for Hono — routes are dispatched by HTTP method with per-channel input validation (`schema.input.pathParams`, `query`, `body`, `headers`). Works with Bun, Deno, Cloudflare Workers, and Node.js.
+
+## Installation
+
+```bash
+npm install ts-procedures hono
+```
+
+## Quick Start
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoAPIAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/hono-api'
+import { Type } from 'typebox'
+
+// ─── Procedures ───────────────────────────────────────────
+
+const API = Procedures<{ userId: string }, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { pathParams }) => {
+  return { id: pathParams.id, name: 'John Doe' }
+})
+
+API.Create('CreateUser', {
+  path: '/users',
+  method: 'post',                    // → 201 by default
+  schema: {
+    input: { body: Type.Object({ name: Type.String(), email: Type.String() }) },
+    returnType: Type.Object({ id: Type.String() }),
+  },
+}, async (ctx, { body }) => {
+  return { id: await createUser(body) }
+})
+
+// ─── Build ────────────────────────────────────────────────
+
+const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+
+// Routes:
+//   GET  /api/users/:id   → 200
+//   POST /api/users       → 201
+```
+
+## Configuration
+
+```typescript
+export type HonoAPIAppBuilderConfig = {
+  app?: Hono                                     // Reuse an existing Hono instance
+  pathPrefix?: string                            // Prepend to every route
+  queryParser?: QueryParser                      // Custom query-string parser
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+  onSuccess?: (procedure, c: Context) => void
+  errors?: ErrorTaxonomy                         // Declarative error-to-response mapping
+  unknownError?: UnknownErrorConfig              // Fallback for unmatched errors
+  onError?: (procedure, c, error) => Response    // Imperative error callback (peer of `errors` above)
+  onRequestError?: (ctx) => void | Promise<void> // Cross-cutting observer for logging/tracing
+}
+```
+
+| Option | Description |
+|---|---|
+| `app` | Existing Hono instance to register routes on. If omitted, a new `Hono()` is created. |
+| `pathPrefix` | Prefix applied to every route (e.g. `/api/v1`). Leading slash is optional. |
+| `queryParser` | Override the default native `URLSearchParams` parser (see *Query Parsing* below). |
+| `onRequestStart` / `onRequestEnd` | Global lifecycle hooks — wrap every registered route. |
+| `onSuccess` | Called after a handler returns successfully, before the response is sent. |
+| `errors` / `unknownError` | Declarative error handling — see *Error Handling* below. |
+| `onError` | Imperative error callback — first-class peer of the declarative taxonomy. |
+| `onRequestError` | Cross-cutting observer — fires for every caught error before dispatch. Awaited; can't mutate the response. For logging / tracing / metrics. |
+
+## schema.input — Multi-Channel Structured Input
+
+REST endpoints carry input via several transport channels. `schema.input` lets you type and validate each independently:
+
+```typescript
+API.Create('UpdatePost', {
+  path: '/posts/:id',
+  method: 'put',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({ draft: Type.Optional(Type.Boolean()) }),
+      body: Type.Object({ title: Type.String(), body: Type.String() }),
+      headers: Type.Object({ 'if-match': Type.String() }),
+    },
+    returnType: Type.Object({ id: Type.String(), version: Type.Number() }),
+  },
+}, async (ctx, { pathParams, query, body, headers }) => {
+  // All four channels typed independently.
+  // AJV validates each channel; `removeAdditional` strips undeclared keys from headers.
+})
+```
+
+Supported channels: `pathParams`, `query`, `body`, `headers`. `schema.input` is mutually exclusive with `schema.params` — defining both throws `ProcedureRegistrationError` at registration time.
+
+`HonoAPIAppBuilder` performs build-time consistency checks: `:id` in the path template must match a `pathParams.id` entry in the schema, or the builder throws at `.build()`.
+
+### APIInput helper
+
+```typescript
+import type { APIInput } from 'ts-procedures/hono-api'
+
+const schema = {
+  input: {
+    pathParams: Type.Object({ id: Type.String() }),
+    qurey: Type.Object({ /* ... */ }),  // ← TS error: 'qurey' not in APIInput
+  } satisfies APIInput,
+}
+```
+
+`APIInput` constrains channel names so typos become compile errors.
+
+## Default Success Status
+
+| Method | Default status |
+|---|---|
+| `post` | 201 |
+| `delete` | 204 |
+| `get`, `put`, `patch`, `head` | 200 |
+
+Override via `successStatus` on the per-route config:
+
+```typescript
+API.Create('RemoveUser', {
+  path: '/users/:id',
+  method: 'delete',
+  successStatus: 200,  // Override the default 204
+  schema: { input: { pathParams: Type.Object({ id: Type.String() }) } },
+}, async (ctx, { pathParams }) => { /* ... */ })
+```
+
+## Query Parsing
+
+Default: native `URLSearchParams`. Handles flat keys (`?page=2`) and repeated keys (`?tag=a&tag=b → { tag: ['a', 'b'] }`). It does **not** parse bracket objects, bracket arrays, dot paths, or comma-split arrays.
+
+Opt in to richer parsing via `qs`:
+
+```typescript
+import qs from 'qs'
+
+new HonoAPIAppBuilder({
+  queryParser: (raw) => qs.parse(raw) as Record<string, unknown>,
+})
+```
+
+## Context Resolution
+
+The context resolver receives Hono's `Context` object:
+
+```typescript
+builder.register(API, (c) => ({
+  userId: c.req.header('x-user-id') || 'anonymous',
+  requestId: c.req.header('x-request-id') ?? crypto.randomUUID(),
+}))
+
+// Async context resolution — authenticate per request
+builder.register(API, async (c) => {
+  const token = c.req.header('authorization')?.replace('Bearer ', '')
+  const user = await verifyToken(token)
+  return { userId: user.id, roles: user.roles }
+})
+```
+
+## Abort Signal
+
+`HonoAPIAppBuilder` injects `c.req.raw.signal` as `ctx.signal` in every handler so downstream async calls (fetch, DB queries) can cancel when the client disconnects.
+
+```typescript
+API.Create('StreamingQuery', { /* ... */ }, async (ctx) => {
+  const result = await db.query(sql, { signal: ctx.signal })
+  return result
+})
+```
+
+## Error Handling
+
+Declare error classes via `defineErrorTaxonomy` and pass them to the builder's `errors` option. Handlers `throw` their classes; the builder auto-serializes to the configured status + body.
+
+```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/hono-api'
+
+const appErrors = defineErrorTaxonomy({
+  NotFoundError: { class: NotFoundError, statusCode: 404 },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
+})
+```
+
+Full contract (both peer error modes, `onRequestError` observer, per-route narrowing via `APIConfig<keyof typeof appErrors & string>`): see **[docs/http-integrations.md § Error Handling](../../../../docs/http-integrations.md#error-handling)** — the canonical explanation shared across all four HTTP builders.
+
+## Extending Procedure Documentation
+
+Like the other builders, `register()` accepts an optional third argument that extends each route's generated doc object:
+
+```typescript
+builder.register(API, ctxResolver, ({ base, procedure }) => ({
+  summary: procedure.config.description,
+  tags: [base.scope ?? 'default'],
+  deprecated: procedure.config.description?.toLowerCase().includes('deprecated') ?? false,
+}))
+```
+
+The extended doc is spread onto the `APIHttpRouteDoc` before `base`, so base fields (`kind`, `name`, `method`, `path`, `fullPath`, `jsonSchema`, `errors`) always win.
+
+## Using an Existing Hono App
+
+```typescript
+const app = new Hono()
+app.use('*', cors())
+app.get('/health', (c) => c.json({ ok: true }))
+
+new HonoAPIAppBuilder({ app, pathPrefix: '/api' })
+  .register(API, contextResolver)
+  .build()
+
+// API routes added alongside your custom routes.
+```
+
+## Route Documentation
+
+Each registered procedure generates an `APIHttpRouteDoc` accessible via `builder.docs`:
+
+```typescript
+interface APIHttpRouteDoc {
+  kind: 'api'
+  name: string
+  scope?: string
+  path: string
+  fullPath: string                  // path with pathPrefix applied
+  method: HttpMethod
+  successStatus?: number
+  jsonSchema: {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: Record<string, unknown>
+    headers?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+  errors?: string[]                 // Taxonomy keys this route may emit
+}
+```
+
+Feed these into `DocRegistry` to compose a single `/docs` endpoint from multiple builders — see [docs/http-integrations.md § DocRegistry](../../../../docs/http-integrations.md#docregistry--composing-docs-from-multiple-builders).
+
+## Runtime Compatibility
+
+Runs wherever Hono runs: Bun, Deno, Cloudflare Workers, Node.js 18+. Uses standard Fetch API (`c.req.raw.signal`, `Request`, `Response`) — no Node-specific APIs.
+
+## TypeScript Types
+
+```typescript
+import type {
+  APIConfig,
+  APIHttpRouteDoc,
+  APIInput,
+  HttpMethod,
+  HonoAPIAppBuilderConfig,
+  QueryParser,
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  OnRequestErrorContext,
+} from 'ts-procedures/hono-api'
+
+import { HonoAPIAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-api'
+```

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

@@ -0,0 +1,179 @@
+import { describe, expect, test, vi } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import { APIConfig } from '../../types.js'
+import { HonoAPIAppBuilder, 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('HonoAPIAppBuilder — error taxonomy', () => {
+  test('taxonomy serializes user error with configured status + body', async () => {
+    const errors = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      {
+        path: '/boom',
+        method: 'get',
+        schema: { returnType: Type.Object({}) },
+      },
+      async () => {
+        throw new UseCaseError('public detail', 'private stack')
+      }
+    )
+
+    const app = new HonoAPIAppBuilder({ errors }).register(API, () => ({})).build()
+    const res = await app.request('/boom')
+    expect(res.status).toBe(422)
+    expect(await res.json()).toEqual({ name: 'UseCaseError', message: 'public detail' })
+  })
+
+  test('onCatch is awaited before response is sent', async () => {
+    const logged: string[] = []
+    const onCatch = vi.fn(async (err: UseCaseError) => {
+      await Promise.resolve()
+      logged.push(err.internalMsg)
+    })
+
+    const errors = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch,
+      },
+    })
+
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new UseCaseError('ext', 'int-log')
+      }
+    )
+
+    const app = new HonoAPIAppBuilder({ errors }).register(API, () => ({})).build()
+    await app.request('/boom')
+    expect(onCatch).toHaveBeenCalledOnce()
+    expect(logged).toEqual(['int-log'])
+  })
+
+  test('unknownError catches errors the taxonomy does not match', async () => {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new TypeError('ts-broke')
+      }
+    )
+
+    const app = new HonoAPIAppBuilder({
+      unknownError: {
+        statusCode: 503,
+        toResponse: () => ({ name: 'ServiceUnavailable' }),
+      },
+    })
+      .register(API, () => ({}))
+      .build()
+
+    const res = await app.request('/boom')
+    expect(res.status).toBe(503)
+    expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
+  })
+
+  test('default taxonomy catches ProcedureValidationError at 400 when user opts in', async () => {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Validate',
+      {
+        path: '/v',
+        method: 'post',
+        schema: {
+          input: { body: Type.Object({ n: Type.Number() }) },
+          returnType: Type.Object({}),
+        },
+      },
+      async () => ({})
+    )
+    // Empty user taxonomy opts into the default chain.
+    const app = new HonoAPIAppBuilder({ errors: {} }).register(API, () => ({})).build()
+    const res = await app.request('/v', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ 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/unknownError do not match', async () => {
+    const onError = vi.fn(async (_p: any, c: any) => c.json({ legacy: true }, 418))
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new TypeError('legacy path')
+      }
+    )
+    const app = new HonoAPIAppBuilder({ onError }).register(API, () => ({})).build()
+    const res = await app.request('/boom')
+    expect(res.status).toBe(418)
+    expect(await res.json()).toEqual({ legacy: true })
+    expect(onError).toHaveBeenCalledOnce()
+  })
+
+  test('no config → hard default unchanged ({ error: message }, 500)', async () => {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new TypeError('untouched')
+      }
+    )
+    const app = new HonoAPIAppBuilder().register(API, () => ({})).build()
+    const res = await app.request('/boom')
+    expect(res.status).toBe(500)
+    // The handler's TypeError is wrapped by the core into a ProcedureError with
+    // `cause` set. The default ProcedureError entry skips wrappers, no
+    // unknownError is configured, and no onError is provided — so we hit the
+    // hard default: { error: message }.
+    expect(await res.json()).toEqual({ error: expect.stringContaining('untouched') })
+  })
+
+  test('ctx.error() is serialized by the default ProcedureError taxonomy entry when opted in', async () => {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async (ctx) => {
+        throw ctx.error('direct from ctx.error', { code: 'E1' })
+      }
+    )
+    const app = new HonoAPIAppBuilder({ errors: {} }).register(API, () => ({})).build()
+    const res = await app.request('/boom')
+    expect(res.status).toBe(500)
+    const body = (await res.json()) as any
+    expect(body.name).toBe('ProcedureError')
+    expect(body.procedureName).toBe('Boom')
+  })
+})