ts-procedures 7.3.0 → 8.0.0

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

@@ -1,1107 +0,0 @@
-import { describe, expect, test, vi, beforeEach } from 'vitest'
-import { Hono } from 'hono'
-import { v } from 'suretype'
-import { Procedures } from '../../../index.js'
-import { HonoRPCAppBuilder } from './index.js'
-import { RPCConfig } from '../../types.js'
-
-/**
- * HonoRPCAppBuilder Test Suite
- *
- * Tests the RPC-style Hono integration for ts-procedures.
- * This builder creates POST routes at `/{name}/{version}` paths (with optional pathPrefix).
- */
-describe('HonoRPCAppBuilder', () => {
-  // --------------------------------------------------------------------------
-  // Constructor Tests
-  // --------------------------------------------------------------------------
-  describe('constructor', () => {
-    test('creates default Hono app', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{ userId: string }, RPCConfig>()
-
-      RPC.Create(
-        'Echo',
-        { scope: 'echo', version: 1, schema: { params: v.object({ message: v.string() }) } },
-        async (ctx, params) => params
-      )
-
-      builder.register(RPC, () => ({ userId: '123' }))
-      const app = builder.build()
-
-      // Hono has built-in JSON parsing via c.req.json()
-      const res = await app.request('/echo/echo/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ message: 'hello' }),
-      })
-
-      expect(res.status).toBe(200)
-      const body = await res.json()
-      expect(body).toEqual({ message: 'hello' })
-    })
-
-    test('uses provided Hono app', async () => {
-      const customApp = new Hono()
-      // Add a custom route to verify it's the same app
-      customApp.get('/custom', (c) => c.json({ custom: true }))
-
-      const builder = new HonoRPCAppBuilder({ app: customApp })
-      const RPC = Procedures<{ userId: string }, RPCConfig>()
-
-      RPC.Create(
-        'Echo',
-        { scope: 'echo', version: 1, schema: { params: v.object({ message: v.string() }) } },
-        async (ctx, params) => ({ received: params })
-      )
-
-      builder.register(RPC, () => ({ userId: '123' }))
-      const app = builder.build()
-
-      // Custom route should still work
-      const customRes = await app.request('/custom')
-      expect(customRes.status).toBe(200)
-      const customBody = await customRes.json()
-      expect(customBody).toEqual({ custom: true })
-
-      // RPC route should also work
-      const rpcRes = await app.request('/echo/echo/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ message: 'hello' }),
-      })
-      expect(rpcRes.status).toBe(200)
-    })
-
-    test('handles empty config', () => {
-      const builder = new HonoRPCAppBuilder({})
-      expect(builder.app).toBeDefined()
-      expect(builder.docs).toEqual([])
-    })
-
-    test('handles undefined config', () => {
-      const builder = new HonoRPCAppBuilder(undefined)
-      expect(builder.app).toBeDefined()
-      expect(builder.docs).toEqual([])
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // pathPrefix Option Tests
-  // --------------------------------------------------------------------------
-  describe('pathPrefix option', () => {
-    test('uses custom pathPrefix for all routes', async () => {
-      const builder = new HonoRPCAppBuilder({ pathPrefix: '/api/v1' })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/api/v1/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(res.status).toBe(200)
-      const body = await res.json()
-      expect(body).toEqual({ ok: true })
-    })
-
-    test('pathPrefix without leading slash gets normalized', async () => {
-      const builder = new HonoRPCAppBuilder({ pathPrefix: 'custom' })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/custom/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(res.status).toBe(200)
-    })
-
-    test('no prefix when pathPrefix not specified', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(res.status).toBe(200)
-    })
-
-    test('pathPrefix appears in generated docs', () => {
-      const builder = new HonoRPCAppBuilder({ pathPrefix: '/api' })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      expect(builder.docs[0]!.path).toBe('/api/test/test/1')
-    })
-
-    test('pathPrefix /rpc restores original behavior', async () => {
-      const builder = new HonoRPCAppBuilder({ pathPrefix: '/rpc' })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Users', { scope: 'users', version: 1 }, async () => ({ users: [] }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/rpc/users/users/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(res.status).toBe(200)
-      expect(builder.docs[0]!.path).toBe('/rpc/users/users/1')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Lifecycle Hooks Tests
-  // --------------------------------------------------------------------------
-  describe('lifecycle hooks', () => {
-    test('onRequestStart is called with context object', async () => {
-      const onRequestStart = vi.fn()
-      const builder = new HonoRPCAppBuilder({ onRequestStart })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(onRequestStart).toHaveBeenCalledTimes(1)
-      expect(onRequestStart.mock.calls[0]![0]).toHaveProperty('req')
-    })
-
-    test('onRequestEnd is called after response', async () => {
-      const onRequestEnd = vi.fn()
-      const builder = new HonoRPCAppBuilder({ onRequestEnd })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(onRequestEnd).toHaveBeenCalledTimes(1)
-      expect(onRequestEnd.mock.calls[0]![0]).toHaveProperty('req')
-    })
-
-    test('onSuccess is called on successful procedure execution', async () => {
-      const onSuccess = vi.fn()
-      const builder = new HonoRPCAppBuilder({ onSuccess })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(onSuccess).toHaveBeenCalledTimes(1)
-      expect(onSuccess.mock.calls[0]![0]).toHaveProperty('name', 'Test')
-    })
-
-    test('onSuccess is NOT called when procedure throws', async () => {
-      const onSuccess = vi.fn()
-      const builder = new HonoRPCAppBuilder({ onSuccess })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
-        throw new Error('Handler error')
-      })
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(onSuccess).not.toHaveBeenCalled()
-    })
-
-    test('hooks execute in correct order: start → handler → success → end', async () => {
-      const order: string[] = []
-
-      const builder = new HonoRPCAppBuilder({
-        onRequestStart: () => order.push('start'),
-        onRequestEnd: () => order.push('end'),
-        onSuccess: () => order.push('success'),
-      })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
-        order.push('handler')
-        return { ok: true }
-      })
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(order).toEqual(['start', 'handler', 'success', 'end'])
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Error Handling Tests
-  // --------------------------------------------------------------------------
-  describe('error handling', () => {
-    test('custom error handler receives procedure, context, and error', async () => {
-      const errorHandler = vi.fn((procedure, c, error) => {
-        return c.json({ customError: error.message }, 400)
-      })
-
-      const builder = new HonoRPCAppBuilder({ onError: errorHandler })
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
-        throw new Error('Test error')
-      })
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(errorHandler).toHaveBeenCalledTimes(1)
-      expect(errorHandler.mock.calls[0]![0]).toHaveProperty('name', 'Test')
-      expect(errorHandler.mock.calls[0]![2]).toBeInstanceOf(Error)
-      expect(res.status).toBe(400)
-      const body = await res.json()
-      // Error is wrapped by Procedures with "Error in handler for {name}" prefix
-      expect(body.customError).toContain('Test error')
-    })
-
-    test('default error handling returns error message in response', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
-        throw new Error('Something went wrong')
-      })
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(res.status).toBe(500)
-      const body = await res.json()
-      // Default error handler returns error message in JSON body
-      expect(body).toHaveProperty('error')
-      expect(body.error).toContain('Something went wrong')
-    })
-
-    test('catches unhandled exceptions in handler', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
-        // Simulate unhandled exception
-        const obj: any = null
-        return obj.property // This will throw
-      })
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/test/test/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      // Unhandled exceptions are caught and returned as error response
-      const body = await res.json()
-      expect(body).toHaveProperty('error')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // register() Method Tests
-  // --------------------------------------------------------------------------
-  describe('register() method', () => {
-    test('returns this for method chaining', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC1 = Procedures<{}, RPCConfig>()
-      const RPC2 = Procedures<{}, RPCConfig>()
-
-      const result = builder.register(RPC1, () => ({}))
-      expect(result).toBe(builder)
-
-      // Chain multiple registrations
-      const chainResult = builder.register(RPC1, () => ({})).register(RPC2, () => ({}))
-
-      expect(chainResult).toBe(builder)
-    })
-
-    test('supports registering multiple factories', async () => {
-      const builder = new HonoRPCAppBuilder()
-
-      const PublicRPC = Procedures<{ public: true }, RPCConfig>()
-      const PrivateRPC = Procedures<{ private: true }, RPCConfig>()
-
-      PublicRPC.Create('PublicMethod', { scope: 'public', version: 1 }, async (ctx) => ({
-        isPublic: ctx.public,
-      }))
-
-      PrivateRPC.Create('PrivateMethod', { scope: 'private', version: 1 }, async (ctx) => ({
-        isPrivate: ctx.private,
-      }))
-
-      builder
-        .register(PublicRPC, () => ({ public: true as const }))
-        .register(PrivateRPC, () => ({ private: true as const }))
-
-      const app = builder.build()
-
-      const publicRes = await app.request('/public/public-method/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      const privateRes = await app.request('/private/private-method/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      const publicBody = await publicRes.json()
-      const privateBody = await privateRes.json()
-
-      expect(publicBody).toEqual({ isPublic: true })
-      expect(privateBody).toEqual({ isPrivate: true })
-    })
-
-    test('context can be a static object', async () => {
-      const factoryContext = { requestId: 'req-123' }
-
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{ requestId: string }, RPCConfig>()
-
-      RPC.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
-        id: ctx.requestId,
-      }))
-
-      builder.register(RPC, factoryContext)
-      const app = builder.build()
-
-      const res = await app.request('/get-request-id/get-request-id/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      const body = await res.json()
-      expect(body).toEqual({ id: 'req-123' })
-    })
-
-    test('factoryContext can be async function', async () => {
-      const factoryContext = vi.fn(async () => {
-        return { requestId: 'req-456' }
-      })
-
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{ requestId: string }, RPCConfig>()
-
-      RPC.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
-        id: ctx.requestId,
-      }))
-
-      builder.register(RPC, factoryContext)
-      const app = builder.build()
-
-      await app.request('/get-request-id/get-request-id/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(factoryContext).toHaveBeenCalledTimes(1)
-    })
-
-    test('factoryContext function receives Hono context object', async () => {
-      const factoryContext = vi.fn((c) => ({
-        authHeader: c.req.header('authorization'),
-      }))
-
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{ authHeader?: string }, RPCConfig>()
-
-      RPC.Create('GetAuth', { scope: 'get-auth', version: 1 }, async (ctx) => ({
-        auth: ctx.authHeader,
-      }))
-
-      builder.register(RPC, factoryContext)
-      const app = builder.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')
-      const body = await res.json()
-      expect(body).toEqual({ auth: 'Bearer token123' })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // build() Method Tests
-  // --------------------------------------------------------------------------
-  describe('build() method', () => {
-    test('creates POST routes for all procedures', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('MethodOne', { scope: 'method-one', version: 1 }, async () => ({ m: 1 }))
-      RPC.Create('MethodTwo', { scope: 'method-two', version: 2 }, async () => ({ m: 2 }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res1 = await app.request('/method-one/method-one/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      const res2 = await app.request('/method-two/method-two/2', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-
-      expect(res1.status).toBe(200)
-      expect(res2.status).toBe(200)
-      const body1 = await res1.json()
-      const body2 = await res2.json()
-      expect(body1).toEqual({ m: 1 })
-      expect(body2).toEqual({ m: 2 })
-    })
-
-    test('returns the Hono application', () => {
-      const builder = new HonoRPCAppBuilder()
-      const app = builder.build()
-
-      expect(app).toBe(builder.app)
-      expect(typeof app.request).toBe('function')
-    })
-
-    test('populates docs array after build', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('MethodOne', { scope: 'method-one', version: 1 }, async () => ({}))
-      RPC.Create('MethodTwo', { scope: ['nested', 'method'], version: 2 }, async () => ({}))
-
-      expect(builder.docs).toHaveLength(0)
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      expect(builder.docs).toHaveLength(2)
-      expect(builder.docs[0]!.path).toBe('/method-one/method-one/1')
-      expect(builder.docs[1]!.path).toBe('/nested/method/method-two/2')
-    })
-
-    test('passes request body to handler as params', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create(
-        'Echo',
-        { scope: 'echo', version: 1, schema: { params: v.object({ data: v.string() }) } },
-        async (ctx, params) => ({ received: params.data })
-      )
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/echo/echo/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ data: 'test-data' }),
-      })
-
-      const body = await res.json()
-      expect(body).toEqual({ received: 'test-data' })
-    })
-
-    test('GET requests return 404 (RPC uses POST only)', async () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      const app = builder.build()
-
-      const res = await app.request('/test/test/1')
-
-      expect(res.status).toBe(404)
-    })
-
-    test('skips streaming procedures and tracks them in skippedProcedures', async () => {
-      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
-      try {
-        const builder = new HonoRPCAppBuilder()
-        const RPC = Procedures<{}, RPCConfig>()
-
-        RPC.Create('RegularProc', { scope: 'test', version: 1 }, async () => ({ ok: true }))
-        RPC.CreateStream('StreamProc', { scope: 'test', version: 1 }, async function* () {
-          yield { msg: 'stream' }
-        })
-
-        builder.register(RPC, () => ({}))
-        builder.build()
-
-        // Only the regular procedure makes it into docs
-        expect(builder.docs).toHaveLength(1)
-        expect(builder.docs[0]!.name).toBe('RegularProc')
-
-        // Stream proc surfaces via skippedProcedures
-        expect(builder.skippedProcedures).toHaveLength(1)
-        expect(builder.skippedProcedures[0]!.name).toBe('StreamProc')
-        expect(builder.skippedProcedures[0]!.reason).toMatch(/HonoStreamAppBuilder/)
-
-        // And we logged a warning so devs aren't blindsided
-        expect(warnSpy).toHaveBeenCalledWith(
-          expect.stringContaining('Skipping procedure "StreamProc"')
-        )
-      } finally {
-        warnSpy.mockRestore()
-      }
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Path Generation Tests (makeRPCHttpRoutePath)
-  // --------------------------------------------------------------------------
-  describe('makeRPCHttpRoutePath', () => {
-    let builder: HonoRPCAppBuilder
-
-    beforeEach(() => {
-      builder = new HonoRPCAppBuilder()
-    })
-
-    test("simple scope with procedure name: 'users' + 'GetUser' → /users/get-user/1", () => {
-      const path = builder.makeRPCHttpRoutePath('GetUser', { scope: 'users', version: 1 })
-      expect(path).toBe('/users/get-user/1')
-    })
-
-    test("array scope with procedure name: ['users', 'profile'] + 'GetById' → /users/profile/get-by-id/1", () => {
-      const path = builder.makeRPCHttpRoutePath('GetById', {
-        scope: ['users', 'profile'],
-        version: 1,
-      })
-      expect(path).toBe('/users/profile/get-by-id/1')
-    })
-
-    test("camelCase procedure name: 'users' + 'getProfile' → /users/get-profile/1", () => {
-      const path = builder.makeRPCHttpRoutePath('getProfile', { scope: 'users', version: 1 })
-      expect(path).toBe('/users/get-profile/1')
-    })
-
-    test("PascalCase procedure name: 'users' + 'UpdateProfile' → /users/update-profile/1", () => {
-      const path = builder.makeRPCHttpRoutePath('UpdateProfile', { scope: 'users', version: 1 })
-      expect(path).toBe('/users/update-profile/1')
-    })
-
-    test('version number included in path', () => {
-      const pathV1 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 1 })
-      const pathV2 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 2 })
-      const pathV99 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 99 })
-
-      expect(pathV1).toBe('/test/test/1')
-      expect(pathV2).toBe('/test/test/2')
-      expect(pathV99).toBe('/test/test/99')
-    })
-
-    test('handles mixed case in array segments', () => {
-      const path = builder.makeRPCHttpRoutePath('ListUsers', {
-        scope: ['UserModule', 'getActiveUsers'],
-        version: 1,
-      })
-      expect(path).toBe('/user-module/get-active-users/list-users/1')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Route Documentation Tests (buildRpcHttpRouteDoc)
-  // --------------------------------------------------------------------------
-  describe('buildRpcHttpRouteDoc', () => {
-    let builder: HonoRPCAppBuilder
-
-    beforeEach(() => {
-      builder = new HonoRPCAppBuilder()
-    })
-
-    test('generates complete route documentation', () => {
-      const paramsSchema = v.object({ id: v.string() })
-      const returnSchema = v.object({ name: v.string() })
-
-      const RPC = Procedures<{}, RPCConfig>()
-      RPC.Create(
-        'GetUser',
-        { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
-        async () => ({ name: 'test' })
-      )
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      const doc = builder.docs[0]!
-      expect(doc.path).toBe('/users/get-user/1')
-      expect(doc.method).toBe('post')
-      expect(doc.jsonSchema.body).toBeDefined()
-      expect(doc.jsonSchema.response).toBeDefined()
-    })
-
-    test('omits body schema when no params defined', () => {
-      const RPC = Procedures<{}, RPCConfig>()
-      RPC.Create('NoParams', { scope: 'no-params', version: 1 }, async () => ({ ok: true }))
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      const doc = builder.docs[0]!
-      expect(doc.jsonSchema.body).toBeUndefined()
-    })
-
-    test('omits response schema when no returnType defined', () => {
-      const RPC = Procedures<{}, RPCConfig>()
-      RPC.Create(
-        'NoReturn',
-        { scope: 'no-return', version: 1, schema: { params: v.object({ x: v.number() }) } },
-        async () => ({})
-      )
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      const doc = builder.docs[0]!
-      expect(doc.jsonSchema.body).toBeDefined()
-      expect(doc.jsonSchema.response).toBeUndefined()
-    })
-
-    test("method is always 'post'", () => {
-      const RPC = Procedures<{}, RPCConfig>()
-      RPC.Create('Test1', { scope: 't1', version: 1 }, async () => ({}))
-      RPC.Create('Test2', { scope: 't2', version: 2 }, async () => ({}))
-
-      builder.register(RPC, () => ({}))
-      builder.build()
-
-      builder.docs.forEach((doc) => {
-        expect(doc.method).toBe('post')
-      })
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // extendProcedureDoc Tests
-  // --------------------------------------------------------------------------
-  describe('extendProcedureDoc', () => {
-    test('adds custom properties to generated documentation', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('GetUser', { scope: 'users', version: 1 }, async () => ({ name: 'test' }))
-
-      builder.register(
-        RPC,
-        () => ({}),
-        ({ base, procedure }) => ({
-          summary: `Get user endpoint`,
-          tags: ['users'],
-          operationId: procedure.name,
-        })
-      )
-      builder.build()
-
-      const doc = builder.docs[0]!
-      expect(doc).toHaveProperty('summary', 'Get user endpoint')
-      expect(doc).toHaveProperty('tags', ['users'])
-      expect(doc).toHaveProperty('operationId', 'GetUser')
-    })
-
-    test('receives correct base and procedure parameters', () => {
-      const extendFn = vi.fn(() => ({}))
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      const paramsSchema = v.object({ id: v.string() })
-      RPC.Create(
-        'GetItem',
-        { scope: 'items', version: 2, schema: { params: paramsSchema } },
-        async () => ({})
-      )
-
-      builder.register(RPC, () => ({}), extendFn)
-      builder.build()
-
-      expect(extendFn).toHaveBeenCalledTimes(1)
-      const callArg = extendFn.mock.calls[0]![0 as any] as any
-
-      // Verify base properties
-      expect(callArg.base).toHaveProperty('name', 'GetItem')
-      expect(callArg.base).toHaveProperty('version', 2)
-      expect(callArg.base).toHaveProperty('scope', 'items')
-      expect(callArg.base).toHaveProperty('path', '/items/get-item/2')
-      expect(callArg.base).toHaveProperty('method', 'post')
-      expect(callArg.base.jsonSchema).toHaveProperty('body')
-
-      // Verify procedure properties
-      expect(callArg.procedure).toHaveProperty('name', 'GetItem')
-      expect(callArg.procedure).toHaveProperty('handler')
-      expect(callArg.procedure.config).toHaveProperty('scope', 'items')
-      expect(callArg.procedure.config).toHaveProperty('version', 2)
-    })
-
-    test('base properties take precedence over extended properties', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
-
-      builder.register(
-        RPC,
-        () => ({}),
-        () => ({
-          name: 'OverriddenName',
-          path: '/overridden/path',
-          method: 'get',
-          customField: 'custom-value',
-        })
-      )
-      builder.build()
-
-      const doc = builder.docs[0]!
-      // Base properties should NOT be overridden
-      expect(doc.name).toBe('Test')
-      expect(doc.path).toBe('/test/test/1')
-      expect(doc.method).toBe('post')
-      // Custom field should be present
-      expect(doc).toHaveProperty('customField', 'custom-value')
-    })
-
-    test('different factories can have different extendProcedureDoc functions', () => {
-      const builder = new HonoRPCAppBuilder()
-
-      const PublicRPC = Procedures<{}, RPCConfig>()
-      const AdminRPC = Procedures<{}, RPCConfig>()
-
-      PublicRPC.Create('GetPublic', { scope: 'public', version: 1 }, async () => ({}))
-      AdminRPC.Create('GetAdmin', { scope: 'admin', version: 1 }, async () => ({}))
-
-      builder
-        .register(
-          PublicRPC,
-          () => ({}),
-          () => ({
-            security: [],
-            tags: ['public'],
-          })
-        )
-        .register(
-          AdminRPC,
-          () => ({}),
-          () => ({
-            security: [{ bearerAuth: [] }],
-            tags: ['admin'],
-          })
-        )
-
-      builder.build()
-
-      const publicDoc = builder.docs.find((d) => d.name === 'GetPublic')!
-      const adminDoc = builder.docs.find((d) => d.name === 'GetAdmin')!
-
-      expect(publicDoc).toHaveProperty('security', [])
-      expect(publicDoc).toHaveProperty('tags', ['public'])
-      expect(adminDoc).toHaveProperty('security', [{ bearerAuth: [] }])
-      expect(adminDoc).toHaveProperty('tags', ['admin'])
-    })
-
-    test('extendProcedureDoc is called for each procedure in factory', () => {
-      const extendFn = vi.fn(() => ({ extended: true }))
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Method1', { scope: 'm1', version: 1 }, async () => ({}))
-      RPC.Create('Method2', { scope: 'm2', version: 1 }, async () => ({}))
-      RPC.Create('Method3', { scope: 'm3', version: 1 }, async () => ({}))
-
-      builder.register(RPC, () => ({}), extendFn)
-      builder.build()
-
-      expect(extendFn).toHaveBeenCalledTimes(3)
-
-      const procedureNames = extendFn.mock.calls.map((call: any) => call[0].procedure.name)
-      expect(procedureNames).toContain('Method1')
-      expect(procedureNames).toContain('Method2')
-      expect(procedureNames).toContain('Method3')
-    })
-
-    test('not providing extendProcedureDoc results in base documentation only', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
-
-      builder.register(RPC, () => ({})) // No extendProcedureDoc
-      builder.build()
-
-      const doc = builder.docs[0]!
-      expect(doc.name).toBe('Test')
-      expect(doc.path).toBe('/test/test/1')
-      expect(doc.method).toBe('post')
-      // Should not have any extra properties
-      expect(Object.keys(doc)).toEqual(['kind', 'name', 'version', 'scope', 'path', 'method', 'jsonSchema'])
-    })
-
-    test('extendProcedureDoc can access procedure config for conditional logic', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      RPC.Create('PublicEndpoint', { scope: 'public', version: 1 }, async () => ({}))
-      RPC.Create('PrivateEndpoint', { scope: 'private', version: 1 }, async () => ({}))
-
-      builder.register(
-        RPC,
-        () => ({}),
-        ({ procedure }) => ({
-          isPublic: procedure.config.scope === 'public',
-          description: `This is a ${procedure.config.scope} endpoint`,
-        })
-      )
-      builder.build()
-
-      const publicDoc = builder.docs.find((d) => d.name === 'PublicEndpoint')!
-      const privateDoc = builder.docs.find((d) => d.name === 'PrivateEndpoint')!
-
-      expect(publicDoc).toHaveProperty('isPublic', true)
-      expect(publicDoc).toHaveProperty('description', 'This is a public endpoint')
-      expect(privateDoc).toHaveProperty('isPublic', false)
-      expect(privateDoc).toHaveProperty('description', 'This is a private endpoint')
-    })
-
-    test('extendProcedureDoc can use base jsonSchema for OpenAPI-style docs', () => {
-      const builder = new HonoRPCAppBuilder()
-      const RPC = Procedures<{}, RPCConfig>()
-
-      const paramsSchema = v.object({ userId: v.string() })
-      const returnSchema = v.object({ name: v.string(), email: v.string() })
-
-      RPC.Create(
-        'GetUser',
-        { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
-        async () => ({ name: 'test', email: 'test@example.com' })
-      )
-
-      builder.register(
-        RPC,
-        () => ({}),
-        ({ base }) => ({
-          requestBody: base.jsonSchema.body
-            ? { content: { 'application/json': { schema: base.jsonSchema.body } } }
-            : undefined,
-          responses: {
-            200: base.jsonSchema.response
-              ? { content: { 'application/json': { schema: base.jsonSchema.response } } }
-              : { description: 'Success' },
-          },
-        })
-      )
-      builder.build()
-
-      const doc = builder.docs[0] as any
-      expect(doc).toHaveProperty('requestBody')
-      expect(doc.requestBody).toHaveProperty('content')
-      expect(doc).toHaveProperty('responses')
-      expect(doc.responses).toHaveProperty('200')
-    })
-  })
-
-  // --------------------------------------------------------------------------
-  // Integration Test
-  // --------------------------------------------------------------------------
-  describe('integration', () => {
-    test('full workflow with multiple procedure factories and different contexts', async () => {
-      // Define context types
-      type PublicContext = { source: 'public' }
-      type AuthContext = { source: 'auth'; userId: string }
-
-      // Create factories
-      const PublicRPC = Procedures<PublicContext, RPCConfig>()
-      const AuthRPC = Procedures<AuthContext, RPCConfig>()
-
-      // Create public procedures
-      PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
-        version: '1.0.0',
-      }))
-
-      PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
-        status: 'ok',
-      }))
-
-      // Create authenticated procedures
-      AuthRPC.Create(
-        'GetProfile',
-        {
-          scope: ['users', 'profile'],
-          version: 1,
-          schema: { returnType: v.object({ userId: v.string(), source: v.string() }) },
-        },
-        async (ctx) => ({ userId: ctx.userId, source: ctx.source })
-      )
-
-      AuthRPC.Create(
-        'UpdateProfile',
-        {
-          scope: ['users', 'profile'],
-          version: 2,
-          schema: { params: v.object({ name: v.string() }) },
-        },
-        async (ctx, params) => ({ userId: ctx.userId, name: params.name })
-      )
-
-      // Build app with lifecycle hooks
-      const events: string[] = []
-
-      const builder = new HonoRPCAppBuilder({
-        onRequestStart: () => events.push('request-start'),
-        onRequestEnd: () => events.push('request-end'),
-        onSuccess: (proc) => events.push(`success:${proc.name}`),
-      })
-
-      builder
-        .register(PublicRPC, () => ({ source: 'public' as const }))
-        .register(AuthRPC, (c) => ({
-          source: 'auth' as const,
-          userId: c.req.header('x-user-id') || 'anonymous',
-        }))
-
-      const app = builder.build()
-
-      // Test public endpoints
-      const versionRes = await app.request('/system/version/get-version/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(versionRes.status).toBe(200)
-      const versionBody = await versionRes.json()
-      expect(versionBody).toEqual({ version: '1.0.0' })
-
-      const healthRes = await app.request('/health/health-check/1', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      })
-      expect(healthRes.status).toBe(200)
-      const healthBody = await healthRes.json()
-      expect(healthBody).toEqual({ status: 'ok' })
-
-      // Test authenticated endpoints
-      const profileRes = await app.request('/users/profile/get-profile/1', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-User-Id': 'user-123',
-        },
-        body: JSON.stringify({}),
-      })
-      expect(profileRes.status).toBe(200)
-      const profileBody = await profileRes.json()
-      expect(profileBody).toEqual({ userId: 'user-123', source: 'auth' })
-
-      const updateRes = await app.request('/users/profile/update-profile/2', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-User-Id': 'user-456',
-        },
-        body: JSON.stringify({ name: 'John Doe' }),
-      })
-      expect(updateRes.status).toBe(200)
-      const updateBody = await updateRes.json()
-      expect(updateBody).toEqual({ userId: 'user-456', name: 'John Doe' })
-
-      // Verify documentation
-      expect(builder.docs).toHaveLength(4)
-
-      const paths = builder.docs.map((d) => d.path)
-      expect(paths).toContain('/system/version/get-version/1')
-      expect(paths).toContain('/health/health-check/1')
-      expect(paths).toContain('/users/profile/get-profile/1')
-      expect(paths).toContain('/users/profile/update-profile/2')
-
-      // Verify hooks were called
-      expect(events).toContain('request-start')
-      expect(events).toContain('success:GetVersion')
-      expect(events).toContain('success:HealthCheck')
-      expect(events).toContain('success:GetProfile')
-      expect(events).toContain('success:UpdateProfile')
-      expect(events).toContain('request-end')
-    })
-  })
-})