ts-procedures 3.4.0 → 4.0.1

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

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type, @typescript-eslint/explicit-function-return-type */
 import { describe, expect, test, vi, beforeEach } from 'vitest'
 import { Hono } from 'hono'
 import { v } from 'suretype'
@@ -20,9 +21,9 @@ describe('HonoStreamAppBuilder', () => {
       const builder = new HonoStreamAppBuilder()
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 
-      RPC.CreateStream('StreamMessages', { scope: 'messages', version: 1 }, async function* (ctx) {
+      RPC.CreateStream('StreamMessages', { scope: 'messages', version: 1 }, async function* () {
         yield { message: 'hello' }
-        yield { message: 'world' }
+        yield { data: { message: 'world' } }
       })
 
       builder.register(RPC, () => ({ userId: '123' }))
@@ -44,7 +45,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 
       RPC.CreateStream('StreamData', { scope: 'data', version: 1 }, async function* () {
-        yield { data: 1 }
+        yield { data: { data: 1 } }
       })
 
       builder.register(RPC, () => ({ userId: '123' }))
@@ -83,9 +84,9 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Counter', { scope: 'counter', version: 1 }, async function* () {
-        yield { count: 1 }
-        yield { count: 2 }
-        yield { count: 3 }
+        yield { data: { count: 1 } }
+        yield { data: { count: 2 } }
+        yield { data: { count: 3 } }
       })
 
       builder.register(RPC, () => ({}))
@@ -110,7 +111,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -125,7 +126,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -190,7 +191,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { method: 'works' }
+        yield { data: { method: 'works' } }
       })
 
       builder.register(RPC, () => ({}))
@@ -205,7 +206,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { method: 'works' }
+        yield { data: { method: 'works' } }
       })
 
       builder.register(RPC, () => ({}))
@@ -267,7 +268,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -282,7 +283,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -297,7 +298,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield {}
+        yield { data: {} }
       })
 
       builder.register(RPC, () => ({}))
@@ -317,7 +318,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -335,7 +336,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -354,7 +355,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -372,7 +373,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -399,7 +400,7 @@ describe('HonoStreamAppBuilder', () => {
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
         order.push('handler')
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -447,7 +448,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { count: params.count }
+          yield { data: { count: params.count } }
         }
       )
 
@@ -470,7 +471,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
-        yield { count: 1 }
+        yield { data: { count: 1 } }
         throw new Error('Stream error')
       })
 
@@ -520,7 +521,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { count: params.count }
+          yield { data: { count: params.count } }
         }
       )
 
@@ -557,7 +558,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { count: params.count }
+          yield { data: { count: params.count } }
         }
       )
 
