ts-procedures 5.16.0 → 6.0.0

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')
+  })
+})

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

@@ -9,9 +9,18 @@ import {
   APIInput,
   HttpMethod,
 } from '../../types.js'
+import {
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  defineErrorTaxonomy,
+  resolveErrorResponse,
+} from '../error-taxonomy.js'
 import { HonoAPIFactoryItem } from './types.js'
 
 export type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod }
+export { defineErrorTaxonomy }
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
 
 // ================
 // Query string parsing
@@ -94,13 +103,48 @@ export type HonoAPIAppBuilderConfig = {
   onRequestEnd?: (c: Context) => void
   onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
   /**
-   * Error handler called when a procedure throws an error.
+   * Declarative error-to-response mapping (one of the two peer error modes).
+   * When a thrown error matches an entry (by `class` or `match`), the builder
+   * serializes it automatically. User entries are checked before the framework
+   * defaults (`ProcedureValidationError`, `ProcedureYieldValidationError`,
+   * `ProcedureError`).
+   */
+  errors?: ErrorTaxonomy
+  /**
+   * Fallback serializer for errors not matched by the taxonomy. Used together
+   * with `errors` for apps that want declarative dispatch plus a well-defined
+   * shape for unexpected errors.
+   */
+  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 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>
+}
+
+/**
+ * Context passed to the `onRequestError` observer. `raw` is the Hono
+ * `Context` for the in-flight request.
+ */
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: TProcedureRegistration
+  raw: Context
 }
 
 /**
@@ -327,6 +371,33 @@ export class HonoAPIAppBuilder {
 
         return c.json(result, successStatus as any)
       } catch (error) {
+        // Observer fires first — cross-cutting, cannot alter dispatch or the
+        // response. Swallow any throw from the observer so instrumentation
+        // bugs never break the primary error-response flow.
+        if (this.config?.onRequestError) {
+          try {
+            await this.config.onRequestError({ err: error, procedure, raw: c })
+          } catch (observerErr) {
+            console.error('[ts-procedures hono-api] onRequestError threw — swallowed:', observerErr)
+          }
+        }
+
+        // Dispatch: taxonomy → onError → hard default. The two modes are
+        // peers; apps configure whichever fits (or both, in which case the
+        // taxonomy handles what it covers and `onError` handles the tail).
+        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)
         }
@@ -430,6 +501,10 @@ export class HonoAPIAppBuilder {
       base.successStatus = config.successStatus
     }
 
+    if (config.errors && config.errors.length > 0) {
+      base.errors = [...config.errors]
+    }
+
     let extendedDoc: object = {}
 
     if (extendProcedureDoc) {

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

@@ -162,27 +162,22 @@ const RPC = Procedures<AppContext, RPCConfig>()
 
 ## Error Handling
 
-Custom error handler receives the procedure, context, and error. **Must return a Response:**
+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
-const builder = new HonoRPCAppBuilder({
-  onError: (procedure, c, error) => {
-    console.error(`Error in ${procedure.name}:`, error)
-
-    if (error instanceof ValidationError) {
-      return c.json({ error: error.message, code: 'VALIDATION_ERROR' }, 400)
-    }
+import { defineErrorTaxonomy } from 'ts-procedures/hono-rpc'
 
-    if (error instanceof AuthError) {
-      return c.json({ error: 'Unauthorized', code: 'AUTH_ERROR' }, 401)
-    }
+const appErrors = defineErrorTaxonomy({
+  AuthError: { class: AuthError, statusCode: 401 },
+})
 
-    return c.json({ error: 'Internal server error' }, 500)
-  },
+new HonoRPCAppBuilder({
+  errors: appErrors,
+  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
 })
 ```
 
-**Default error handling:** Returns `{ error: message }` with status 500.
+Full contract (both peer error modes, `onRequestError` observer, per-route narrowing via `RPCConfig<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.
 
 ## Using Existing Hono App
 
@@ -269,11 +264,15 @@ new HonoRPCAppBuilder(config?: HonoRPCAppBuilderConfig)
 ## TypeScript Types
 
 ```typescript
-import {
-  HonoRPCAppBuilder,
+import { HonoRPCAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-rpc'
+import type {
   HonoRPCAppBuilderConfig,
   RPCConfig,
   RPCHttpRouteDoc,
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  OnRequestErrorContext,
 } from 'ts-procedures/hono-rpc'
 ```
 
@@ -345,10 +344,10 @@ builder
 const app = builder.build()
 
 // Generated routes:
-// POST /rpc/health/1
+// POST /rpc/health/health-check/1
 // POST /rpc/system/version/get-version/1
-// POST /rpc/users/profile/get-user/1
-// POST /rpc/users/profile/get-user/2
+// POST /rpc/users/profile/get-profile/1
+// POST /rpc/users/profile/update-profile/2
 
 console.log(
   'Routes:',