ts-procedures 3.1.0 → 3.3.0

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

@@ -0,0 +1,1009 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import { v } from 'suretype'
+import { Procedures } from '../../../index.js'
+import { HonoStreamAppBuilder } from './index.js'
+import { RPCConfig } from '../../types.js'
+
+/**
+ * HonoStreamAppBuilder Test Suite
+ *
+ * Tests the streaming Hono integration for ts-procedures.
+ * This builder creates GET and POST routes for streaming procedures (SSE and text modes).
+ */
+describe('HonoStreamAppBuilder', () => {
+  // --------------------------------------------------------------------------
+  // Constructor Tests
+  // --------------------------------------------------------------------------
+  describe('constructor', () => {
+    test('creates default Hono app', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{ userId: string }, RPCConfig>()
+
+      RPC.CreateStream(
+        'StreamMessages',
+        { scope: 'messages', version: 1 },
+        async function* (ctx) {
+          yield { message: 'hello' }
+          yield { message: 'world' }
+        }
+      )
+
+      builder.register(RPC, () => ({ userId: '123' }))
+      const app = builder.build()
+
+      const res = await app.request('/messages/stream-messages/1', {
+        method: 'GET',
+      })
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('content-type')).toContain('text/event-stream')
+    })
+
+    test('uses provided Hono app', async () => {
+      const customApp = new Hono()
+      customApp.get('/custom', (c) => c.json({ custom: true }))
+
+      const builder = new HonoStreamAppBuilder({ app: customApp })
+      const RPC = Procedures<{ userId: string }, RPCConfig>()
+
+      RPC.CreateStream(
+        'StreamData',
+        { scope: 'data', version: 1 },
+        async function* () {
+          yield { data: 1 }
+        }
+      )
+
+      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 })
+
+      // Stream route should also work
+      const streamRes = await app.request('/data/stream-data/1')
+      expect(streamRes.status).toBe(200)
+    })
+
+    test('handles empty config', () => {
+      const builder = new HonoStreamAppBuilder({})
+      expect(builder.app).toBeDefined()
+      expect(builder.docs).toEqual([])
+    })
+
+    test('handles undefined config', () => {
+      const builder = new HonoStreamAppBuilder(undefined)
+      expect(builder.app).toBeDefined()
+      expect(builder.docs).toEqual([])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // SSE Streaming Tests
+  // --------------------------------------------------------------------------
+  describe('SSE streaming mode', () => {
+    test('streams multiple values as SSE events', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Counter',
+        { scope: 'counter', version: 1 },
+        async function* () {
+          yield { count: 1 }
+          yield { count: 2 }
+          yield { count: 3 }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/counter/counter/1')
+      expect(res.status).toBe(200)
+      expect(res.headers.get('content-type')).toContain('text/event-stream')
+
+      const text = await res.text()
+      expect(text).toContain('event: Counter')
+      expect(text).toContain('data: {"count":1}')
+      expect(text).toContain('data: {"count":2}')
+      expect(text).toContain('data: {"count":3}')
+      expect(text).toContain('id: 0')
+      expect(text).toContain('id: 1')
+      expect(text).toContain('id: 2')
+    })
+
+    test('uses SSE mode by default', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1')
+      expect(res.headers.get('content-type')).toContain('text/event-stream')
+    })
+
+    test('explicitly set SSE mode works', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1')
+      expect(res.headers.get('content-type')).toContain('text/event-stream')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Text Streaming Tests
+  // --------------------------------------------------------------------------
+  describe('text streaming mode', () => {
+    test('streams multiple values as newline-delimited JSON', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Counter',
+        { scope: 'counter', version: 1 },
+        async function* () {
+          yield { count: 1 }
+          yield { count: 2 }
+          yield { count: 3 }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/counter/counter/1')
+      expect(res.status).toBe(200)
+      expect(res.headers.get('content-type')).toContain('text/plain')
+
+      const text = await res.text()
+      const lines = text.trim().split('\n')
+      expect(lines).toHaveLength(3)
+      expect(JSON.parse(lines[0]!)).toEqual({ count: 1 })
+      expect(JSON.parse(lines[1]!)).toEqual({ count: 2 })
+      expect(JSON.parse(lines[2]!)).toEqual({ count: 3 })
+    })
+
+    test('per-factory streamMode overrides default', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}), { streamMode: 'text' })
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1')
+      expect(res.headers.get('content-type')).toContain('text/plain')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // HTTP Method Tests (GET and POST)
+  // --------------------------------------------------------------------------
+  describe('HTTP methods', () => {
+    test('GET request works', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { method: 'works' }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1', { method: 'GET' })
+      expect(res.status).toBe(200)
+    })
+
+    test('POST request works', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { method: 'works' }
+        }
+      )
+
+      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('GET request passes query params to handler', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Echo',
+        { scope: 'echo', version: 1 },
+        async function* (ctx, params) {
+          yield { received: params }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/echo/echo/1?foo=bar&baz=qux')
+      const text = await res.text()
+      const data = JSON.parse(text.trim())
+      expect(data.received).toEqual({ foo: 'bar', baz: 'qux' })
+    })
+
+    test('POST request passes JSON body to handler', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Echo',
+        { scope: 'echo', version: 1 },
+        async function* (ctx, params) {
+          yield { received: params }
+        }
+      )
+
+      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({ complex: { nested: 'data' }, array: [1, 2, 3] }),
+      })
+      const text = await res.text()
+      const data = JSON.parse(text.trim())
+      expect(data.received).toEqual({ complex: { nested: 'data' }, array: [1, 2, 3] })
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // pathPrefix Option Tests
+  // --------------------------------------------------------------------------
+  describe('pathPrefix option', () => {
+    test('uses custom pathPrefix for all routes', async () => {
+      const builder = new HonoStreamAppBuilder({ pathPrefix: '/api/v1' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/api/v1/test/test/1')
+      expect(res.status).toBe(200)
+    })
+
+    test('pathPrefix without leading slash gets normalized', async () => {
+      const builder = new HonoStreamAppBuilder({ pathPrefix: 'custom' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/custom/test/test/1')
+      expect(res.status).toBe(200)
+    })
+
+    test('pathPrefix appears in generated docs', () => {
+      const builder = new HonoStreamAppBuilder({ pathPrefix: '/api' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield {}
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      expect(builder.docs[0]!.path).toBe('/api/test/test/1')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Lifecycle Hooks Tests
+  // --------------------------------------------------------------------------
+  describe('lifecycle hooks', () => {
+    test('onRequestStart is called with context object', async () => {
+      const onRequestStart = vi.fn()
+      const builder = new HonoStreamAppBuilder({ onRequestStart })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await app.request('/test/test/1')
+
+      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 HonoStreamAppBuilder({ onRequestEnd })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await app.request('/test/test/1')
+
+      expect(onRequestEnd).toHaveBeenCalledTimes(1)
+      expect(onRequestEnd.mock.calls[0]![0]).toHaveProperty('req')
+    })
+
+    test('onStreamStart is called before streaming begins', async () => {
+      const onStreamStart = vi.fn()
+      const builder = new HonoStreamAppBuilder({ onStreamStart })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await app.request('/test/test/1')
+
+      expect(onStreamStart).toHaveBeenCalledTimes(1)
+      expect(onStreamStart.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+    })
+
+    test('onStreamEnd is called after stream completes', async () => {
+      const onStreamEnd = vi.fn()
+      const builder = new HonoStreamAppBuilder({ onStreamEnd })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1')
+      // Consume the stream to ensure it completes
+      await res.text()
+
+      expect(onStreamEnd).toHaveBeenCalledTimes(1)
+      expect(onStreamEnd.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+    })
+
+    test('hooks execute in correct order', async () => {
+      const order: string[] = []
+
+      const builder = new HonoStreamAppBuilder({
+        onRequestStart: () => order.push('request-start'),
+        onRequestEnd: () => order.push('request-end'),
+        onStreamStart: () => order.push('stream-start'),
+        onStreamEnd: () => order.push('stream-end'),
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          order.push('handler')
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/test/1')
+      // Consume the stream to ensure it completes
+      await res.text()
+
+      // Note: onRequestEnd middleware runs when response starts (before stream completes)
+      // while onStreamEnd runs when the stream finishes
+      expect(order).toContain('request-start')
+      expect(order).toContain('stream-start')
+      expect(order).toContain('handler')
+      expect(order).toContain('stream-end')
+      expect(order).toContain('request-end')
+      // request-start should be first
+      expect(order[0]).toBe('request-start')
+      // stream-start should be before handler
+      expect(order.indexOf('stream-start')).toBeLessThan(order.indexOf('handler'))
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // 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 HonoStreamAppBuilder({ onStreamError: errorHandler })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      // Error during context resolution (before streaming starts)
+      builder.register(RPC, () => {
+        throw new Error('Context error')
+      })
+
+      const app = builder.build()
+
+      // Since no streaming procedures were registered, this should 404
+      // Let's test with a real streaming procedure that throws during setup
+    })
+
+    test('errors during streaming are sent as error events (SSE mode)', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'ErrorStream',
+        { scope: 'error', version: 1 },
+        async function* () {
+          yield { count: 1 }
+          throw new Error('Stream error')
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/error/error-stream/1')
+      const text = await res.text()
+
+      expect(text).toContain('data: {"count":1}')
+      expect(text).toContain('event: error')
+      expect(text).toContain('Stream error')
+    })
+
+    test('errors during streaming are sent as JSON lines (text mode)', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'ErrorStream',
+        { scope: 'error', version: 1 },
+        async function* () {
+          yield { count: 1 }
+          throw new Error('Stream error')
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/error/error-stream/1')
+      const text = await res.text()
+      const lines = text.trim().split('\n')
+
+      expect(JSON.parse(lines[0]!)).toEqual({ count: 1 })
+      // Error is wrapped by Procedures with "Error in streaming handler for {name}" prefix
+      expect(JSON.parse(lines[1]!).error).toContain('Stream error')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Context Resolution Tests
+  // --------------------------------------------------------------------------
+  describe('context resolution', () => {
+    test('context can be a static object', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{ requestId: string }, RPCConfig>()
+
+      RPC.CreateStream(
+        'GetId',
+        { scope: 'get-id', version: 1 },
+        async function* (ctx) {
+          yield { id: ctx.requestId }
+        }
+      )
+
+      builder.register(RPC, { requestId: 'static-123' })
+      const app = builder.build()
+
+      const res = await app.request('/get-id/get-id/1')
+      const text = await res.text()
+      expect(JSON.parse(text.trim())).toEqual({ id: 'static-123' })
+    })
+
+    test('context can be sync function', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{ requestId: string }, RPCConfig>()
+
+      RPC.CreateStream(
+        'GetId',
+        { scope: 'get-id', version: 1 },
+        async function* (ctx) {
+          yield { id: ctx.requestId }
+        }
+      )
+
+      builder.register(RPC, (c) => ({ requestId: c.req.header('x-request-id') || 'unknown' }))
+      const app = builder.build()
+
+      const res = await app.request('/get-id/get-id/1', {
+        headers: { 'X-Request-Id': 'req-456' },
+      })
+      const text = await res.text()
+      expect(JSON.parse(text.trim())).toEqual({ id: 'req-456' })
+    })
+
+    test('context can be async function', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{ requestId: string }, RPCConfig>()
+
+      RPC.CreateStream(
+        'GetId',
+        { scope: 'get-id', version: 1 },
+        async function* (ctx) {
+          yield { id: ctx.requestId }
+        }
+      )
+
+      builder.register(RPC, async () => {
+        await new Promise((r) => setTimeout(r, 10))
+        return { requestId: 'async-789' }
+      })
+      const app = builder.build()
+
+      const res = await app.request('/get-id/get-id/1')
+      const text = await res.text()
+      expect(JSON.parse(text.trim())).toEqual({ id: 'async-789' })
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Documentation Tests
+  // --------------------------------------------------------------------------
+  describe('documentation', () => {
+    test('generates complete route documentation', () => {
+      const paramsSchema = v.object({ id: v.string() })
+      const yieldSchema = v.object({ message: v.string() })
+      const returnSchema = v.object({ total: v.number() })
+
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'StreamMessages',
+        {
+          scope: 'messages',
+          version: 1,
+          schema: { params: paramsSchema, yieldType: yieldSchema, returnType: returnSchema },
+        },
+        async function* () {
+          yield { message: 'test' }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc.path).toBe('/messages/stream-messages/1')
+      expect(doc.methods).toEqual(['get', 'post'])
+      expect(doc.streamMode).toBe('sse')
+      expect(doc.jsonSchema.params).toBeDefined()
+      expect(doc.jsonSchema.yieldType).toBeDefined()
+      expect(doc.jsonSchema.returnType).toBeDefined()
+    })
+
+    test('streamMode is recorded in docs', () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield {}
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      expect(builder.docs[0]!.streamMode).toBe('text')
+    })
+
+    test('per-factory streamMode is recorded in docs', () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield {}
+        }
+      )
+
+      builder.register(RPC, () => ({}), { streamMode: 'text' })
+      builder.build()
+
+      expect(builder.docs[0]!.streamMode).toBe('text')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Filter Tests (Only Streaming Procedures)
+  // --------------------------------------------------------------------------
+  describe('procedure filtering', () => {
+    test('only registers streaming procedures', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      // Regular procedure (should be ignored)
+      RPC.Create('NonStream', { scope: 'non-stream', version: 1 }, async () => ({
+        ok: true,
+      }))
+
+      // Streaming procedure (should be registered)
+      RPC.CreateStream(
+        'Stream',
+        { scope: 'stream', version: 1 },
+        async function* () {
+          yield { ok: true }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      // Only streaming procedure should be in docs
+      expect(builder.docs).toHaveLength(1)
+      expect(builder.docs[0]!.name).toBe('Stream')
+
+      // Non-streaming route should 404
+      const nonStreamRes = await app.request('/non-stream/non-stream/1', { method: 'POST' })
+      expect(nonStreamRes.status).toBe(404)
+
+      // Streaming route should work
+      const streamRes = await app.request('/stream/stream/1')
+      expect(streamRes.status).toBe(200)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // extendProcedureDoc Tests
+  // --------------------------------------------------------------------------
+  describe('extendProcedureDoc', () => {
+    test('adds custom properties to generated documentation', () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'StreamEvents',
+        { scope: 'events', version: 1 },
+        async function* () {
+          yield {}
+        }
+      )
+
+      builder.register(
+        RPC,
+        () => ({}),
+        {
+          extendProcedureDoc: ({ base, procedure }) => ({
+            summary: `Stream events endpoint`,
+            tags: ['events'],
+            operationId: procedure.name,
+          }),
+        }
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc).toHaveProperty('summary', 'Stream events endpoint')
+      expect(doc).toHaveProperty('tags', ['events'])
+      expect(doc).toHaveProperty('operationId', 'StreamEvents')
+    })
+
+    test('base properties take precedence over extended properties', () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Test',
+        { scope: 'test', version: 1 },
+        async function* () {
+          yield {}
+        }
+      )
+
+      builder.register(
+        RPC,
+        () => ({}),
+        {
+          extendProcedureDoc: () => ({
+            name: 'OverriddenName',
+            path: '/overridden/path',
+            methods: ['put'],
+            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.methods).toEqual(['get', 'post'])
+      // Custom field should be present
+      expect(doc).toHaveProperty('customField', 'custom-value')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Multiple Factory Tests
+  // --------------------------------------------------------------------------
+  describe('multiple factories', () => {
+    test('supports registering multiple factories', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+
+      const PublicRPC = Procedures<{ public: true }, RPCConfig>()
+      const PrivateRPC = Procedures<{ private: true }, RPCConfig>()
+
+      PublicRPC.CreateStream(
+        'PublicStream',
+        { scope: 'public', version: 1 },
+        async function* (ctx) {
+          yield { isPublic: ctx.public }
+        }
+      )
+
+      PrivateRPC.CreateStream(
+        'PrivateStream',
+        { scope: 'private', version: 1 },
+        async function* (ctx) {
+          yield { 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-stream/1')
+      const publicText = await publicRes.text()
+      expect(JSON.parse(publicText.trim())).toEqual({ isPublic: true })
+
+      const privateRes = await app.request('/private/private-stream/1')
+      const privateText = await privateRes.text()
+      expect(JSON.parse(privateText.trim())).toEqual({ isPrivate: true })
+    })
+
+    test('different factories can have different stream modes', async () => {
+      const builder = new HonoStreamAppBuilder()
+
+      const SSERPC = Procedures<{}, RPCConfig>()
+      const TextRPC = Procedures<{}, RPCConfig>()
+
+      SSERPC.CreateStream(
+        'SSEStream',
+        { scope: 'sse', version: 1 },
+        async function* () {
+          yield { mode: 'sse' }
+        }
+      )
+
+      TextRPC.CreateStream(
+        'TextStream',
+        { scope: 'text', version: 1 },
+        async function* () {
+          yield { mode: 'text' }
+        }
+      )
+
+      builder
+        .register(SSERPC, () => ({}), { streamMode: 'sse' })
+        .register(TextRPC, () => ({}), { streamMode: 'text' })
+
+      const app = builder.build()
+
+      const sseRes = await app.request('/sse/sse-stream/1')
+      expect(sseRes.headers.get('content-type')).toContain('text/event-stream')
+
+      const textRes = await app.request('/text/text-stream/1')
+      expect(textRes.headers.get('content-type')).toContain('text/plain')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Path Generation Tests
+  // --------------------------------------------------------------------------
+  describe('makeStreamHttpRoutePath', () => {
+    let builder: HonoStreamAppBuilder
+
+    beforeEach(() => {
+      builder = new HonoStreamAppBuilder()
+    })
+
+    test("simple scope: 'events' + 'StreamUpdates' → /events/stream-updates/1", () => {
+      const path = builder.makeStreamHttpRoutePath('StreamUpdates', { scope: 'events', version: 1 })
+      expect(path).toBe('/events/stream-updates/1')
+    })
+
+    test("array scope: ['events', 'live'] + 'Watch' → /events/live/watch/1", () => {
+      const path = builder.makeStreamHttpRoutePath('Watch', {
+        scope: ['events', 'live'],
+        version: 1,
+      })
+      expect(path).toBe('/events/live/watch/1')
+    })
+
+    test('version number included in path', () => {
+      const pathV1 = builder.makeStreamHttpRoutePath('Test', { scope: 'test', version: 1 })
+      const pathV2 = builder.makeStreamHttpRoutePath('Test', { scope: 'test', version: 2 })
+
+      expect(pathV1).toBe('/test/test/1')
+      expect(pathV2).toBe('/test/test/2')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Integration Test
+  // --------------------------------------------------------------------------
+  describe('integration', () => {
+    test('full workflow with streaming procedures', async () => {
+      type StreamContext = { userId: string }
+
+      const RPC = Procedures<StreamContext, RPCConfig>()
+
+      RPC.CreateStream(
+        'WatchNotifications',
+        {
+          scope: ['user', 'notifications'],
+          version: 1,
+          schema: {
+            params: v.object({ limit: v.number() }),
+            yieldType: v.object({ id: v.number(), message: v.string() }),
+          },
+        },
+        async function* (ctx, params) {
+          const limit = params?.limit ?? 3
+          for (let i = 1; i <= limit; i++) {
+            yield { id: i, message: `Notification ${i} for ${ctx.userId}` }
+          }
+        }
+      )
+
+      // Also create a non-streaming procedure to ensure it's filtered out
+      RPC.Create('GetNotificationCount', { scope: ['user', 'notifications'], version: 1 }, async () => ({
+        count: 10,
+      }))
+
+      const events: string[] = []
+
+      const builder = new HonoStreamAppBuilder({
+        defaultStreamMode: 'text',
+        onRequestStart: () => events.push('request-start'),
+        onRequestEnd: () => events.push('request-end'),
+        onStreamStart: (proc) => events.push(`stream-start:${proc.name}`),
+        onStreamEnd: (proc) => events.push(`stream-end:${proc.name}`),
+      })
+
+      builder.register(RPC, (c) => ({
+        userId: c.req.header('x-user-id') || 'anonymous',
+      }))
+
+      const app = builder.build()
+
+      // Only streaming procedure should be registered
+      expect(builder.docs).toHaveLength(1)
+      expect(builder.docs[0]!.name).toBe('WatchNotifications')
+      expect(builder.docs[0]!.methods).toEqual(['get', 'post'])
+
+      // Test streaming
+      const res = await app.request('/user/notifications/watch-notifications/1?limit=2', {
+        headers: { 'X-User-Id': 'user-123' },
+      })
+
+      expect(res.status).toBe(200)
+
+      const text = await res.text()
+      const lines = text.trim().split('\n')
+      expect(lines).toHaveLength(2)
+      expect(JSON.parse(lines[0]!)).toEqual({ id: 1, message: 'Notification 1 for user-123' })
+      expect(JSON.parse(lines[1]!)).toEqual({ id: 2, message: 'Notification 2 for user-123' })
+
+      // Verify hooks were called
+      expect(events).toContain('request-start')
+      expect(events).toContain('stream-start:WatchNotifications')
+      expect(events).toContain('stream-end:WatchNotifications')
+      expect(events).toContain('request-end')
+    })
+  })
+})