ts-procedures 7.2.0 → 8.0.0

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

@@ -0,0 +1,329 @@
+import { describe, expect, test, vi } from 'vitest'
+import { Hono } from 'hono'
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import type { RPCConfig } from '../../types.js'
+import { HonoAppBuilder } from './index.js'
+import { defineErrorTaxonomy } from '../error-taxonomy.js'
+import { DocRegistry } from '../doc-registry.js'
+
+describe('HonoAppBuilder — public surface', () => {
+  test('constructor with no args', () => {
+    const b = new HonoAppBuilder()
+    expect(b.app).toBeInstanceOf(Hono)
+    expect(b.docs).toEqual([])
+    expect(b.skippedProcedures).toEqual([])
+  })
+
+  test('constructor accepts existing Hono app', () => {
+    const custom = new Hono()
+    const b = new HonoAppBuilder({ app: custom })
+    expect(b.app).toBe(custom)
+  })
+
+  test('register is chainable', () => {
+    const b = new HonoAppBuilder()
+    const P = Procedures<{}, RPCConfig>()
+    const result = b.register(P, () => ({}))
+    expect(result).toBe(b)
+  })
+
+  test('docs is lazily computed before build()', () => {
+    const b = new HonoAppBuilder()
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('A', { scope: 's', version: 1 }, async () => ({}))
+    b.register(P, () => ({}))
+
+    const docs1 = b.docs
+    expect(docs1).toHaveLength(1)
+    expect(docs1[0]!.kind).toBe('rpc')
+    // Calling docs again returns the same cached array reference
+    expect(b.docs).toBe(docs1)
+  })
+
+  test('docs reads after build() return the same content', () => {
+    const b = new HonoAppBuilder()
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('A', { scope: 's', version: 1 }, async () => ({}))
+    b.register(P, () => ({}))
+    b.build()
+    expect(b.docs).toHaveLength(1)
+  })
+})
+
+describe('HonoAppBuilder — mixed-kind dispatch', () => {
+  test('one factory with all four kinds mounts each at the correct path', async () => {
+    const P = Procedures<{ uid: string }, RPCConfig>()
+    P.Create('Echo', { scope: 'rpc', version: 1 }, async (_ctx, p) => p)
+    P.CreateStream('Tail', { scope: 'rpc', version: 1 }, async function* () { yield 1 })
+    P.CreateHttp('GetUser', {
+      path: '/users/:id',
+      method: 'get',
+      schema: {
+        req: { pathParams: Type.Object({ id: Type.String() }) },
+        res: { body: Type.Object({ id: Type.String() }) },
+      },
+    }, async () => ({ id: '1' }))
+    P.CreateHttpStream('Watch', {
+      path: '/watch', method: 'get',
+      schema: { yield: Type.String() },
+    }, (async function* () { yield 'tick' }) as any)
+
+    const app = new HonoAppBuilder()
+      .register(P, () => ({ uid: 'u1' }))
+      .build()
+
+    const rpc = await app.request('/rpc/echo/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(rpc.status).toBe(200)
+
+    const stream = await app.request('/rpc/tail/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(stream.status).toBe(200)
+    await stream.text()
+
+    const http = await app.request('/users/1')
+    expect(http.status).toBe(200)
+
+    const httpStream = await app.request('/watch')
+    expect(httpStream.status).toBe(200)
+    await httpStream.text()
+  })
+
+  test('toDocEnvelope produces same shape as DocRegistry.toJSON', () => {
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('Echo', { scope: 'e', version: 1 }, async () => ({}))
+
+    const errors = defineErrorTaxonomy({})
+    const builder = new HonoAppBuilder({ pathPrefix: '/api', errors })
+    builder.register(P, () => ({}))
+    builder.build()
+
+    const builderEnvelope = builder.toDocEnvelope({ basePath: '/api', errors })
+    const registryEnvelope = new DocRegistry({ basePath: '/api', errors }).from(builder).toJSON()
+
+    expect(builderEnvelope.basePath).toBe(registryEnvelope.basePath)
+    expect(builderEnvelope.routes).toEqual(registryEnvelope.routes)
+    expect(builderEnvelope.errors.map(e => e.name).sort()).toEqual(registryEnvelope.errors.map(e => e.name).sort())
+  })
+
+  test('toDocEnvelope filter and transform options work', () => {
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('A', { scope: 's', version: 1 }, async () => ({}))
+    P.Create('B', { scope: 's', version: 1 }, async () => ({}))
+
+    const builder = new HonoAppBuilder().register(P, () => ({}))
+    const onlyA = builder.toDocEnvelope({ filter: r => r.name === 'A' })
+    expect(onlyA.routes).toHaveLength(1)
+    expect(onlyA.routes[0]!.name).toBe('A')
+
+    const tagged = builder.toDocEnvelope({
+      transform: env => ({ ...env, tagged: true }) as any,
+    }) as any
+    expect(tagged.tagged).toBe(true)
+  })
+
+  test('makeRoutePath static is exposed', () => {
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('GetUser', { scope: 'users', version: 1 }, async () => ({}))
+    const proc = P.getProcedure('GetUser')!
+    expect(HonoAppBuilder.makeRoutePath({ procedure: proc as any })).toBe('/users/get-user/1')
+  })
+})
+
+describe('HonoAppBuilder — factoryContext variants', () => {
+  test('factoryContext as a static object is forwarded into ctx', async () => {
+    const P = Procedures<{ requestId: string }, RPCConfig>()
+    P.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
+      id: ctx.requestId,
+    }))
+
+    const app = new HonoAppBuilder()
+      .register(P, { requestId: 'req-123' })
+      .build()
+
+    const res = await app.request('/get-request-id/get-request-id/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+    expect(await res.json()).toEqual({ id: 'req-123' })
+  })
+
+  test('factoryContext as an async function is awaited and result reaches handler', async () => {
+    const factoryContext = vi.fn(async () => ({ requestId: 'req-456' }))
+    const P = Procedures<{ requestId: string }, RPCConfig>()
+    P.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
+      id: ctx.requestId,
+    }))
+
+    const app = new HonoAppBuilder().register(P, factoryContext).build()
+
+    const res = await app.request('/get-request-id/get-request-id/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+    expect(factoryContext).toHaveBeenCalledTimes(1)
+    expect(await res.json()).toEqual({ id: 'req-456' })
+  })
+
+  test('factoryContext rejection flows through dispatchPreStreamError → 500', async () => {
+    const P = Procedures<{ requestId: string }, RPCConfig>()
+    P.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
+      id: ctx.requestId,
+    }))
+
+    const app = new HonoAppBuilder()
+      .register(P, async () => {
+        throw new Error('context-load-failed')
+      })
+      .build()
+
+    const res = await app.request('/get-request-id/get-request-id/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+    expect(res.status).toBe(500)
+    const body = await res.json()
+    expect(body.error).toContain('context-load-failed')
+  })
+
+  test('factoryContext function receives Hono Context with req.header access', async () => {
+    const factoryContext = vi.fn((c: any) => ({
+      authHeader: c.req.header('authorization'),
+    }))
+    const P = Procedures<{ authHeader?: string }, RPCConfig>()
+    P.Create('GetAuth', { scope: 'get-auth', version: 1 }, async (ctx) => ({
+      auth: ctx.authHeader,
+    }))
+
+    const app = new HonoAppBuilder().register(P, factoryContext).build()
+
+    const res = await app.request('/get-auth/get-auth/1', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: 'Bearer token123',
+      },
+      body: JSON.stringify({}),
+    })
+    expect(factoryContext).toHaveBeenCalledTimes(1)
+    expect(factoryContext.mock.calls[0]![0]).toHaveProperty('req')
+    expect(await res.json()).toEqual({ auth: 'Bearer token123' })
+  })
+})
+
+describe('HonoAppBuilder — extendProcedureDoc discriminated union per kind', () => {
+  test('rpc: base.kind === "rpc" and returned object is merged into doc', () => {
+    const extend = vi.fn(({ base }: { base: { kind: string } }) => ({
+      summary: `RPC: ${base.kind}`,
+      tags: ['rpc'],
+    }))
+    const P = Procedures<{}, RPCConfig>()
+    P.Create('GetUser', { scope: 'users', version: 1 }, async () => ({}))
+
+    const builder = new HonoAppBuilder().register(P, () => ({}), { extendProcedureDoc: extend })
+    builder.build()
+
+    expect(extend).toHaveBeenCalledTimes(1)
+    expect(extend.mock.calls[0]![0]!.base.kind).toBe('rpc')
+    const doc = builder.docs[0] as any
+    expect(doc.summary).toBe('RPC: rpc')
+    expect(doc.tags).toEqual(['rpc'])
+  })
+
+  test('api (http): base.kind === "api" and returned object is merged into doc', () => {
+    const extend = vi.fn(({ base }: { base: { kind: string } }) => ({
+      summary: `API: ${base.kind}`,
+      tags: ['api'],
+    }))
+    const P = Procedures<{}>()
+    P.CreateHttp(
+      'GetUser',
+      {
+        path: '/users/:id',
+        method: 'get',
+        schema: {
+          req: { pathParams: Type.Object({ id: Type.String() }) },
+          res: { body: Type.Object({ id: Type.String() }) },
+        },
+      },
+      async () => ({ id: '1' }),
+    )
+
+    const builder = new HonoAppBuilder().register(P, () => ({}), { extendProcedureDoc: extend })
+    builder.build()
+
+    expect(extend).toHaveBeenCalledTimes(1)
+    expect(extend.mock.calls[0]![0]!.base.kind).toBe('api')
+    const doc = builder.docs[0] as any
+    expect(doc.summary).toBe('API: api')
+    expect(doc.tags).toEqual(['api'])
+  })
+
+  test('rpc-stream: base.kind === "stream" and returned object is merged into doc', () => {
+    const extend = vi.fn(({ base }: { base: { kind: string } }) => ({
+      summary: `Stream: ${base.kind}`,
+      tags: ['stream'],
+    }))
+    const P = Procedures<{}, RPCConfig>()
+    P.CreateStream('Tail', { scope: 'rpc', version: 1 }, async function* () {
+      yield 1
+    })
+
+    const builder = new HonoAppBuilder().register(P, () => ({}), { extendProcedureDoc: extend })
+    builder.build()
+
+    expect(extend).toHaveBeenCalledTimes(1)
+    expect(extend.mock.calls[0]![0]!.base.kind).toBe('stream')
+    const doc = builder.docs[0] as any
+    expect(doc.summary).toBe('Stream: stream')
+    expect(doc.tags).toEqual(['stream'])
+  })
+
+  test('http-stream: base.kind === "http-stream" and returned object is merged into doc', () => {
+    const extend = vi.fn(({ base }: { base: { kind: string } }) => ({
+      summary: `HTTP-Stream: ${base.kind}`,
+      tags: ['http-stream'],
+    }))
+    const P = Procedures<{}>()
+    P.CreateHttpStream(
+      'Watch',
+      { path: '/watch', method: 'get', schema: { yield: Type.String() } },
+      (async function* () {
+        yield 'tick'
+      }) as any,
+    )
+
+    const builder = new HonoAppBuilder().register(P, () => ({}), { extendProcedureDoc: extend })
+    builder.build()
+
+    expect(extend).toHaveBeenCalledTimes(1)
+    expect(extend.mock.calls[0]![0]!.base.kind).toBe('http-stream')
+    const doc = builder.docs[0] as any
+    expect(doc.summary).toBe('HTTP-Stream: http-stream')
+    expect(doc.tags).toEqual(['http-stream'])
+  })
+})
+
+describe('HonoAppBuilder — per-factory streamMode override', () => {
+  test('register options.streamMode overrides stream.defaultStreamMode', async () => {
+    const P = Procedures<{}, RPCConfig>()
+    P.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+      yield { ok: true }
+    })
+
+    const app = new HonoAppBuilder({ stream: { defaultStreamMode: 'sse' } })
+      .register(P, () => ({}), { streamMode: 'text' })
+      .build()
+
+    const res = await app.request('/test/test/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    })
+    expect(res.headers.get('content-type')).toContain('text/plain')
+    // Drain the response so the stream lifecycle completes cleanly.
+    await res.text()
+  })
+})

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

