ts-procedures 8.5.0 → 9.0.0

package/src/server/errors/dispatch.test.ts

@@ -0,0 +1,450 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { ProcedureError } from '../../core/errors.js'
+import type {
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from '../../core/types.js'
+import { defineErrorTaxonomy } from './taxonomy.js'
+import { dispatchMidStreamError, dispatchPreStreamError } from './dispatch.js'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string) {
+    super(externalMsg)
+    this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+const rpcProcedure = {
+  name: 'DoThing',
+  kind: 'rpc',
+  config: {},
+  handler: async () => {},
+} as unknown as TProcedureRegistration
+
+const streamProcedure = {
+  name: 'Watch',
+  kind: 'rpc-stream',
+  config: {},
+  handler: async function* () {},
+} as unknown as TStreamProcedureRegistration<any, any>
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// dispatchPreStreamError
+// ---------------------------------------------------------------------------
+
+describe('dispatchPreStreamError', () => {
+  test('taxonomy match returns { type: body } with status and serialized body', async () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err: UseCaseError) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const result = await dispatchPreStreamError({
+      err: new UseCaseError('nope'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { errors: taxonomy },
+    })
+    expect(result).toEqual({
+      type: 'body',
+      statusCode: 422,
+      body: { name: 'UseCaseError', message: 'nope' },
+    })
+  })
+
+  test('taxonomy onCatch side effect runs before the result is returned', async () => {
+    const calls: string[] = []
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch: async () => {
+          await new Promise((r) => setTimeout(r, 5))
+          calls.push('onCatch')
+        },
+      },
+    })
+    const result = await dispatchPreStreamError({
+      err: new UseCaseError('nope'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { errors: taxonomy },
+    })
+    expect(result.type).toBe('body')
+    expect(calls).toEqual(['onCatch'])
+  })
+
+  test('unknownError handles non-taxonomy errors via { type: body }', async () => {
+    const result = await dispatchPreStreamError({
+      err: new Error('boom'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: {
+        unknownError: {
+          statusCode: 502,
+          toResponse: () => ({ name: 'InternalServerError' }),
+        },
+      },
+    })
+    expect(result).toEqual({
+      type: 'body',
+      statusCode: 502,
+      body: { name: 'InternalServerError' },
+    })
+  })
+
+  test('hard default: { error: message } with status 500 when nothing is configured', async () => {
+    const result = await dispatchPreStreamError({
+      err: new Error('kaput'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: {},
+    })
+    expect(result).toEqual({
+      type: 'body',
+      statusCode: 500,
+      body: { error: 'kaput' },
+    })
+  })
+
+  test('imperative onError produces { type: response } with the framework response', async () => {
+    const frameworkResponse = { marker: 'framework-response' }
+    const result = await dispatchPreStreamError({
+      err: new Error('boom'),
+      procedure: rpcProcedure,
+      raw: { marker: 'raw' },
+      cfg: {
+        onError: async (procedure, raw, err) => {
+          expect(procedure).toBe(rpcProcedure)
+          expect(raw).toEqual({ marker: 'raw' })
+          expect(err.message).toBe('boom')
+          return frameworkResponse
+        },
+      },
+    })
+    expect(result.type).toBe('response')
+    expect((result as { type: 'response'; response: unknown }).response).toBe(frameworkResponse)
+  })
+
+  test('taxonomy wins over onError when both are configured', async () => {
+    const onError = vi.fn(async () => ({ marker: 'never' }))
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: { class: UseCaseError, statusCode: 422 },
+    })
+    const result = await dispatchPreStreamError({
+      err: new UseCaseError('nope'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { errors: taxonomy, onError },
+    })
+    expect(result.type).toBe('body')
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  test('onError is reached when the taxonomy does not match', async () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: { class: UseCaseError, statusCode: 422 },
+    })
+    const result = await dispatchPreStreamError({
+      err: new Error('not a use-case error'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { errors: taxonomy, onError: async () => 'imperative' },
+    })
+    expect(result).toEqual({ type: 'response', response: 'imperative' })
+  })
+
+  test('onRequestError observer is awaited BEFORE dispatch and cannot mutate the response', async () => {
+    const order: string[] = []
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch: () => {
+          order.push('onCatch')
+        },
+      },
+    })
+    const result = await dispatchPreStreamError({
+      err: new UseCaseError('nope'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: {
+        errors: taxonomy,
+        onRequestError: async ({ err, procedure, raw }) => {
+          await new Promise((r) => setTimeout(r, 5))
+          expect((err as Error).message).toBe('nope')
+          expect(procedure).toBe(rpcProcedure)
+          expect(raw).toEqual({})
+          order.push('observer')
+        },
+      },
+    })
+    expect(order).toEqual(['observer', 'onCatch'])
+    // Observer can't change the outcome — taxonomy still resolves.
+    expect(result.type).toBe('body')
+  })
+
+  test('onRequestError throws are swallowed (console.error) and dispatch proceeds', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const result = await dispatchPreStreamError({
+      err: new Error('boom'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: {
+        onRequestError: () => {
+          throw new Error('observer exploded')
+        },
+      },
+    })
+    expect(errorSpy).toHaveBeenCalledOnce()
+    expect(String(errorSpy.mock.calls[0]![0])).toContain('onRequestError')
+    expect(result).toEqual({ type: 'body', statusCode: 500, body: { error: 'boom' } })
+  })
+
+  test('order: observer → taxonomy → onError → hard default', async () => {
+    const order: string[] = []
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        onCatch: () => {
+          order.push('taxonomy')
+        },
+      },
+    })
+    const cfg = {
+      errors: taxonomy,
+      onRequestError: () => {
+        order.push('observer')
+      },
+      onError: async () => {
+        order.push('onError')
+        return 'resp'
+      },
+    }
+
+    // 1. Taxonomy match: observer then taxonomy; onError skipped.
+    await dispatchPreStreamError({
+      err: new UseCaseError('x'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg,
+    })
+    expect(order).toEqual(['observer', 'taxonomy'])
+
+    // 2. No taxonomy match: observer then onError.
+    order.length = 0
+    await dispatchPreStreamError({
+      err: new Error('y'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg,
+    })
+    expect(order).toEqual(['observer', 'onError'])
+
+    // 3. Nothing configured beyond the observer: hard default.
+    order.length = 0
+    const result = await dispatchPreStreamError({
+      err: new Error('z'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { onRequestError: cfg.onRequestError },
+    })
+    expect(order).toEqual(['observer'])
+    expect(result).toEqual({ type: 'body', statusCode: 500, body: { error: 'z' } })
+  })
+
+  test('unwraps a ProcedureError wrapper — cause is matched before the outer error', async () => {
+    const original = new UseCaseError('the real problem')
+    const wrapped = new ProcedureError('DoThing', 'wrapped')
+    ;(wrapped as { cause?: unknown }).cause = original
+
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err: UseCaseError) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const result = await dispatchPreStreamError({
+      err: wrapped,
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: { errors: taxonomy },
+    })
+    expect(result).toEqual({
+      type: 'body',
+      statusCode: 422,
+      body: { name: 'UseCaseError', message: 'the real problem' },
+    })
+  })
+
+  test('direct ProcedureError (no cause) hits the default taxonomy entry', async () => {
+    const result = await dispatchPreStreamError({
+      err: new ProcedureError('DoThing', 'from ctx.error'),
+      procedure: rpcProcedure,
+      raw: {},
+      cfg: {},
+    })
+    expect(result.type).toBe('body')
+    const bodyResult = result as { type: 'body'; statusCode: number; body: any }
+    expect(bodyResult.statusCode).toBe(500)
+    expect(bodyResult.body.name).toBe('ProcedureError')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// dispatchMidStreamError
+// ---------------------------------------------------------------------------
+
+describe('dispatchMidStreamError', () => {
+  test('taxonomy match returns { data, sseEvent: error, runOnCatch }', async () => {
+    const calls: string[] = []
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err: UseCaseError) => ({ name: 'UseCaseError', message: err.externalMsg }),
+        onCatch: () => {
+          calls.push('onCatch')
+        },
+      },
+    })
+    const result = await dispatchMidStreamError({
+      err: new UseCaseError('mid-stream nope'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: { errors: taxonomy },
+    })
+    expect(result.data).toEqual({ name: 'UseCaseError', message: 'mid-stream nope' })
+    expect(result.sseEvent).toBe('error')
+    expect(result.runOnCatch).toBeDefined()
+    // onCatch is deferred — caller decides when to run it.
+    expect(calls).toEqual([])
+    await result.runOnCatch!()
+    expect(calls).toEqual(['onCatch'])
+  })
+
+  test('onMidStreamError fallback returns { data, sseEvent: procedure.name }', async () => {
+    const result = await dispatchMidStreamError({
+      err: new Error('boom'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: {
+        onMidStreamError: (procedure, _raw, err) => ({
+          data: { custom: true, from: procedure.name, message: err.message },
+        }),
+      },
+    })
+    expect(result.data).toEqual({ custom: true, from: 'Watch', message: 'boom' })
+    expect(result.sseEvent).toBe('Watch')
+    expect(result.runOnCatch).toBeUndefined()
+  })
+
+  test('taxonomy wins over onMidStreamError when both are configured', async () => {
+    const onMidStreamError = vi.fn(() => ({ data: { never: true } }))
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: { class: UseCaseError, statusCode: 422 },
+    })
+    const result = await dispatchMidStreamError({
+      err: new UseCaseError('nope'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: { errors: taxonomy, onMidStreamError },
+    })
+    expect(result.sseEvent).toBe('error')
+    expect(onMidStreamError).not.toHaveBeenCalled()
+  })
+
+  test('onMidStreamError returning undefined data falls through to the hard default', async () => {
+    const result = await dispatchMidStreamError({
+      err: new Error('boom'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: { onMidStreamError: () => undefined },
+    })
+    expect(result.data).toEqual({ error: 'boom' })
+    expect(result.sseEvent).toBe('error')
+  })
+
+  test('hard default: { data: { error }, sseEvent: error } when nothing is configured', async () => {
+    const result = await dispatchMidStreamError({
+      err: new Error('stream died'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: {},
+    })
+    expect(result).toEqual({
+      data: { error: 'stream died' },
+      sseEvent: 'error',
+    })
+  })
+
+  test('onRequestError observer is awaited before mid-stream dispatch', async () => {
+    const order: string[] = []
+    const result = await dispatchMidStreamError({
+      err: new Error('boom'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: {
+        onRequestError: async () => {
+          await new Promise((r) => setTimeout(r, 5))
+          order.push('observer')
+        },
+        onMidStreamError: () => {
+          order.push('onMidStreamError')
+          return { data: { handled: true } }
+        },
+      },
+    })
+    expect(order).toEqual(['observer', 'onMidStreamError'])
+    expect(result.data).toEqual({ handled: true })
+  })
+
+  test('onRequestError throws are swallowed (console.error) in the mid-stream path', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const result = await dispatchMidStreamError({
+      err: new Error('boom'),
+      procedure: streamProcedure,
+      raw: {},
+      cfg: {
+        onRequestError: () => {
+          throw new Error('observer exploded')
+        },
+      },
+    })
+    expect(errorSpy).toHaveBeenCalledOnce()
+    expect(String(errorSpy.mock.calls[0]![0])).toContain('mid-stream')
+    expect(result.data).toEqual({ error: 'boom' })
+  })
+
+  test('unwraps a ProcedureError wrapper in the mid-stream path', async () => {
+    const original = new UseCaseError('inner')
+    const wrapped = new ProcedureError('Watch', 'wrapped')
+    ;(wrapped as { cause?: unknown }).cause = original
+
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err: UseCaseError) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const result = await dispatchMidStreamError({
+      err: wrapped,
+      procedure: streamProcedure,
+      raw: {},
+      cfg: { errors: taxonomy },
+    })
+    expect(result.data).toEqual({ name: 'UseCaseError', message: 'inner' })
+    expect(result.sseEvent).toBe('error')
+  })
+})

