ts-procedures 7.2.0 → 8.0.0

package/src/implementations/http/hono/docs/http-doc.ts

@@ -0,0 +1,43 @@
+import type { THttpProcedureRegistration } from '../../../../types.js'
+import type { APIHttpRouteDoc } from '../../../types.js'
+import { resolveFullPath } from '../path.js'
+
+export function buildHttpRouteDoc(
+  procedure: THttpProcedureRegistration<any>,
+  prefix: string | undefined,
+  extend?: (params: { base: APIHttpRouteDoc; procedure: THttpProcedureRegistration<any> }) => Record<string, unknown>,
+): APIHttpRouteDoc {
+  const config = procedure.config
+  const fullPath = resolveFullPath(config.path, prefix)
+  const reqSchema = config.schema?.req
+  const resSchema = config.schema?.res
+  const jsonSchema: APIHttpRouteDoc['jsonSchema'] = {}
+
+  if (reqSchema && (reqSchema.pathParams || reqSchema.query || reqSchema.body || reqSchema.headers)) {
+    jsonSchema.req = {}
+    if (reqSchema.pathParams) jsonSchema.req.pathParams = reqSchema.pathParams as any
+    if (reqSchema.query) jsonSchema.req.query = reqSchema.query as any
+    if (reqSchema.body) jsonSchema.req.body = reqSchema.body as any
+    if (reqSchema.headers) jsonSchema.req.headers = reqSchema.headers as any
+  }
+  if (resSchema && (resSchema.body || resSchema.headers)) {
+    jsonSchema.res = {}
+    if (resSchema.body) jsonSchema.res.body = resSchema.body as any
+    if (resSchema.headers) jsonSchema.res.headers = resSchema.headers as any
+  }
+
+  const base: APIHttpRouteDoc = {
+    kind: 'api',
+    name: procedure.name,
+    scope: config.scope,
+    path: config.path,
+    method: config.method,
+    fullPath,
+    jsonSchema,
+  }
+  if (config.successStatus) base.successStatus = config.successStatus
+  if (config.errors && config.errors.length > 0) base.errors = [...config.errors]
+
+  const extended = extend ? extend({ base, procedure }) : {}
+  return { ...extended, ...base }
+}

package/src/implementations/http/hono/docs/http-stream-doc.ts

@@ -0,0 +1,44 @@
+import type { THttpStreamProcedureRegistration } from '../../../../types.js'
+import type { HttpStreamRouteDoc } from '../../../types.js'
+import { resolveFullPath } from '../path.js'
+
+export function buildHttpStreamRouteDoc(
+  procedure: THttpStreamProcedureRegistration<any>,
+  prefix: string | undefined,
+  extend?: (params: {
+    base: HttpStreamRouteDoc
+    procedure: THttpStreamProcedureRegistration<any>
+  }) => Record<string, unknown>,
+): HttpStreamRouteDoc {
+  const config = procedure.config
+  const fullPath = resolveFullPath(config.path, prefix)
+  const reqSchema = config.schema?.req
+  const resSchema = config.schema?.res
+  const jsonSchema: HttpStreamRouteDoc['jsonSchema'] = {}
+
+  if (reqSchema && (reqSchema.pathParams || reqSchema.query || reqSchema.body || reqSchema.headers)) {
+    jsonSchema.req = {}
+    if (reqSchema.pathParams) jsonSchema.req.pathParams = reqSchema.pathParams as any
+    if (reqSchema.query) jsonSchema.req.query = reqSchema.query as any
+    if (reqSchema.body) jsonSchema.req.body = reqSchema.body as any
+    if (reqSchema.headers) jsonSchema.req.headers = reqSchema.headers as any
+  }
+  if (resSchema?.headers) jsonSchema.res = { headers: resSchema.headers as any }
+  if (config.schema?.yield) jsonSchema.yield = config.schema.yield as any
+  if (config.schema?.returnType) jsonSchema.returnType = config.schema.returnType as any
+
+  const base: HttpStreamRouteDoc = {
+    kind: 'http-stream',
+    name: procedure.name,
+    scope: config.scope,
+    path: config.path,
+    method: config.method,
+    fullPath,
+    streamMode: 'sse',
+    jsonSchema,
+  }
+  if (config.errors && config.errors.length > 0) base.errors = [...config.errors]
+
+  const extended = extend ? extend({ base, procedure }) : {}
+  return { ...extended, ...base }
+}

package/src/implementations/http/hono/docs/rpc-doc.ts