@@ -583,7 +584,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 
       RPC.CreateStream('SecureStream', { scope: 'secure', version: 1 }, async function* (ctx) {
-        yield { userId: ctx.userId }
+        yield { data: { userId: ctx.userId } }
       })
 
       builder.register(RPC, () => {
@@ -603,7 +604,7 @@ describe('HonoStreamAppBuilder', () => {
     test('onMidStreamError returns custom value written to SSE stream', async () => {
       const onMidStreamError = vi.fn((procedure, c, error) => {
         return {
-          value: {
+          data: {
             type: 'error',
             code: 'STREAM_FAILED',
             message: error.message,
@@ -617,7 +618,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
-        yield { type: 'data', value: 1 }
+        yield { data: { type: 'data', value: 1 } }
         throw new Error('Something broke')
       })
 
@@ -641,7 +642,7 @@ describe('HonoStreamAppBuilder', () => {
     test('onMidStreamError returns custom value written to text stream', async () => {
       const onMidStreamError = vi.fn((procedure, c, error) => {
         return {
-          value: { type: 'error', message: error.message },
+          data: { type: 'error', message: error.message },
         }
       })
 
@@ -791,8 +792,95 @@ describe('HonoStreamAppBuilder', () => {
       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()
+
+      // SSE envelope fields are merged into yieldType
+      const yt = doc.jsonSchema.yieldType as Record<string, any>
+      expect(yt.required).toEqual(['data', 'event', 'id'])
+      expect(yt.properties.event).toEqual({ type: 'string' })
+      expect(yt.properties.id).toEqual({ type: 'string' })
+      expect(yt.properties.retry).toEqual({ type: 'number' })
+      // Developer's data property is preserved
+      expect(yt.properties.message).toBeDefined()
+    })
+
+    test('SSE mode generates SSE envelope even when no yieldType is defined', () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('NoYield', { scope: 'test', version: 1 }, async function* () {
+        yield {}
+      })
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const yt = builder.docs[0]!.jsonSchema.yieldType as Record<string, any>
+      expect(yt).toBeDefined()
+      expect(yt.type).toBe('object')
+      expect(yt.required).toEqual(['data', 'event', 'id'])
+      expect(yt.properties.data).toEqual({})
+      expect(yt.properties.event).toEqual({ type: 'string' })
+      expect(yt.properties.id).toEqual({ type: 'string' })
+      expect(yt.properties.retry).toEqual({ type: 'number' })
+    })
+
+    test('text mode passes yieldType through as-is', () => {
+      const yieldSchema = v.object({ chunk: v.string() })
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'TextStream',
+        { scope: 'test', version: 1, schema: { yieldType: yieldSchema } },
+        async function* () {
+          yield { chunk: 'hi' }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const yt = builder.docs[0]!.jsonSchema.yieldType as Record<string, any>
+      expect(yt).toBeDefined()
+      // Text mode should NOT have SSE envelope fields injected
+      expect(yt.properties?.event).toBeUndefined()
+      expect(yt.properties?.id).toBeUndefined()
+      expect(yt.properties?.retry).toBeUndefined()
+    })
+
+    test('developer-defined event/id in yieldType are preserved', () => {
+      const yieldSchema = v.object({
+        data: v.object({ msg: v.string() }),
+        event: v.string().const('custom-event'),
+        id: v.string().const('fixed-id'),
+      })
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'CustomSSE',
+        { scope: 'test', version: 1, schema: { yieldType: yieldSchema } },
+        async function* () {
+          // suretype sucks, we have to assert this as the exact type to satisfy the const assertions in the schema
+          yield { data: { msg: 'hi' }, event: 'custom-event', id: 'fixed-id' } as {
+            data: { msg: string }
+            event: 'custom-event'
+            id: 'fixed-id'
+          }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const yt = builder.docs[0]!.jsonSchema.yieldType as Record<string, any>
+      expect(yt.required).toEqual(['data', 'event', 'id'])
+      // Developer's custom event/id definitions take precedence
+      expect(yt.properties.event.const).toBe('custom-event')
+      expect(yt.properties.id.const).toBe('fixed-id')
+      // retry is still added as a base default
+      expect(yt.properties.retry).toEqual({ type: 'number' })
     })
 
     test('streamMode is recorded in docs', () => {
@@ -839,7 +927,7 @@ describe('HonoStreamAppBuilder', () => {
 
       // Streaming procedure (should be registered)
       RPC.CreateStream('Stream', { scope: 'stream', version: 1 }, async function* () {
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -868,11 +956,11 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('StreamEvents', { scope: 'events', version: 1 }, async function* () {
-        yield {}
+        yield { data: {} }
       })
 
       builder.register(RPC, () => ({}), {
-        extendProcedureDoc: ({ base, procedure }) => ({
+        extendProcedureDoc: ({ procedure }) => ({
           summary: `Stream events endpoint`,
           tags: ['events'],
           operationId: procedure.name,
@@ -891,7 +979,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield {}
+        yield { data: {} }
       })
 
       builder.register(RPC, () => ({}), {
@@ -962,7 +1050,7 @@ describe('HonoStreamAppBuilder', () => {
       const TextRPC = Procedures<{}, RPCConfig>()
 
       SSERPC.CreateStream('SSEStream', { scope: 'sse', version: 1 }, async function* () {
-        yield { mode: 'sse' }
+        yield { data: { mode: 'sse' } }
       })
 
       TextRPC.CreateStream('TextStream', { scope: 'text', version: 1 }, async function* () {
@@ -1026,7 +1114,7 @@ describe('HonoStreamAppBuilder', () => {
 
       RPC.CreateStream('CheckPrevalidated', { scope: 'check', version: 1 }, async function* (ctx) {
         receivedIsPrevalidated = ctx.isPrevalidated
-        yield { ok: true }
+        yield { data: { ok: true } }
       })
 
       builder.register(RPC, () => ({}))
@@ -1108,6 +1196,98 @@ describe('HonoStreamAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // SSE Yield Shape Tests
+  // --------------------------------------------------------------------------
+  describe('SSE yield shape', () => {
+    test('custom event names in yields', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+        yield { data: { type: 'user_joined' }, event: 'join' }
+        yield { data: { type: 'message' }, event: 'chat' }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/events/events/1')
+      const text = await res.text()
+
+      expect(text).toContain('event: join')
+      expect(text).toContain('event: chat')
+      expect(text).not.toContain('event: Events')
+    })
+
+    test('custom id in yields', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+        yield { data: { msg: 'first' }, id: 'msg-001' }
+        yield { data: { msg: 'second' }, id: 'msg-002' }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/events/events/1')
+      const text = await res.text()
+
+      expect(text).toContain('id: msg-001')
+      expect(text).toContain('id: msg-002')
+    })
+
+    test('string data pass-through without double-stringify', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+        yield { data: 'already a string' }
+        yield { data: { needs: 'stringify' } }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/events/events/1')
+      const text = await res.text()
+
+      // String data should be passed through as-is (not JSON-stringified again)
+      expect(text).toContain('data: already a string')
+      // Object data should be JSON-stringified
+      expect(text).toContain('data: {"needs":"stringify"}')
+    })
+
+    test('default event falls back to procedure name when omitted', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('MyProcedure', { scope: 'test', version: 1 }, async function* () {
+        yield { data: { value: 1 } }
+        yield { data: { value: 2 }, event: 'custom' }
+        yield { data: { value: 3 } }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/test/my-procedure/1')
+      const text = await res.text()
+
+      // Split into individual SSE messages
+      const messages = text.split('\n\n').filter(Boolean)
+
+      // First and third should use procedure name as event
+      expect(messages[0]).toContain('event: MyProcedure')
+      // Second should use custom event
+      expect(messages[1]).toContain('event: custom')
+      // Third should fall back to procedure name
+      expect(messages[2]).toContain('event: MyProcedure')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------

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

@@ -9,13 +9,24 @@ import { ProcedureValidationError } from '../../../errors.js'
 
 export type { StreamHttpRouteDoc, StreamMode }
 
+export type SSEYield = {
+  data: string | unknown
+  event?: string
+  id?: string
+  retry?: number
+}
+
 /**
  * Result from onMidStreamError callback.
- * @property value - The value to write to the stream (should match yieldType schema)
+ * @property data - The data to write to the stream (should match yieldType schema)
+ * @property event - Optional SSE event name (defaults to procedure name if data provided, 'error' otherwise)
+ * @property id - Optional SSE event id (auto-incremented if not provided)
  * @property closeStream - Whether to close the stream after writing (defaults to true)
  */
 export type MidStreamErrorResult = {
-  value: unknown
+  data: unknown
+  event?: string
+  id?: string
   closeStream?: boolean
 }
 
@@ -48,7 +59,7 @@ export type HonoStreamAppBuilderConfig = {
    * Should return a value matching your yieldType schema (e.g., error variant of a union).
    * Return undefined to use default behavior (writes { error: message }).
    *
-   * @returns { value, closeStream? } - value to yield, whether to close after (default true)
+   * @returns { data, event?, id?, closeStream? } - data to yield, optional SSE fields, whether to close after (default true)
    */
   onMidStreamError?: (
     procedure: TStreamProcedureRegistration,
@@ -230,10 +241,12 @@ export class HonoStreamAppBuilder {
       let eventId = 0
       try {
         for await (const value of generator) {
+          const currentId = eventId++
           await stream.writeSSE({
-            data: JSON.stringify(value),
-            event: procedure.name,
-            id: String(eventId++),
+            data: typeof value.data === 'string' ? value.data : JSON.stringify(value.data),
+            event: value.event ?? procedure.name,
+            id: value.id ?? String(currentId),
+            ...(value.retry !== undefined && { retry: value.retry }),
           })
         }
       } catch (error) {
@@ -245,12 +258,11 @@ export class HonoStreamAppBuilder {
         }
 
         // Write error value to stream
-        const errorValue = errorResult?.value ?? { error: (error as Error).message }
+        const errorData = errorResult?.data ?? { error: (error as Error).message }
         await stream.writeSSE({
-          data: JSON.stringify(errorValue),
-          // Use procedure event name if custom value provided, otherwise 'error'
-          event: errorResult?.value !== undefined ? procedure.name : 'error',
-          id: String(eventId++),
+          data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
+          event: errorResult?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
+          id: errorResult?.id ?? String(eventId++),
         })
 
         // closeStream defaults to true if not specified
@@ -296,8 +308,8 @@ export class HonoStreamAppBuilder {
         }
 
         // Write error value to stream
-        const errorValue = errorResult?.value ?? { error: (error as Error).message }
-        await stream.writeln(JSON.stringify(errorValue))
+        const errorData = errorResult?.data ?? { error: (error as Error).message }
+        await stream.writeln(JSON.stringify(errorData))
       } finally {
         if (this.config?.onStreamEnd) {
           this.config.onStreamEnd(procedure, c)
@@ -357,7 +369,38 @@ export class HonoStreamAppBuilder {
     if (config.schema?.params) {
       jsonSchema.params = config.schema.params
     }
-    if (config.schema?.yieldType) {
+    if (streamMode === 'sse') {
+      const sseBaseProperties = {
+        event: { type: 'string' },
+        id: { type: 'string' },
+        retry: { type: 'number' },
+      }
+
+      if (config.schema?.yieldType) {
+        // Developer's yieldType describes the full SSEYield envelope.
+        // Merge in SSE base fields for any the developer didn't define.
+        const userSchema = config.schema.yieldType as Record<string, any>
+        jsonSchema.yieldType = {
+          ...userSchema,
+          required: ['data', 'event', 'id'],
+          properties: {
+            ...sseBaseProperties,
+            ...(userSchema.properties ?? {}),
+          },
+        }
+      } else {
+        // No yieldType defined — generate a complete SSE envelope schema
+        jsonSchema.yieldType = {
+          type: 'object',
+          required: ['data', 'event', 'id'],
+          properties: {
+            data: {},
+            ...sseBaseProperties,
+          },
+        }
+      }
+    } else if (config.schema?.yieldType) {
+      // Text mode: pass through as-is
       jsonSchema.yieldType = config.schema.yieldType
     }
     if (config.schema?.returnType) {