ts-procedures 5.16.0 → 6.0.0

package/src/implementations/http/error-taxonomy.ts

@@ -0,0 +1,337 @@
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureYieldValidationError,
+} from '../../errors.js'
+import type { TProcedureRegistration, TStreamProcedureRegistration } from '../../index.js'
+import type { ErrorDoc } from '../types.js'
+
+/** Either a regular or stream procedure registration — accepted by taxonomy callbacks. */
+export type TAnyProcedureRegistration = TProcedureRegistration | TStreamProcedureRegistration
+
+/**
+ * An entry in an {@link ErrorTaxonomy}. Describes how to recognize a thrown
+ * error at runtime and how to serialize it into an HTTP response.
+ *
+ * Exactly one of `class` or `match` must be provided.
+ */
+export type ErrorTaxonomyEntry<TError = any, TBody = unknown> = {
+  /** `instanceof` discriminator. Mutually exclusive with `match`. */
+  class?: new (...args: any[]) => TError
+  /** Predicate discriminator — for 3rd-party errors that can't subclass a framework type. */
+  match?: (err: unknown) => err is TError
+  /** HTTP status code to send when this error is caught. */
+  statusCode: number
+  /** One-line description used by DocRegistry to document the error in the envelope. */
+  description?: string
+  /** Optional response-body JSON Schema — consumed by DocRegistry. */
+  schema?: Record<string, unknown>
+  /**
+   * Maps the caught error to a response body. When omitted, the body is
+   * `{ name: <key>, message: err.message }` where `<key>` is this entry's key.
+   * When the returned object lacks a `name` field, one is auto-injected —
+   * wire-protocol consistency (needed by the client dispatcher) is guaranteed.
+   */
+  toResponse?: (err: TError, meta: { key: string }) => TBody
+  /**
+   * Side effect on catch (logging, metrics). Awaited before the response is sent.
+   * `raw` is the framework-specific request context (Hono `Context` /
+   * `{ req, res }` for Express) — cast as needed.
+   */
+  onCatch?: (
+    err: TError,
+    ctx: { procedure: TAnyProcedureRegistration; key: string; raw: unknown }
+  ) => void | Promise<void>
+}
+
+/**
+ * A named collection of {@link ErrorTaxonomyEntry} values. First match wins at
+ * resolution time. `defineErrorTaxonomy` topologically sorts class-based
+ * entries so a subclass is always checked before its ancestors regardless of
+ * declaration order; predicate entries retain declared order.
+ */
+export type ErrorTaxonomy = Record<string, ErrorTaxonomyEntry>
+
+/**
+ * Identity helper that preserves literal inference and:
+ * 1. validates each entry has exactly one discriminator (`class` xor `match`);
+ * 2. topologically sorts `class:` entries so subclasses precede base classes.
+ *
+ * The sort is stable — entries unrelated by inheritance keep their declared
+ * order. Predicate entries (with `match:`) always keep declared order relative
+ * to class entries, so a predicate that's intentionally narrower can be placed
+ * before a class entry to take precedence.
+ */
+export function defineErrorTaxonomy<T extends ErrorTaxonomy>(entries: T): T {
+  const pairs = Object.entries(entries)
+
+  for (const [key, entry] of pairs) {
+    const hasClass = entry.class !== undefined
+    const hasMatch = entry.match !== undefined
+    if (hasClass === hasMatch) {
+      throw new Error(
+        `Error taxonomy entry "${key}" must define exactly one of { class, match }.`
+      )
+    }
+  }
+
+  // Stable sort: subclass-of-the-other → -1, other-subclass-of-this → 1, else 0.
+  pairs.sort(([, a], [, b]) => {
+    if (!a.class || !b.class) return 0
+    if (a.class === b.class) return 0
+    if (a.class.prototype instanceof b.class) return -1
+    if (b.class.prototype instanceof a.class) return 1
+    return 0
+  })
+
+  return Object.fromEntries(pairs) as T
+}
+
+/**
+ * Default taxonomy covering framework error classes that can be thrown by a
+ * handler at request time. Layered after the user taxonomy during resolution.
+ *
+ * `ProcedureError` uses `match:` rather than `class:` so it matches only
+ * direct throws (e.g. from `ctx.error()`). When the core wraps a non-ProcedureError
+ * into a ProcedureError with `cause`, that wrapper falls through — the
+ * resolver unwraps the cause and the user taxonomy / `unknownError` sees the
+ * real thrown value.
+ */
+export const defaultErrorTaxonomy = defineErrorTaxonomy({
+  ProcedureValidationError: {
+    class: ProcedureValidationError,
+    statusCode: 400,
+    description: 'Schema validation failed for the procedure input parameters.',
+    toResponse: (err) => ({
+      name: 'ProcedureValidationError' as const,
+      procedureName: err.procedureName,
+      message: err.message,
+      errors: err.errors,
+    }),
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'ProcedureValidationError' },
+        procedureName: { type: 'string' },
+        message: { type: 'string' },
+        errors: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              instancePath: { type: 'string' },
+              message: { type: 'string' },
+            },
+          },
+        },
+      },
+      required: ['name', 'procedureName', 'message'],
+    },
+  },
+  ProcedureYieldValidationError: {
+    class: ProcedureYieldValidationError,
+    statusCode: 500,
+    description: 'Schema validation failed for a yielded value in a streaming procedure.',
+    toResponse: (err) => ({
+      name: 'ProcedureYieldValidationError' as const,
+      procedureName: err.procedureName,
+      message: err.message,
+      errors: err.errors,
+    }),
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'ProcedureYieldValidationError' },
+        procedureName: { type: 'string' },
+        message: { type: 'string' },
+        errors: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              instancePath: { type: 'string' },
+              message: { type: 'string' },
+            },
+          },
+        },
+      },
+      required: ['name', 'procedureName', 'message'],
+    },
+  },
+  ProcedureError: {
+    match: (err): err is ProcedureError =>
+      err instanceof ProcedureError && (err as { cause?: unknown }).cause === undefined,
+    statusCode: 500,
+    description: 'An error thrown from within a procedure handler via ctx.error().',
+    toResponse: (err) => ({
+      name: 'ProcedureError' as const,
+      procedureName: err.procedureName,
+      message: err.message,
+      meta: err.meta,
+    }),
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'ProcedureError' },
+        procedureName: { type: 'string' },
+        message: { type: 'string' },
+        meta: { type: 'object' },
+      },
+      required: ['name', 'procedureName', 'message'],
+    },
+  },
+})
+
+/**
+ * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
+ * Single source of truth so the runtime mapping and the documented shape
+ * cannot drift apart.
+ */
+export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
+  return Object.entries(taxonomy).map(([key, entry]) => ({
+    name: key,
+    statusCode: entry.statusCode,
+    description: entry.description ?? '',
+    schema: entry.schema,
+  }))
+}
+
+/**
+ * Configuration for the fallback "unknown" error handler — applied when no
+ * taxonomy entry (user or default) matches a thrown value.
+ */
+export type UnknownErrorConfig = {
+  /** HTTP status code. Defaults to 500. */
+  statusCode?: number
+  /** Serializes the error into a response body. */
+  toResponse: (err: unknown) => unknown
+  /** Awaited before the response is sent. */
+  onCatch?: (
+    err: unknown,
+    ctx: { procedure: TAnyProcedureRegistration; raw: unknown }
+  ) => void | Promise<void>
+}
+
+/**
+ * Result of matching an error against a taxonomy chain. Consumers translate
+ * `{ statusCode, body }` into their framework's response primitive and must
+ * `await runOnCatch()` before sending.
+ */
+export type ResolvedErrorResponse = {
+  statusCode: number
+  body: unknown
+  runOnCatch: () => Promise<void>
+}
+
+/**
+ * Injects `{ name: key }` when `rawBody` is an object without a `name` field.
+ * Guarantees wire-protocol consistency (client dispatchers discriminate on
+ * `body.name`) without forcing every `toResponse` to repeat it.
+ */
+function ensureName(rawBody: unknown, key: string): unknown {
+  if (rawBody && typeof rawBody === 'object' && !('name' in (rawBody as object))) {
+    return { name: key, ...(rawBody as object) }
+  }
+  return rawBody
+}
+
+/**
+ * Matches a thrown value against the user taxonomy, then (if `includeDefaults`)
+ * the default taxonomy, then the `unknownError` config. Returns `null` when
+ * nothing matches — callers fall through to their builder's imperative
+ * `onError` callback and the hard default.
+ *
+ * The core wraps any non-ProcedureError thrown by a handler into a
+ * ProcedureError with `cause` set to the original. This resolver unwraps that:
+ * candidates are checked in the order `[cause, outer]` so a user taxonomy sees
+ * its own error classes rather than the wrapper. The default `ProcedureError`
+ * entry uses a `match:` predicate that excludes wrappers so they reach
+ * `unknownError` instead.
+ *
+ * Side effects (`onCatch`) are deferred into `runOnCatch` so the caller decides
+ * when to execute them relative to writing the response.
+ */
+export function resolveErrorResponse(params: {
+  err: unknown
+  userTaxonomy?: ErrorTaxonomy
+  /** Whether to apply {@link defaultErrorTaxonomy}. Defaults to `true`. */
+  includeDefaults?: boolean
+  unknownError?: UnknownErrorConfig
+  procedure: TAnyProcedureRegistration
+  raw: unknown
+}): ResolvedErrorResponse | null {
+  const {
+    err,
+    userTaxonomy,
+    includeDefaults = true,
+    unknownError,
+    procedure,
+    raw,
+  } = params
+
+  const wrappedCause =
+    err instanceof ProcedureError && (err as { cause?: unknown }).cause !== undefined
+      ? (err as { cause?: unknown }).cause
+      : undefined
+  // Most-specific candidate first so a matching user entry on `cause` wins over
+  // a matching entry on the outer wrapper.
+  const candidates: unknown[] =
+    wrappedCause !== undefined ? [wrappedCause, err] : [err]
+
+  const tryMatch = (tax: ErrorTaxonomy): ResolvedErrorResponse | null => {
+    for (const [key, entry] of Object.entries(tax)) {
+      for (const candidate of candidates) {
+        const matched = entry.class
+          ? candidate instanceof entry.class
+          : entry.match
+            ? entry.match(candidate)
+            : false
+        if (!matched) continue
+
+        const rawBody = entry.toResponse
+          ? entry.toResponse(candidate as any, { key })
+          : {
+              name: key,
+              message: candidate instanceof Error ? candidate.message : String(candidate),
+            }
+        const body = ensureName(rawBody, key)
+
+        return {
+          statusCode: entry.statusCode,
+          body,
+          runOnCatch: async () => {
+            if (entry.onCatch) {
+              await entry.onCatch(candidate as any, { procedure, key, raw })
+            }
+          },
+        }
+      }
+    }
+    return null
+  }
+
+  if (userTaxonomy) {
+    const hit = tryMatch(userTaxonomy)
+    if (hit) return hit
+  }
+
+  if (includeDefaults) {
+    const hit = tryMatch(defaultErrorTaxonomy)
+    if (hit) return hit
+  }
+
+  if (unknownError) {
+    const mostSpecific = candidates[0]
+    return {
+      statusCode: unknownError.statusCode ?? 500,
+      body: unknownError.toResponse(mostSpecific),
+      runOnCatch: async () => {
+        if (unknownError.onCatch) {
+          await unknownError.onCatch(mostSpecific, { procedure, raw })
+        }
+      },
+    }
+  }
+
+  return null
+}

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