@@ -0,0 +1,34 @@
+import type { TProcedureRegistration } from '../../../../types.js'
+import type { RPCConfig, RPCHttpRouteDoc } from '../../../types.js'
+import { makeRoutePath } from '../path.js'
+
+export function buildRpcRouteDoc(
+  procedure: TProcedureRegistration<any, RPCConfig>,
+  prefix: string | undefined,
+  extend?: (params: { base: RPCHttpRouteDoc; procedure: TProcedureRegistration<any, RPCConfig> }) => Record<string, unknown>,
+): RPCHttpRouteDoc {
+  const config = procedure.config as RPCConfig & {
+    schema?: { params?: Record<string, unknown>; returnType?: Record<string, unknown> }
+    errors?: string[]
+  }
+
+  const jsonSchema: { body?: Record<string, unknown>; response?: Record<string, unknown> } = {}
+  if (config.schema?.params) jsonSchema.body = config.schema.params
+  if (config.schema?.returnType) jsonSchema.response = config.schema.returnType
+
+  const base: RPCHttpRouteDoc = {
+    kind: 'rpc',
+    name: procedure.name,
+    version: config.version,
+    scope: config.scope,
+    path: makeRoutePath({ procedure, prefix }),
+    method: 'post',
+    jsonSchema,
+  }
+  if (config.errors && config.errors.length > 0) {
+    base.errors = [...config.errors]
+  }
+
+  const extended = extend ? extend({ base, procedure }) : {}
+  return { ...extended, ...base }
+}

package/src/implementations/http/hono/docs/stream-doc.ts

@@ -0,0 +1,53 @@
+import type { TStreamProcedureRegistration } from '../../../../types.js'
+import type { RPCConfig, StreamHttpRouteDoc, StreamMode } from '../../../types.js'
+import { makeRoutePath } from '../path.js'
+
+export function buildStreamRouteDoc(
+  procedure: TStreamProcedureRegistration<any, RPCConfig>,
+  streamMode: StreamMode,
+  prefix: string | undefined,
+  extend?: (params: { base: StreamHttpRouteDoc; procedure: TStreamProcedureRegistration<any, RPCConfig> }) => Record<string, unknown>,
+): StreamHttpRouteDoc {
+  const config = procedure.config as RPCConfig & {
+    schema?: { params?: Record<string, unknown>; yieldType?: Record<string, unknown>; returnType?: Record<string, unknown> }
+    errors?: string[]
+  }
+
+  const jsonSchema: StreamHttpRouteDoc['jsonSchema'] = {}
+  if (config.schema?.params) jsonSchema.params = config.schema.params
+
+  if (streamMode === 'sse') {
+    jsonSchema.yieldType = {
+      type: 'object',
+      description: 'SSE message envelope. The data field contains the procedure yield value.',
+      required: ['data', 'event', 'id'],
+      properties: {
+        data: config.schema?.yieldType ?? {},
+        event: { type: 'string' },
+        id: { type: 'string' },
+        retry: { type: 'number' },
+      },
+    }
+  } else if (config.schema?.yieldType) {
+    jsonSchema.yieldType = config.schema.yieldType
+  }
+
+  if (config.schema?.returnType) jsonSchema.returnType = config.schema.returnType
+
+  // POST first so codegen (which reads `methods[0]`) defaults to POST. POST is
+  // the canonical method for streams because it can carry a body for params.
+  const base: StreamHttpRouteDoc = {
+    kind: 'stream',
+    name: procedure.name,
+    version: config.version,
+    scope: config.scope,
+    path: makeRoutePath({ procedure, prefix }),
+    methods: ['post', 'get'],
+    streamMode,
+    jsonSchema,
+  }
+  if (config.errors && config.errors.length > 0) base.errors = [...config.errors]
+
+  const extended = extend ? extend({ base, procedure }) : {}
+  return { ...extended, ...base }
+}

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

