ts-procedures 8.5.0 → 9.0.0

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,
-        },
-      })
-    }
-  })
-}

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

@@ -1,145 +0,0 @@
-import type { Context, Hono } from 'hono'
-import type { THttpProcedureRegistration } from '../../../../types.js'
-import type { HttpMethod } from '../../../types.js'
-import { dispatchPreStreamError } from '../../error-dispatch.js'
-import { buildHttpRouteDoc } from '../docs/http-doc.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, QueryParser } from '../types.js'
-
-const BODY_METHODS: HttpMethod[] = ['post', 'put', 'patch']
-
-function defaultSuccessStatus(method: HttpMethod): number {
-  switch (method) {
-    case 'post':   return 201
-    case 'delete': return 204
-    default:       return 200
-  }
-}
-
-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 installHttpRoute(params: {
-  app: Hono
-  procedure: THttpProcedureRegistration<any>
-  factoryItem: HonoFactoryItem
-  cfg: HonoAppBuilderConfig
-  docs: DocAccumulator
-}): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
-  const queryParser = cfg.api?.queryParser ?? parseQueryNative
-
-  const route = buildHttpRouteDoc(
-    procedure,
-    cfg.pathPrefix,
-    factoryItem.extendProcedureDoc as any,
-  )
-  docs.push(route)
-
-  const successStatus = procedure.config.successStatus ?? defaultSuccessStatus(procedure.config.method)
-  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, queryParser)
-        : undefined
-
-      const result = await procedure.handler(
-        { ...context, signal: c.req.raw.signal },
-        reqParams,
-      )
-
-      cfg.api?.onSuccess?.(procedure, c)
-
-      // The `{ body, headers }` envelope is OPT-IN via `schema.res.headers`: when
-      // the route declares response headers, the handler returns `{ body, headers }`;
-      // otherwise its return value IS the body. Gating on the schema (rather than
-      // duck-typing the result for a `body`/`headers` key) lets a domain object
-      // safely carry its own `body`/`headers` field without being unwrapped.
-      // Normalize both shapes to a single `{ body, headers }` so the response
-      // decision below is uniform for every legal return shape.
-      const hasResHeaders = procedure.config.schema?.res?.headers != null
-      const { body, headers } = hasResHeaders
-        ? ((result ?? {}) as { body?: unknown; headers?: unknown })
-        : { body: result, headers: undefined }
-
-      if (headers && typeof headers === 'object') {
-        for (const [k, v] of Object.entries(headers as Record<string, string>)) c.header(k, v)
-      }
-
-      // No body to send — a 204 status, or an `undefined` return (a `void`
-      // handler, or a headers-only `res: { headers }` envelope). Emit a clean
-      // bodyless response instead of `c.json(undefined)`, which would send an
-      // empty, unparseable body under an `application/json` content-type.
-      if (successStatus === 204 || body === undefined) {
-        return c.body(null, successStatus as any)
-      }
-
-      return c.json(body, successStatus as any)
-    } catch (error) {
-      return dispatchPreStreamError({
-        err: error,
-        procedure,
-        raw: c,
-        cfg: {
-          errors: cfg.errors,
-          unknownError: cfg.unknownError,
-          onError: cfg.onError,
-          onRequestError: cfg.onRequestError,
-        },
-      })
-    }
-  })
-}

package/src/implementations/http/hono/handlers/rpc.ts

@@ -1,54 +0,0 @@
-import type { Context, Hono } from 'hono'
-import type { TProcedureRegistration } from '../../../../types.js'
-import type { RPCConfig } from '../../../types.js'
-import { dispatchPreStreamError } from '../../error-dispatch.js'
-import { buildRpcRouteDoc } from '../docs/rpc-doc.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
-
-export function installRpcRoute(params: {
-  app: Hono
-  procedure: TProcedureRegistration<any, RPCConfig>
-  factoryItem: HonoFactoryItem
-  cfg: HonoAppBuilderConfig
-  docs: DocAccumulator
-}): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
-
-  const route = buildRpcRouteDoc(
-    procedure,
-    cfg.pathPrefix,
-    factoryItem.extendProcedureDoc as any,
-  )
-  docs.push(route)
-
-  app.post(route.path, async (c: Context) => {
-    try {
-      const context =
-        typeof factoryItem.factoryContext === 'function'
-          ? await (factoryItem.factoryContext as (c: Context) => any)(c)
-          : factoryItem.factoryContext
-
-      const body = await c.req.json().catch(() => ({}))
-      const result = await procedure.handler(
-        { ...context, signal: c.req.raw.signal },
-        body,
-      )
-
-      cfg.rpc?.onSuccess?.(procedure, c)
-
-      return c.json(result)
-    } catch (error) {
-      return dispatchPreStreamError({
-        err: error,
-        procedure,
-        raw: c,
-        cfg: {
-          errors: cfg.errors,
-          unknownError: cfg.unknownError,
-          onError: cfg.onError,
-          onRequestError: cfg.onRequestError,
-        },
-      })
-    }
-  })
-}