package/src/server/errors/dispatch.ts

@@ -0,0 +1,189 @@
+/**
+ * Transport-agnostic error dispatch.
+ *
+ * Unlike v8 (where dispatch produced Hono `Response` objects directly), v9
+ * dispatch returns plain data and the server adapter translates it into its
+ * framework's response primitive. `TRaw` is the adapter's request context
+ * (Hono `Context`, Fastify `Request`, ...) and `TResponse` its response type —
+ * both flow through untouched.
+ */
+import {
+  resolveErrorResponse,
+  type ErrorTaxonomy,
+  type TAnyProcedureRegistration,
+  type UnknownErrorConfig,
+} from './taxonomy.js'
+import type {
+  TStreamProcedureRegistration,
+  THttpStreamProcedureRegistration,
+} from '../../core/types.js'
+
+/** Public alias of {@link TAnyProcedureRegistration}. */
+export type AnyServedProcedure = TAnyProcedureRegistration
+
+export type OnRequestErrorContext<TRaw = unknown> = {
+  err: unknown
+  procedure: AnyServedProcedure
+  raw: TRaw
+}
+
+/**
+ * Cross-cutting observer for logging/tracing — fires for every caught error
+ * BEFORE dispatch. Awaited; cannot mutate the response; throws are swallowed.
+ */
+export type OnRequestErrorObserver<TRaw = unknown> = (
+  ctx: OnRequestErrorContext<TRaw>,
+) => void | Promise<void>
+
+/** Imperative error handler — produces a framework response directly. */
+export type PreStreamOnError<TRaw = unknown, TResponse = unknown> = (
+  procedure: AnyServedProcedure,
+  raw: TRaw,
+  err: Error,
+) => TResponse | Promise<TResponse>
+
+export type PreStreamErrorConfig<TRaw = unknown, TResponse = unknown> = {
+  errors?: ErrorTaxonomy
+  unknownError?: UnknownErrorConfig
+  onError?: PreStreamOnError<TRaw, TResponse>
+  onRequestError?: OnRequestErrorObserver<TRaw>
+}
+
+/**
+ * What the adapter should send. Either resolved data (taxonomy / unknownError /
+ * hard default — serialize `body` as JSON with `statusCode`) or a framework
+ * response produced by the imperative `onError` callback (send as-is).
+ */
+export type PreStreamDispatchResult<TResponse = unknown> =
+  | { type: 'body'; statusCode: number; body: unknown }
+  | { type: 'response'; response: TResponse }
+
+/**
+ * Used by rpc, http, and the pre-stream guard in stream / http-stream
+ * handlers. Order: onRequestError observer (awaited, throws swallowed) →
+ * taxonomy resolver → imperative onError → hard default
+ * (`{ error: message }`, 500).
+ */
+export async function dispatchPreStreamError<TRaw, TResponse>(params: {
+  err: unknown
+  procedure: AnyServedProcedure
+  raw: TRaw
+  cfg: PreStreamErrorConfig<TRaw, TResponse>
+}): Promise<PreStreamDispatchResult<TResponse>> {
+  const { err, procedure, raw, cfg } = params
+
+  if (cfg.onRequestError) {
+    try {
+      await cfg.onRequestError({ err, procedure, raw })
+    } catch (observerErr) {
+      console.error('[ts-procedures] onRequestError threw — swallowed:', observerErr)
+    }
+  }
+
+  const resolved = resolveErrorResponse({
+    err,
+    userTaxonomy: cfg.errors,
+    unknownError: cfg.unknownError,
+    procedure,
+    raw,
+  })
+  if (resolved) {
+    await resolved.runOnCatch()
+    return { type: 'body', statusCode: resolved.statusCode, body: resolved.body }
+  }
+
+  if (cfg.onError) {
+    return { type: 'response', response: await cfg.onError(procedure, raw, err as Error) }
+  }
+
+  return { type: 'body', statusCode: 500, body: { error: (err as Error).message } }
+}
+
+/**
+ * Return shape of an `onMidStreamError` callback.
+ *
+ * - `data`: the value to write to the open stream as the error payload.
+ *   Decorate with the `sse(data, { event, id, retry })` helper to attach SSE
+ *   metadata; the stream handler reads that metadata via `getSSEMeta` after
+ *   dispatch.
+ * - `closeStream`: reserved for future use. The stream currently always
+ *   closes naturally after the catch block returns.
+ */
+export type MidStreamErrorResult<TErrorData = unknown> = {
+  data: TErrorData
+  closeStream?: boolean
+}
+
+export type OnMidStreamError<TErrorData = unknown, TRaw = unknown> = (
+  procedure: TStreamProcedureRegistration<any, any> | THttpStreamProcedureRegistration<any>,
+  raw: TRaw,
+  err: Error,
+) => MidStreamErrorResult<TErrorData> | undefined
+
+export type MidStreamErrorConfig<TErrorData = unknown, TRaw = unknown> = {
+  errors?: ErrorTaxonomy
+  unknownError?: UnknownErrorConfig
+  onMidStreamError?: OnMidStreamError<TErrorData, TRaw>
+  onRequestError?: OnRequestErrorObserver<TRaw>
+}
+
+export type DispatchedMidStreamError = {
+  data: unknown
+  sseEvent?: string
+  sseId?: string
+  sseRetry?: number
+  runOnCatch?: () => Promise<void>
+}
+
+/**
+ * Used inside SSE / text-stream generator catch blocks. Returns the bytes
+ * to write to the open stream — the HTTP status is already committed, so a
+ * Response is impossible. Order matches dispatchPreStreamError: observer
+ * (awaited, throws swallowed) → taxonomy → onMidStreamError → hard default.
+ */
+export async function dispatchMidStreamError<TErrorData, TRaw>(params: {
+  err: unknown
+  procedure: TStreamProcedureRegistration<any, any> | THttpStreamProcedureRegistration<any>
+  raw: TRaw
+  cfg: MidStreamErrorConfig<TErrorData, TRaw>
+}): Promise<DispatchedMidStreamError> {
+  const { err, procedure, raw, cfg } = params
+
+  if (cfg.onRequestError) {
+    try {
+      await cfg.onRequestError({ err, procedure, raw })
+    } catch (observerErr) {
+      console.error('[ts-procedures] onRequestError (mid-stream) threw — swallowed:', observerErr)
+    }
+  }
+
+  const resolved = resolveErrorResponse({
+    err,
+    userTaxonomy: cfg.errors,
+    unknownError: cfg.unknownError,
+    procedure,
+    raw,
+  })
+  if (resolved) {
+    return {
+      data: resolved.body,
+      sseEvent: 'error',
+      runOnCatch: resolved.runOnCatch,
+    }
+  }
+
+  if (cfg.onMidStreamError) {
+    const result = cfg.onMidStreamError(procedure, raw, err as Error)
+    if (result?.data !== undefined) {
+      return {
+        data: result.data,
+        sseEvent: procedure.name,
+      }
+    }
+  }
+
+  return {
+    data: { error: (err as Error).message },
+    sseEvent: 'error',
+  }
+}