@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'vitest'
+import { Hono } from 'hono'
+import { Type } from 'typebox'
+import { Procedures } from '../../../../index.js'
+import { installHttpStreamRoute } from './http-stream.js'
+
+function buildApp(setup: (P: ReturnType<typeof Procedures<{ uid: string }>>) => void, cfg: any = {}) {
+  const P = Procedures<{ uid: string }>()
+  setup(P)
+  const app = new Hono()
+  const docs: any[] = []
+  for (const proc of P.getProcedures().values()) {
+    if (proc.kind !== 'http-stream') continue
+    installHttpStreamRoute({
+      app,
+      procedure: proc as any,
+      factoryItem: { factory: P, factoryContext: () => ({ uid: 'u1' }) },
+      cfg,
+      docs,
+    })
+  }
+  return { app, docs }
+}
+
+describe('installHttpStreamRoute', () => {
+  test('SSE pumping with initialHeaders and event:return', async () => {
+    const { app, docs } = buildApp((P) => {
+      P.CreateHttpStream('Tail', {
+        path: '/logs/tail', method: 'get',
+        schema: {
+          yield: Type.Object({ line: Type.String() }),
+          res: { headers: Type.Object({ 'x-trace': Type.String() }) },
+        },
+      }, async () => ({
+        headers: { 'x-trace': 'abc' },
+        stream: (async function* () {
+          yield { line: 'a' }
+          yield { line: 'b' }
+          return 'fin'
+        })(),
+      }))
+    })
+    expect(docs[0].kind).toBe('http-stream')
+
+    const res = await app.request('/logs/tail')
+    const text = await res.text()
+    expect(res.headers.get('x-trace')).toBe('abc')
+    expect(text).toContain('"line":"a"')
+    expect(text).toContain('"line":"b"')
+    expect(text).toContain('event: return')
+    expect(text).toContain('fin')
+  })
+
+  test('mid-stream throw → dispatchMidStreamError default { error }', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttpStream('Boom', { path: '/boom', method: 'get', schema: {} },
+        (async function* () {
+          yield { ok: 1 }
+          throw new Error('mid')
+        }) as any
+      )
+    })
+    const res = await app.request('/boom')
+    const text = await res.text()
+    expect(text).toContain('event: error')
+    expect(text).toContain('"error":"mid"')
+  })
+
+  test('pre-stream throw → dispatchPreStreamError 500', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttpStream('Pre', { path: '/pre', method: 'get', schema: {} },
+        (async () => { throw new Error('pre') }) as any)
+    })
+    const res = await app.request('/pre')
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.error).toContain('pre')
+  })
+
+  test('validateYields: true → invalid yield surfaces ProcedureYieldValidationError on the wire', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttpStream(
+        'BadHttpYield',
+        {
+          path: '/bad-yield',
+          method: 'get',
+          schema: { yield: Type.Object({ id: Type.Number() }) },
+          validateYields: true,
+        },
+        (async function* () {
+          yield { id: 1 }
+          yield { id: 'not-a-number' } as any
+        }) as any,
+      )
+    })
+
+    const res = await app.request('/bad-yield')
+    expect(res.status).toBe(200)
+    const text = await res.text()
+    expect(text).toContain('event: error')
+    expect(text).toContain('"name":"ProcedureYieldValidationError"')
+    expect(text).toContain('"procedureName":"BadHttpYield"')
+    expect(text).toContain('"id":1')
+  })
+
+  test('AbortSignal: natural completion → ctx.signal.reason === "stream-completed"', async () => {
+    let capturedSignal: AbortSignal | undefined
+    const { app } = buildApp((P) => {
+      P.CreateHttpStream('NaturalSig', { path: '/sig-natural', method: 'get', schema: {} },
+        (async function* (ctx: any) {
+          capturedSignal = ctx.signal
+          yield { tick: 1 }
+        }) as any,
+      )
+    })
+
+    const res = await app.request('/sig-natural')
+    await res.text()
+
+    expect(capturedSignal).toBeInstanceOf(AbortSignal)
+    expect(capturedSignal!.aborted).toBe(true)
+    expect(capturedSignal!.reason).toBe('stream-completed')
+  })
+
+  test('AbortSignal: pre-aborted request signal → ctx.signal.reason !== "stream-completed"', async () => {
+    // Same proxy approach as the rpc-stream variant: pre-abort the request
+    // signal and rely on `AbortSignal.any` preserving the earlier reason over
+    // the internal 'stream-completed' that fires in the wrappedHandler's
+    // finally clause.
+    let capturedSignal: AbortSignal | undefined
+    const { app } = buildApp((P) => {
+      P.CreateHttpStream('DisconnectSig', { path: '/sig-disconnect', method: 'get', schema: {} },
+        (async function* (ctx: any) {
+          capturedSignal = ctx.signal
+          yield { tick: 1 }
+        }) as any,
+      )
+    })
+
+    const ac = new AbortController()
+    ac.abort('client-gone')
+    const req = new Request('http://localhost/sig-disconnect', { method: 'GET', signal: ac.signal })
+    const res = await app.request(req)
+    await res.text().catch(() => '')
+
+    expect(capturedSignal).toBeInstanceOf(AbortSignal)
+    expect(capturedSignal!.aborted).toBe(true)
+    expect(capturedSignal!.reason).not.toBe('stream-completed')
+  })
+})

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