@@ -0,0 +1,204 @@
+import { Context, Hono } from 'hono'
+import type {
+  AnyHttpRouteDoc,
+  ProceduresFactory,
+  ExtractContext,
+  StreamMode,
+  DocEnvelope,
+  ErrorDoc,
+  HeaderDoc,
+} from '../../types.js'
+import { DocRegistry } from '../doc-registry.js'
+import type { ErrorTaxonomy } from '../error-taxonomy.js'
+import { buildRpcRouteDoc } from './docs/rpc-doc.js'
+import { buildStreamRouteDoc } from './docs/stream-doc.js'
+import { buildHttpRouteDoc } from './docs/http-doc.js'
+import { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
+import { installRpcRoute } from './handlers/rpc.js'
+import { installRpcStreamRoute } from './handlers/stream.js'
+import { installHttpRoute } from './handlers/http.js'
+import { installHttpStreamRoute } from './handlers/http-stream.js'
+import { makeRoutePath as _makeRoutePath } from './path.js'
+import type {
+  HonoAppBuilderConfig,
+  HonoFactoryItem,
+  ExtendProcedureDoc,
+  AnyProcedureRegistration,
+  OnRequestErrorContext,
+} from './types.js'
+
+export type { HonoAppBuilderConfig, OnRequestErrorContext, ExtendProcedureDoc } from './types.js'
+export type { AnyProcedureRegistration } from './types.js'
+export { sse } from './handlers/stream.js'
+export type { SSEOptions, MidStreamErrorResult } from './handlers/stream.js'
+export { defineErrorTaxonomy } from '../error-taxonomy.js'
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig } from '../error-taxonomy.js'
+export type { QueryParser } from './types.js'
+
+export class HonoAppBuilder<TStreamErrorData = unknown> {
+  private readonly _app: Hono
+  private readonly factories: HonoFactoryItem<any>[] = []
+  private _docs: AnyHttpRouteDoc[] | null = null
+  private _skipped: { name: string; reason: string }[] = []
+  private _built = false
+
+  constructor(readonly config?: HonoAppBuilderConfig<TStreamErrorData>) {
+    this._app = config?.app ?? new Hono()
+
+    if (config?.onRequestStart) {
+      this._app.use('*', async (c, next) => {
+        config.onRequestStart!(c)
+        await next()
+      })
+    }
+    if (config?.onRequestEnd) {
+      this._app.use('*', async (c, next) => {
+        await next()
+        config.onRequestEnd!(c)
+      })
+    }
+  }
+
+  static makeRoutePath = _makeRoutePath
+
+  get app(): Hono {
+    return this._app
+  }
+
+  /**
+   * Lazily computed on first read or `build()`. Computing without `build()`
+   * lets tests and tooling introspect routes without spinning up handlers.
+   */
+  get docs(): AnyHttpRouteDoc[] {
+    if (this._docs === null) this.computeDocs()
+    return this._docs!
+  }
+
+  get skippedProcedures(): { name: string; reason: string }[] {
+    return this._skipped
+  }
+
+  register<TFactory extends ProceduresFactory>(
+    factory: TFactory,
+    factoryContext:
+      | ExtractContext<TFactory>
+      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+    options?: {
+      streamMode?: StreamMode
+      extendProcedureDoc?: ExtendProcedureDoc
+    },
+  ): this {
+    this.factories.push({
+      factory,
+      factoryContext,
+      streamMode: options?.streamMode,
+      extendProcedureDoc: options?.extendProcedureDoc,
+    } as HonoFactoryItem<any>)
+    // Invalidate docs cache so the next read recomputes.
+    this._docs = null
+    return this
+  }
+
+  private computeDocs(): void {
+    const docs: AnyHttpRouteDoc[] = []
+    const skipped: { name: string; reason: string }[] = []
+
+    for (const item of this.factories) {
+      for (const procedure of item.factory.getProcedures().values() as Iterable<AnyProcedureRegistration>) {
+        const prefix = this.config?.pathPrefix
+        switch (procedure.kind) {
+          case 'rpc':
+            docs.push(buildRpcRouteDoc(procedure as any, prefix, item.extendProcedureDoc as any))
+            break
+          case 'rpc-stream':
+            docs.push(buildStreamRouteDoc(
+              procedure as any,
+              item.streamMode ?? this.config?.stream?.defaultStreamMode ?? 'sse',
+              prefix,
+              item.extendProcedureDoc as any,
+            ))
+            break
+          case 'http':
+            docs.push(buildHttpRouteDoc(procedure as any, prefix, item.extendProcedureDoc as any))
+            break
+          case 'http-stream':
+            docs.push(buildHttpStreamRouteDoc(procedure as any, prefix, item.extendProcedureDoc as any))
+            break
+          default: {
+            const reason = `Unknown procedure kind "${(procedure as any).kind}"`
+            skipped.push({ name: (procedure as any).name, reason })
+          }
+        }
+      }
+    }
+
+    this._docs = docs
+    this._skipped = skipped
+  }
+
+  /**
+   * Mounts every registered procedure on the Hono app and returns it.
+   * Idempotent: calling twice is a no-op on the second call.
+   */
+  build(): Hono {
+    if (this._built) return this._app
+    this._built = true
+
+    const docs: AnyHttpRouteDoc[] = []
+    const skipped: { name: string; reason: string }[] = []
+    const cfg = this.config ?? {}
+
+    for (const item of this.factories) {
+      for (const procedure of item.factory.getProcedures().values() as Iterable<AnyProcedureRegistration>) {
+        switch (procedure.kind) {
+          case 'rpc':
+            installRpcRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            break
+          case 'rpc-stream': {
+            const streamMode = item.streamMode ?? cfg.stream?.defaultStreamMode ?? 'sse'
+            installRpcStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, streamMode })
+            break
+          }
+          case 'http':
+            installHttpRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            break
+          case 'http-stream':
+            installHttpStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            break
+          default: {
+            const reason = `Unknown procedure kind "${(procedure as any).kind}"`
+            skipped.push({ name: (procedure as any).name, reason })
+            console.warn(`[ts-procedures hono] Skipping procedure "${(procedure as any).name}": ${reason}`)
+          }
+        }
+      }
+    }
+
+    this._docs = docs
+    this._skipped = skipped
+    return this._app
+  }
+
+  /**
+   * Produces a {@link DocEnvelope} for single-app usage. For multi-app
+   * aggregation, use {@link DocRegistry} and `from(builder)` instead.
+   *
+   * Mirrors `DocRegistry.toJSON()` options so the two paths produce
+   * interchangeable envelopes for the codegen pipeline.
+   */
+  toDocEnvelope<T = DocEnvelope>(options?: {
+    basePath?: string
+    errors?: ErrorTaxonomy | ErrorDoc[]
+    includeDefaults?: boolean
+    headers?: HeaderDoc[]
+    filter?: (route: AnyHttpRouteDoc) => boolean
+    transform?: (envelope: DocEnvelope) => T
+  }): T {
+    return new DocRegistry({
+      basePath: options?.basePath ?? this.config?.pathPrefix,
+      errors: options?.errors ?? this.config?.errors,
+      includeDefaults: options?.includeDefaults,
+      headers: options?.headers,
+    }).from(this).toJSON<T>(options)
+  }
+}

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

