ts-procedures 8.6.0 → 9.0.0

package/src/implementations/http/error-dispatch.test.ts

@@ -1,283 +0,0 @@
-import { describe, expect, test, vi } from 'vitest'
-import { Hono } from 'hono'
-import { dispatchMidStreamError, dispatchPreStreamError } from './error-dispatch.js'
-import { defineErrorTaxonomy } from './error-taxonomy.js'
-import { ProcedureValidationError } from '../../errors.js'
-
-function makeContext() {
-  return new Promise<import('hono').Context>((resolve) => {
-    const app = new Hono()
-    app.get('/', (c) => {
-      resolve(c)
-      return c.text('ok')
-    })
-    app.request('/')
-  })
-}
-
-const dummyProcedure = {
-  name: 'Test',
-  kind: 'rpc',
-  config: { scope: 'test', version: 1 },
-  handler: async () => undefined,
-} as any
-
-describe('dispatchPreStreamError', () => {
-  test('default taxonomy: ProcedureValidationError → 400', async () => {
-    const c = await makeContext()
-    const err = new ProcedureValidationError('Test', 'Validation error for Test', [
-      { instancePath: '/x', message: 'expected number' } as any,
-    ])
-
-    const res = await dispatchPreStreamError({
-      err,
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: {},
-    })
-
-    expect(res.status).toBe(400)
-    const body = await res.json()
-    expect(body.name).toBe('ProcedureValidationError')
-    expect(body.procedureName).toBe('Test')
-  })
-
-  test('user taxonomy entry takes precedence', async () => {
-    const c = await makeContext()
-    class MyError extends Error {
-      constructor(public reason: string) { super(reason) }
-    }
-    const errors = defineErrorTaxonomy({
-      MyError: { class: MyError, statusCode: 422, toResponse: (e) => ({ name: 'MyError', reason: e.reason }) },
-    })
-
-    const res = await dispatchPreStreamError({
-      err: new MyError('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(res.status).toBe(422)
-    expect(await res.json()).toEqual({ name: 'MyError', reason: 'boom' })
-  })
-
-  test('falls back to onError imperative callback', async () => {
-    const c = await makeContext()
-    const onError = vi.fn().mockResolvedValue(c.json({ ok: false }, 503))
-
-    const res = await dispatchPreStreamError({
-      err: new Error('unmatched'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { onError: (proc, raw, e) => onError(proc, raw, e) },
-    })
-
-    expect(onError).toHaveBeenCalled()
-    expect(res.status).toBe(503)
-  })
-
-  test('hard default 500 when nothing matches', async () => {
-    const c = await makeContext()
-    const res = await dispatchPreStreamError({
-      err: new Error('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: {},
-    })
-    expect(res.status).toBe(500)
-    expect(await res.json()).toEqual({ error: 'boom' })
-  })
-
-  test('onRequestError observer fires before dispatch and is awaited', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    const onRequestError = vi.fn(async () => {
-      calls.push('observer')
-    })
-    const errors = defineErrorTaxonomy({
-      AnyError: {
-        match: (e): e is Error => e instanceof Error,
-        statusCode: 500,
-        toResponse: () => {
-          calls.push('toResponse')
-          return { name: 'AnyError' }
-        },
-      },
-    })
-
-    await dispatchPreStreamError({
-      err: new Error('x'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors, onRequestError },
-    })
-
-    expect(calls).toEqual(['observer', 'toResponse'])
-    expect(onRequestError).toHaveBeenCalledWith({ err: expect.any(Error), procedure: dummyProcedure, raw: c })
-  })
-
-  test('observer throw is swallowed and logged', async () => {
-    const c = await makeContext()
-    const consoleErr = vi.spyOn(console, 'error').mockImplementation(() => {})
-    const onRequestError = vi.fn(() => { throw new Error('observer broke') })
-
-    const res = await dispatchPreStreamError({
-      err: new Error('x'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { onRequestError },
-    })
-
-    expect(res.status).toBe(500)
-    expect(consoleErr).toHaveBeenCalled()
-    consoleErr.mockRestore()
-  })
-
-  test('taxonomy onCatch is fully awaited before the response body is written', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    class HookedError extends Error {}
-    const errors = defineErrorTaxonomy({
-      HookedError: {
-        class: HookedError,
-        statusCode: 500,
-        toResponse: () => ({ name: 'HookedError' }),
-        onCatch: async () => {
-          // Awaiting an async setTimeout here means a non-awaiting dispatcher
-          // would write the response BEFORE this push runs. The order we capture
-          // in `calls` reveals which branch happened.
-          await new Promise<void>((resolve) => setTimeout(resolve, 5))
-          calls.push('oncatch-done')
-        },
-      },
-    })
-
-    // Spy on c.json: when the dispatcher writes the response, record where in
-    // the timeline it happened relative to onCatch's push.
-    const originalJson = c.json.bind(c) as (...args: any[]) => Response
-    const jsonSpy = vi.fn((...args: any[]) => {
-      calls.push('response-write')
-      return originalJson(...args)
-    })
-    ;(c as any).json = jsonSpy
-
-    const res = await dispatchPreStreamError({
-      err: new HookedError('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(res.status).toBe(500)
-    expect(jsonSpy).toHaveBeenCalledTimes(1)
-    // If the dispatcher awaits onCatch first, 'oncatch-done' precedes
-    // 'response-write'. Without the await, the order would be reversed
-    // (or 'oncatch-done' would land after the dispatcher returns).
-    expect(calls).toEqual(['oncatch-done', 'response-write'])
-  })
-})
-
-const streamProcedure = {
-  name: 'Tail',
-  kind: 'rpc-stream',
-  config: { scope: 'logs', version: 1 },
-  handler: async function* () {},
-} as any
-
-describe('dispatchMidStreamError', () => {
-  test('uses taxonomy body when configured', async () => {
-    const c = await makeContext()
-    class MidErr extends Error {}
-    const errors = defineErrorTaxonomy({
-      MidErr: { class: MidErr, statusCode: 500, toResponse: () => ({ name: 'MidErr', detail: 'x' }) },
-    })
-
-    const result = await dispatchMidStreamError({
-      err: new MidErr('mid'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(result.data).toEqual({ name: 'MidErr', detail: 'x' })
-    expect(result.sseEvent).toBe('error')
-    expect(result.runOnCatch).toBeTypeOf('function')
-  })
-
-  test('falls back to onMidStreamError', async () => {
-    const c = await makeContext()
-    const result = await dispatchMidStreamError({
-      err: new Error('boom'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: {
-        onMidStreamError: () => ({ data: { kind: 'fail', msg: 'boom' } }),
-      },
-    })
-
-    expect(result.data).toEqual({ kind: 'fail', msg: 'boom' })
-    expect(result.sseEvent).toBe('Tail') // procedure name override
-  })
-
-  test('hard default { error: msg } when nothing matches', async () => {
-    const c = await makeContext()
-    const result = await dispatchMidStreamError({
-      err: new Error('plain'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: {},
-    })
-
-    expect(result.data).toEqual({ error: 'plain' })
-    expect(result.sseEvent).toBe('error')
-  })
-
-  test('onRequestError observer fires before dispatch (mid-stream form)', async () => {
-    const c = await makeContext()
-    const onRequestError = vi.fn(async () => {})
-
-    await dispatchMidStreamError({
-      err: new Error('x'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { onRequestError },
-    })
-
-    expect(onRequestError).toHaveBeenCalled()
-  })
-
-  test('returns a runOnCatch function that is invokable and awaits the taxonomy hook', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    class StreamErr extends Error {}
-    const errors = defineErrorTaxonomy({
-      StreamErr: {
-        class: StreamErr,
-        statusCode: 500,
-        toResponse: () => ({ name: 'StreamErr' }),
-        onCatch: async () => {
-          await new Promise<void>((resolve) => setTimeout(resolve, 5))
-          calls.push('oncatch-done')
-        },
-      },
-    })
-
-    // Mid-stream contract: the dispatcher does NOT call runOnCatch itself —
-    // the caller (stream handler) decides when to invoke it. Verify the shape
-    // and that awaiting it actually awaits the hook.
-    const result = await dispatchMidStreamError({
-      err: new StreamErr('mid'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(result.runOnCatch).toBeTypeOf('function')
-    // Hook has not yet run — caller hasn't invoked it.
-    expect(calls).toEqual([])
-
-    await result.runOnCatch!()
-    expect(calls).toEqual(['oncatch-done'])
-  })
-})

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

@@ -1,176 +0,0 @@
-import type { Context } from 'hono'
-import {
-  resolveErrorResponse,
-  type ErrorTaxonomy,
-  type TAnyProcedureRegistration,
-  type UnknownErrorConfig,
-} from './error-taxonomy.js'
-import type { TStreamProcedureRegistration, THttpStreamProcedureRegistration } from '../../types.js'
-
-/**
- * Public alias of {@link TAnyProcedureRegistration} — re-exported here so the
- * hono/ module can import it from one place without taking a direct dependency
- * on error-taxonomy internals. Single source of truth lives in
- * error-taxonomy.ts.
- */
-export type AnyProcedureRegistration = TAnyProcedureRegistration
-
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: AnyProcedureRegistration
-  raw: Context
-}
-
-export type OnRequestErrorObserver = (
-  ctx: OnRequestErrorContext,
-) => void | Promise<void>
-
-export type PreStreamOnError = (
-  procedure: AnyProcedureRegistration,
-  raw: Context,
-  err: Error,
-) => Response | Promise<Response>
-
-export type PreStreamErrorConfig = {
-  errors?: ErrorTaxonomy
-  unknownError?: UnknownErrorConfig
-  onError?: PreStreamOnError
-  onRequestError?: OnRequestErrorObserver
-}
-
-/**
- * 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 500.
- */
-export async function dispatchPreStreamError(params: {
-  err: unknown
-  procedure: AnyProcedureRegistration
-  raw: Context
-  cfg: PreStreamErrorConfig
-}): Promise<Response> {
-  const { err, procedure, raw, cfg } = params
-
-  if (cfg.onRequestError) {
-    try {
-      await cfg.onRequestError({ err, procedure, raw })
-    } catch (observerErr) {
-      console.error(
-        '[ts-procedures hono] onRequestError threw — swallowed:',
-        observerErr,
-      )
-    }
-  }
-
-  const resolved = resolveErrorResponse({
-    err,
-    userTaxonomy: cfg.errors,
-    unknownError: cfg.unknownError,
-    procedure,
-    raw,
-  })
-  if (resolved) {
-    await resolved.runOnCatch()
-    return raw.json(resolved.body, resolved.statusCode as never)
-  }
-
-  if (cfg.onError) {
-    return cfg.onError(procedure, raw, err as Error)
-  }
-
-  return raw.json({ error: (err as Error).message }, 500)
-}
-
-/**
- * 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 from
- *   `hono/handlers/stream` 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; this flag is kept on
- *   the public type for forward compatibility but the dispatcher does not
- *   read it.
- */
-export type MidStreamErrorResult<TErrorData = unknown> = {
-  data: TErrorData
-  closeStream?: boolean
-}
-
-export type OnMidStreamError<TErrorData = unknown> = (
-  procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
-  raw: Context,
-  err: Error,
-) => MidStreamErrorResult<TErrorData> | undefined
-
-export type MidStreamErrorConfig<TErrorData = unknown> = {
-  errors?: ErrorTaxonomy
-  unknownError?: UnknownErrorConfig
-  onMidStreamError?: OnMidStreamError<TErrorData>
-  onRequestError?: OnRequestErrorObserver
-}
-
-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 we
- * can't return a Response. Order matches dispatchPreStreamError: observer
- * (awaited, throws swallowed) → taxonomy → onMidStreamError → hard default.
- */
-export async function dispatchMidStreamError<TErrorData = unknown>(params: {
-  err: unknown
-  procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>
-  raw: Context
-  cfg: MidStreamErrorConfig<TErrorData>
-}): Promise<DispatchedMidStreamError> {
-  const { err, procedure, raw, cfg } = params
-
-  if (cfg.onRequestError) {
-    try {
-      await cfg.onRequestError({ err, procedure, raw })
-    } catch (observerErr) {
-      console.error(
-        '[ts-procedures hono] 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',
-  }
-}

package/src/implementations/http/hono/handlers/http-stream.ts

@@ -1,152 +0,0 @@
-import type { Context, Hono } from 'hono'
-import { streamSSE } from 'hono/streaming'
-import type { THttpStreamProcedureRegistration } from '../../../../types.js'
-import type { HttpMethod } from '../../../types.js'
-import { dispatchMidStreamError, dispatchPreStreamError } from '../../error-dispatch.js'
-import { buildHttpStreamRouteDoc } from '../docs/http-stream-doc.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, QueryParser } from '../types.js'
-
-const BODY_METHODS: HttpMethod[] = ['post', 'put', 'patch']
-
-function parseQueryNative(queryString: string): Record<string, unknown> {
-  const sp = new URLSearchParams(queryString)
-  const result: Record<string, unknown> = {}
-  for (const key of new Set(sp.keys())) {
-    const values = sp.getAll(key)
-    result[key] = values.length > 1 ? values : values[0]
-  }
-  return result
-}
-
-function extractQuery(url: string, parser: QueryParser): Record<string, unknown> {
-  const q = url.indexOf('?')
-  if (q === -1) return {}
-  const raw = url.slice(q + 1)
-  return raw ? parser(raw) : {}
-}
-
-async function extractParams(
-  c: Context,
-  method: HttpMethod,
-  reqSchema: Record<string, unknown>,
-  parser: QueryParser,
-): Promise<Record<string, unknown>> {
-  const params: Record<string, unknown> = {}
-  for (const channel of Object.keys(reqSchema)) {
-    switch (channel) {
-      case 'pathParams':
-        params.pathParams = c.req.param()
-        break
-      case 'query':
-        params.query = extractQuery(c.req.url, parser)
-        break
-      case 'body':
-        if (BODY_METHODS.includes(method)) {
-          params.body = await c.req.json().catch(() => ({}))
-        }
-        break
-      case 'headers': {
-        const obj: Record<string, string> = {}
-        c.req.raw.headers.forEach((v, k) => { obj[k] = v })
-        params.headers = obj
-        break
-      }
-      default:
-        params[channel] = undefined
-    }
-  }
-  return params
-}
-
-export function installHttpStreamRoute(params: {
-  app: Hono
-  procedure: THttpStreamProcedureRegistration<any>
-  factoryItem: HonoFactoryItem
-  cfg: HonoAppBuilderConfig
-  docs: DocAccumulator
-}): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
-  const queryParser = cfg.api?.queryParser ?? parseQueryNative
-
-  const route = buildHttpStreamRouteDoc(
-    procedure,
-    cfg.pathPrefix,
-    factoryItem.extendProcedureDoc as any,
-  )
-  docs.push(route)
-
-  const reqSchema = procedure.config.schema?.req
-
-  app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
-    try {
-      const context =
-        typeof factoryItem.factoryContext === 'function'
-          ? await (factoryItem.factoryContext as (c: Context) => any)(c)
-          : factoryItem.factoryContext
-
-      const reqParams = reqSchema
-        ? await extractParams(c, procedure.config.method, reqSchema as Record<string, unknown>, queryParser)
-        : undefined
-
-      const { stream: gen, initialHeaders } = await procedure.handler(
-        { ...context, signal: c.req.raw.signal },
-        reqParams,
-      )
-
-      if (initialHeaders) {
-        for (const [k, v] of Object.entries(initialHeaders)) c.header(k, v)
-      }
-
-      cfg.stream?.onStreamStart?.(procedure, c, 'sse')
-
-      return streamSSE(c, async (stream) => {
-        let eventId = 0
-        try {
-          let it = await gen.next()
-          while (!it.done) {
-            const data = typeof it.value === 'string' ? it.value : JSON.stringify(it.value)
-            await stream.writeSSE({ data, event: procedure.name, id: String(eventId++) })
-            it = await gen.next()
-          }
-          if (it.value !== undefined) {
-            const data = typeof it.value === 'string' ? it.value : JSON.stringify(it.value)
-            await stream.writeSSE({ data, event: 'return', id: String(eventId++) })
-          }
-        } catch (error) {
-          const dispatched = await dispatchMidStreamError({
-            err: error,
-            procedure,
-            raw: c,
-            cfg: {
-              errors: cfg.errors,
-              unknownError: cfg.unknownError,
-              onMidStreamError: cfg.stream?.onMidStreamError,
-              onRequestError: cfg.onRequestError,
-            },
-          })
-          await stream.writeSSE({
-            data: typeof dispatched.data === 'string' ? dispatched.data : JSON.stringify(dispatched.data),
-            event: dispatched.sseEvent ?? 'error',
-            id: String(eventId++),
-          })
-          if (dispatched.runOnCatch) await dispatched.runOnCatch()
-        } finally {
-          cfg.stream?.onStreamEnd?.(procedure, c, 'sse')
-          cfg.onRequestEnd?.(c)
-        }
-      })
-    } catch (error) {
-      return dispatchPreStreamError({
-        err: error,
-        procedure,
-        raw: c,
-        cfg: {
-          errors: cfg.errors,
-          unknownError: cfg.unknownError,
-          onError: cfg.onError,
-          onRequestError: cfg.onRequestError,
-        },
-      })
-    }
-  })
-}