@@ -0,0 +1,152 @@
+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.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test, vi } from 'vitest'
+import { Hono } from 'hono'
+import { Type } from 'typebox'
+import { Procedures } from '../../../../index.js'
+import { installHttpRoute } from './http.js'
+
+function buildApp(setup: (P: ReturnType<typeof Procedures<{ uid: string }>>) => void, cfg: any = {}) {
+  const P = Procedures<{ uid: string }>()
+  setup(P)
+  const app = new Hono()
+  const docs: any[] = []
+  for (const proc of P.getProcedures().values()) {
+    if (proc.kind !== 'http') continue
+    installHttpRoute({
+      app,
+      procedure: proc as any,
+      factoryItem: { factory: P, factoryContext: () => ({ uid: 'u1' }) },
+      cfg,
+      docs,
+    })
+  }
+  return { app, docs }
+}
+
+describe('installHttpRoute', () => {
+  test('GET with pathParams and query', async () => {
+    const { app, docs } = buildApp((P) => {
+      P.CreateHttp('GetUser', {
+        path: '/users/:id',
+        method: 'get',
+        scope: 'users',
+        schema: {
+          req: {
+            pathParams: Type.Object({ id: Type.String() }),
+            query: Type.Object({ include: Type.Optional(Type.String()) }),
+          },
+          res: { body: Type.Object({ id: Type.String(), include: Type.Optional(Type.String()) }) },
+        },
+      }, async (_ctx, { pathParams, query }) => ({ id: pathParams.id, include: query.include }))
+    })
+
+    const res = await app.request('/users/abc?include=foo')
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: 'abc', include: 'foo' })
+    expect(docs[0].kind).toBe('api')
+    expect(docs[0].fullPath).toBe('/users/:id')
+  })
+
+  test('POST with body, default 201', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Create', {
+        path: '/items',
+        method: 'post',
+        schema: {
+          req: { body: Type.Object({ name: Type.String() }) },
+          res: { body: Type.Object({ name: Type.String() }) },
+        },
+      }, async (_ctx, { body }) => body)
+    })
+
+    const res = await app.request('/items', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'gizmo' }),
+    })
+    expect(res.status).toBe(201)
+    expect(await res.json()).toEqual({ name: 'gizmo' })
+  })
+
+  test('DELETE returns 204 with no body', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Delete', {
+        path: '/items/:id',
+        method: 'delete',
+        schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+      }, async () => undefined)
+    })
+
+    const res = await app.request('/items/x', { method: 'DELETE' })
+    expect(res.status).toBe(204)
+    expect(await res.text()).toBe('')
+  })
+
+  test('headers in result are forwarded', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('WithHeaders', {
+        path: '/h', method: 'get',
+        schema: { res: { body: Type.Object({ ok: Type.Boolean() }), headers: Type.Object({}) } },
+      }, async () => ({ body: { ok: true }, headers: { 'x-trace': 'abc' } }))
+    })
+    const res = await app.request('/h')
+    expect(res.headers.get('x-trace')).toBe('abc')
+    expect(await res.json()).toEqual({ ok: true })
+  })
+
+  test('api.onSuccess fires after handler', async () => {
+    const onSuccess = vi.fn()
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Ping', { path: '/ping', method: 'get', schema: {} }, async () => undefined)
+    }, { api: { onSuccess } })
+
+    await app.request('/ping')
+    expect(onSuccess).toHaveBeenCalledOnce()
+  })
+
+  test('thrown error → dispatchPreStreamError default 500', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Boom', { path: '/boom', method: 'get', schema: {} }, async () => { throw new Error('x') })
+    })
+    const res = await app.request('/boom')
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.error).toContain('x')
+  })
+
+  test('custom queryParser is used', async () => {
+    const queryParser = vi.fn((q: string) => ({ parsed: true, raw: q }))
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Q', {
+        path: '/q', method: 'get',
+        schema: { req: { query: Type.Any() }, res: { body: Type.Any() } },
+      },
+        async (_ctx, { query }) => ({ body: query }))
+    }, { api: { queryParser } })
+
+    const res = await app.request('/q?a=1&b=2')
+    expect(queryParser).toHaveBeenCalledWith('a=1&b=2')
+    expect(await res.json()).toEqual({ parsed: true, raw: 'a=1&b=2' })
+  })
+})