package/src/implementations/http/hono/path.test.ts

@@ -1,96 +0,0 @@
-import { describe, expect, test } from 'vitest'
-import { makeRoutePath, resolveFullPath } from './path.js'
-import type {
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-  THttpProcedureRegistration,
-  THttpStreamProcedureRegistration,
-} from '../../../types.js'
-
-describe('makeRoutePath', () => {
-  test('rpc: scope/name/version with kebab-case', () => {
-    const proc = {
-      name: 'GetUser',
-      kind: 'rpc',
-      config: { scope: 'users', version: 1 },
-      handler: async () => undefined,
-    } as unknown as TProcedureRegistration
-    expect(makeRoutePath({ procedure: proc })).toBe('/users/get-user/1')
-  })
-
-  test('rpc: array scope joined with /', () => {
-    const proc = {
-      name: 'List',
-      kind: 'rpc',
-      config: { scope: ['UserModule', 'admin'], version: 2 },
-      handler: async () => undefined,
-    } as unknown as TProcedureRegistration
-    expect(makeRoutePath({ procedure: proc })).toBe('/user-module/admin/list/2')
-  })
-
-  test('rpc: pathPrefix is normalized (leading slash inserted)', () => {
-    const proc = {
-      name: 'Echo',
-      kind: 'rpc',
-      config: { scope: 'echo', version: 1 },
-      handler: async () => undefined,
-    } as unknown as TProcedureRegistration
-    expect(makeRoutePath({ procedure: proc, prefix: 'api/v1' })).toBe('/api/v1/echo/echo/1')
-  })
-
-  test('rpc-stream: same shape as rpc', () => {
-    const proc = {
-      name: 'Tail',
-      kind: 'rpc-stream',
-      isStream: true,
-      config: { scope: 'logs', version: 1 },
-      handler: async function* () {},
-    } as unknown as TStreamProcedureRegistration
-    expect(makeRoutePath({ procedure: proc, prefix: '/api' })).toBe('/api/logs/tail/1')
-  })
-
-  test('http: prepends prefix to config.path', () => {
-    const proc = {
-      name: 'GetUser',
-      kind: 'http',
-      config: { path: '/users/:id', method: 'get' },
-      handler: async () => undefined,
-    } as unknown as THttpProcedureRegistration
-    expect(makeRoutePath({ procedure: proc, prefix: '/api/v1' })).toBe('/api/v1/users/:id')
-  })
-
-  test('http: leading slash on path is preserved (not duplicated)', () => {
-    const proc = {
-      name: 'Get',
-      kind: 'http',
-      config: { path: 'users', method: 'get' },
-      handler: async () => undefined,
-    } as unknown as THttpProcedureRegistration
-    expect(makeRoutePath({ procedure: proc, prefix: '/api' })).toBe('/api/users')
-  })
-
-  test('http-stream: same shape as http', () => {
-    const proc = {
-      name: 'TailLogs',
-      kind: 'http-stream',
-      config: { path: '/logs/tail', method: 'get' },
-      handler: async () => ({ stream: (async function* () {})(), initialHeaders: undefined }),
-    } as unknown as THttpStreamProcedureRegistration
-    expect(makeRoutePath({ procedure: proc })).toBe('/logs/tail')
-  })
-})
-
-describe('resolveFullPath', () => {
-  test('combines prefix and path', () => {
-    expect(resolveFullPath('/users', '/api/v1')).toBe('/api/v1/users')
-  })
-  test('normalizes prefix without leading slash', () => {
-    expect(resolveFullPath('/users', 'api')).toBe('/api/users')
-  })
-  test('normalizes path without leading slash', () => {
-    expect(resolveFullPath('users', '/api')).toBe('/api/users')
-  })
-  test('no prefix', () => {
-    expect(resolveFullPath('/users')).toBe('/users')
-  })
-})