ts-procedures 5.16.0 → 6.0.1

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

@@ -0,0 +1,361 @@
+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'],
+    },
+  },
+})
+
+/**
+ * Doc-only entry for `ProcedureRegistrationError`, which is thrown at
+ * procedure-definition time (never at request time) and therefore doesn't
+ * appear in the runtime taxonomy. Consumers still see it in the error catalog
+ * via `DocRegistry.defaultErrors()`.
+ */
+export const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
+  name: 'ProcedureRegistrationError',
+  statusCode: 500,
+  description:
+    'An invalid schema or configuration was detected at procedure registration time.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: 'ProcedureRegistrationError' },
+      procedureName: { type: 'string' },
+      message: { type: 'string' },
+    },
+    required: ['name', 'procedureName', 'message'],
+  },
+}
+
+/**
+ * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
+ *
+ * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
+ *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
+ *   rather than calling this helper — the constructor handles the conversion.
+ */
+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

@@ -59,7 +59,7 @@ type ExpressRPCAppBuilderConfig = {
   onRequestStart?: (req: express.Request) => void
   onRequestEnd?: (req: express.Request, res: express.Response) => void
   onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void
-  error?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
+  onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
 }
 ```
 
@@ -70,7 +70,7 @@ type ExpressRPCAppBuilderConfig = {
 | `onRequestStart` | `(req) => void` | Called at start of each request                      |
 | `onRequestEnd` | `(req, res) => void` | Called after response finishes                       |
 | `onSuccess` | `(proc, req, res) => void` | Called on successful handler execution               |
-| `error` | `(proc, req, res, err) => void` | Custom error handler                                 |
+| `onError` | `(proc, req, res, err) => void` | Imperative error handler (peer of `errors` taxonomy — see Error Handling) |
 
 ## Context Resolution
 
@@ -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()
+  })
+})