@@ -120,29 +120,24 @@ const RPC = Procedures<AppContext, RPCConfig>()
 
 ## Error Handling
 
-Custom error handler receives the procedure, request, response, and error:
+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 ExpressRPCAppBuilder({
-  onError: (procedure, req, res, error) => {
-    console.error(`Error in ${procedure.name}:`, error)
-
-    if (error instanceof ValidationError) {
-      res.status(400).json({ error: error.message, code: 'VALIDATION_ERROR' })
-      return
-    }
+import { defineErrorTaxonomy } from 'ts-procedures/express-rpc'
 
-    if (error instanceof AuthError) {
-      res.status(401).json({ error: 'Unauthorized', code: 'AUTH_ERROR' })
-      return
-    }
+const appErrors = defineErrorTaxonomy({
+  AuthError: { class: AuthError, statusCode: 401 },
+})
 
-    res.status(500).json({ error: 'Internal server error' })
-  }
+new ExpressRPCAppBuilder({
+  errors: appErrors,
+  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
 })
 ```
 
-**Default error handling:** Returns `{ error: message }` with status 500.
+Express-specific note: `onCatch` receives `raw: { req, res }` as its framework request context (cast at the use site).
+
+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 Express App
 
@@ -195,11 +190,15 @@ new ExpressRPCAppBuilder(config?: ExpressRPCAppBuilderConfig)
 ## TypeScript Types
 
 ```typescript
-import {
-  ExpressRPCAppBuilder,
+import { ExpressRPCAppBuilder, defineErrorTaxonomy } from 'ts-procedures/express-rpc'
+import type {
   ExpressRPCAppBuilderConfig,
   RPCConfig,
-  RPCHttpRouteDoc
+  RPCHttpRouteDoc,
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  OnRequestErrorContext,
 } from 'ts-procedures/express-rpc'
 ```
 
@@ -271,10 +270,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:', builder.docs.map(d => d.path))
 app.listen(3000)

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

@@ -0,0 +1,103 @@
+import { describe, expect, test, vi } from 'vitest'
+import request from 'supertest'
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import { RPCConfig } from '../../types.js'
+import { ExpressRPCAppBuilder, 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('ExpressRPCAppBuilder — 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 ExpressRPCAppBuilder({ errors }).register(RPC, () => ({})).build()
+    const res = await request(app).post('/test/boom/1').send({})
+    expect(res.status).toBe(422)
+    expect(res.body).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 ExpressRPCAppBuilder({
+      unknownError: { statusCode: 503, toResponse: () => ({ name: 'ServiceUnavailable' }) },
+    })
+      .register(RPC, () => ({}))
+      .build()
+    const res = await request(app).post('/test/boom/1').send({})
+    expect(res.status).toBe(503)
+    expect(res.body).toEqual({ name: 'ServiceUnavailable' })
+  })
+
+  test('onCatch receives { req, res } as raw context', async () => {
+    let rawSeen: any
+    const errors = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch: (_err, ctx) => {
+          rawSeen = ctx.raw
+        },
+      },
+    })
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new UseCaseError('ext', 'int')
+      }
+    )
+    const app = new ExpressRPCAppBuilder({ errors }).register(RPC, () => ({})).build()
+    await request(app).post('/test/boom/1').send({})
+    expect(rawSeen.req).toBeDefined()
+    expect(rawSeen.res).toBeDefined()
+  })
+
+  test('onError callback handles errors not matched by the taxonomy', async () => {
+    const onError = vi.fn((_p: any, _req: any, res: any) => {
+      res.status(418).json({ legacy: true })
+    })
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('legacy')
+      }
+    )
+    const app = new ExpressRPCAppBuilder({ onError }).register(RPC, () => ({})).build()
+    const res = await request(app).post('/test/boom/1').send({})
+    expect(res.status).toBe(418)
+    expect(onError).toHaveBeenCalledOnce()
+  })
+})

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) {