@@ -0,0 +1,96 @@
+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')
+  })
+})

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

@@ -0,0 +1,59 @@
+import { kebabCase } from 'es-toolkit/string'
+import { castArray } from 'es-toolkit/compat'
+import type {
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+} from '../../../types.js'
+
+export type AnyProcedureRegistration =
+  | TProcedureRegistration
+  | TStreamProcedureRegistration
+  | THttpProcedureRegistration<any>
+  | THttpStreamProcedureRegistration<any>
+
+function normalizePrefix(prefix?: string): string {
+  if (!prefix) return ''
+  return prefix.startsWith('/') ? prefix : `/${prefix}`
+}
+
+/**
+ * Resolves the full route path for any procedure kind.
+ *
+ * - `rpc` / `rpc-stream`: `{prefix}/{kebab(scope)}/{kebab(name)}/{version}`
+ * - `http` / `http-stream`: `{prefix}{config.path}` (path-as-given, prefix normalized)
+ */
+export function makeRoutePath({
+  procedure,
+  prefix,
+}: {
+  procedure: AnyProcedureRegistration
+  prefix?: string
+}): string {
+  const normalizedPrefix = normalizePrefix(prefix)
+
+  switch (procedure.kind) {
+    case 'rpc':
+    case 'rpc-stream': {
+      const cfg = procedure.config as { scope: string | string[]; version: number }
+      const scopeSegments = castArray(cfg.scope).map(kebabCase).join('/')
+      return `${normalizedPrefix}/${scopeSegments}/${kebabCase(procedure.name)}/${String(cfg.version).trim()}`
+    }
+    case 'http':
+    case 'http-stream': {
+      const cfg = procedure.config as { path: string }
+      return resolveFullPath(cfg.path, prefix)
+    }
+  }
+}
+
+/**
+ * Combines a developer-supplied path with an optional prefix. Both are
+ * normalized to begin with a single `/`.
+ */
+export function resolveFullPath(procedurePath: string, prefix?: string): string {
+  const normalizedPrefix = normalizePrefix(prefix)
+  const normalizedPath = procedurePath.startsWith('/') ? procedurePath : `/${procedurePath}`
+  return `${normalizedPrefix}${normalizedPath}`
+}