ts-procedures 4.0.0 → 5.0.0

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

@@ -1,8 +1,9 @@
+/* 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'
 import { Procedures } from '../../../index.js'
-import { HonoStreamAppBuilder } from './index.js'
+import { HonoStreamAppBuilder, sse } from './index.js'
 import { RPCConfig } from '../../types.js'
 
 /**
@@ -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 { data: { message: 'world' } }
+        yield { 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: { data: 1 } }
+        yield { 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 { data: { count: 1 } }
-        yield { data: { count: 2 } }
-        yield { data: { count: 3 } }
+        yield { count: 1 }
+        yield { count: 2 }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: { method: 'works' } }
+        yield { 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 { data: { method: 'works' } }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}))
@@ -317,7 +318,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { data: { ok: true } }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: { ok: true } }
+        yield { 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 { data: { ok: true } }
+        yield { ok: true }
       })
 
       builder.register(RPC, () => ({}))
@@ -399,7 +400,7 @@ describe('HonoStreamAppBuilder', () => {
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
         order.push('handler')
-        yield { data: { ok: true } }
+        yield { ok: true }
       })
 
       builder.register(RPC, () => ({}))
@@ -447,7 +448,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { count: params.count }
         }
       )
 
@@ -470,7 +471,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
-        yield { data: { count: 1 } }
+        yield { count: 1 }
         throw new Error('Stream error')
       })
 
@@ -520,7 +521,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { count: params.count }
         }
       )
 
@@ -557,7 +558,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { 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 { data: { userId: ctx.userId } }
+        yield { userId: ctx.userId }
       })
 
       builder.register(RPC, () => {
@@ -617,7 +618,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
-        yield { data: { type: 'data', value: 1 } }
+        yield { type: 'data', value: 1 }
         throw new Error('Something broke')
       })
 
@@ -791,8 +792,94 @@ 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()
+
+      // yieldType is nested under SSE envelope's data property
+      const yt = doc.jsonSchema.yieldType as Record<string, any>
+      expect(yt.description).toBe('SSE message envelope. The data field contains the procedure yield value.')
+      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 yieldType is nested under data
+      expect(yt.properties.data.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.description).toBe('SSE message envelope. The data field contains the procedure yield value.')
+      expect(yt.required).toEqual(['data', 'event', 'id'])
+      // data is empty schema when no yieldType defined
+      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('yieldType with id property does not collide with SSE id field', () => {
+      // User's yieldType has an `id` field (number) — this should be nested under
+      // the SSE envelope's `data` property, not collide with the SSE `id` (string)
+      const yieldSchema = v.object({
+        id: v.number(),
+        message: v.string(),
+      })
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Notifications',
+        { scope: 'test', version: 1, schema: { yieldType: yieldSchema } },
+        async function* () {
+          yield { id: 42, message: 'hello' }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const yt = builder.docs[0]!.jsonSchema.yieldType as Record<string, any>
+      expect(yt.required).toEqual(['data', 'event', 'id'])
+      // SSE envelope id is a string
+      expect(yt.properties.id).toEqual({ type: 'string' })
+      // User's id (number) is safely nested under data
+      expect(yt.properties.data.properties.id.type).toBe('number')
+      expect(yt.properties.data.properties.message.type).toBe('string')
     })
 
     test('streamMode is recorded in docs', () => {
@@ -839,7 +926,7 @@ describe('HonoStreamAppBuilder', () => {
 
       // Streaming procedure (should be registered)
       RPC.CreateStream('Stream', { scope: 'stream', version: 1 }, async function* () {
-        yield { data: { ok: true } }
+        yield { ok: true }
       })
 
       builder.register(RPC, () => ({}))
@@ -868,11 +955,11 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('StreamEvents', { scope: 'events', version: 1 }, async function* () {
-        yield { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}), {
-        extendProcedureDoc: ({ base, procedure }) => ({
+        extendProcedureDoc: ({ procedure }) => ({
           summary: `Stream events endpoint`,
           tags: ['events'],
           operationId: procedure.name,
@@ -891,7 +978,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}), {
@@ -962,7 +1049,7 @@ describe('HonoStreamAppBuilder', () => {
       const TextRPC = Procedures<{}, RPCConfig>()
 
       SSERPC.CreateStream('SSEStream', { scope: 'sse', version: 1 }, async function* () {
-        yield { data: { mode: 'sse' } }
+        yield { mode: 'sse' }
       })
 
       TextRPC.CreateStream('TextStream', { scope: 'text', version: 1 }, async function* () {
@@ -1026,7 +1113,7 @@ describe('HonoStreamAppBuilder', () => {
 
       RPC.CreateStream('CheckPrevalidated', { scope: 'check', version: 1 }, async function* (ctx) {
         receivedIsPrevalidated = ctx.isPrevalidated
-        yield { data: { ok: true } }
+        yield { ok: true }
       })
 
       builder.register(RPC, () => ({}))
@@ -1112,13 +1199,13 @@ describe('HonoStreamAppBuilder', () => {
   // SSE Yield Shape Tests
   // --------------------------------------------------------------------------
   describe('SSE yield shape', () => {
-    test('custom event names in yields', async () => {
+    test('custom event names via sse() helper', 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' }
+        yield sse({ type: 'user_joined' }, { event: 'join' })
+        yield sse({ type: 'message' }, { event: 'chat' })
       })
 
       builder.register(RPC, () => ({}))
@@ -1132,13 +1219,13 @@ describe('HonoStreamAppBuilder', () => {
       expect(text).not.toContain('event: Events')
     })
 
-    test('custom id in yields', async () => {
+    test('custom id via sse() helper', 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' }
+        yield sse({ msg: 'first' }, { id: 'msg-001' })
+        yield sse({ msg: 'second' }, { id: 'msg-002' })
       })
 
       builder.register(RPC, () => ({}))
@@ -1156,8 +1243,8 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
-        yield { data: 'already a string' }
-        yield { data: { needs: 'stringify' } }
+        yield 'already a string'
+        yield { needs: 'stringify' }
       })
 
       builder.register(RPC, () => ({}))
@@ -1177,9 +1264,9 @@ describe('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 } }
+        yield { value: 1 }
+        yield sse({ value: 2 }, { event: 'custom' })
+        yield { value: 3 }
       })
 
       builder.register(RPC, () => ({}))
@@ -1200,6 +1287,106 @@ describe('HonoStreamAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // sse() Helper Tests
+  // --------------------------------------------------------------------------
+  describe('sse() helper', () => {
+    test('tagged yields with custom event/id/retry', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Tagged', { scope: 'tagged', version: 1 }, async function* () {
+        yield sse({ count: 1 }, { event: 'tick', id: 'evt-1', retry: 5000 })
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/tagged/tagged/1')
+      const text = await res.text()
+
+      expect(text).toContain('event: tick')
+      expect(text).toContain('id: evt-1')
+      expect(text).toContain('retry: 5000')
+      expect(text).toContain('data: {"count":1}')
+    })
+
+    test('plain domain objects use procedure name and auto-incremented id', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Plain', { scope: 'plain', version: 1 }, async function* () {
+        yield { a: 1 }
+        yield { a: 2 }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/plain/plain/1')
+      const text = await res.text()
+
+      const messages = text.split('\n\n').filter(Boolean)
+      expect(messages[0]).toContain('event: Plain')
+      expect(messages[0]).toContain('id: 0')
+      expect(messages[0]).toContain('data: {"a":1}')
+      expect(messages[1]).toContain('event: Plain')
+      expect(messages[1]).toContain('id: 1')
+      expect(messages[1]).toContain('data: {"a":2}')
+    })
+
+    test('sse() metadata is invisible in text mode', async () => {
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('TextTagged', { scope: 'text', version: 1 }, async function* () {
+        yield sse({ count: 1 }, { event: 'tick' })
+        yield { count: 2 }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/text/text-tagged/1')
+      const text = await res.text()
+      const lines = text.trim().split('\n')
+
+      // Text mode just JSON-stringifies — sse() metadata is not visible
+      expect(JSON.parse(lines[0]!)).toEqual({ count: 1 })
+      expect(JSON.parse(lines[1]!)).toEqual({ count: 2 })
+    })
+
+    test('sse() with partial options', async () => {
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('Partial', { scope: 'partial', version: 1 }, async function* () {
+        yield sse({ v: 1 }, { event: 'custom' })
+        yield sse({ v: 2 }, { id: 'my-id' })
+        yield sse({ v: 3 })
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/partial/partial/1')
+      const text = await res.text()
+      const messages = text.split('\n\n').filter(Boolean)
+
+      // First: custom event, auto id
+      expect(messages[0]).toContain('event: custom')
+      expect(messages[0]).toContain('id: 0')
+
+      // Second: default event, custom id
+      expect(messages[1]).toContain('event: Partial')
+      expect(messages[1]).toContain('id: my-id')
+
+      // Third: sse() with no options — same as plain object (defaults)
+      expect(messages[2]).toContain('event: Partial')
+      expect(messages[2]).toContain('id: 2')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------
@@ -1242,8 +1429,8 @@ describe('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}`),
+        onStreamStart: () => events.push('stream-start'),
+        onStreamEnd: () => events.push('stream-end'),
       })
 
       builder.register(RPC, (c) => ({
@@ -1272,8 +1459,8 @@ describe('HonoStreamAppBuilder', () => {
 
       // Verify hooks were called
       expect(events).toContain('request-start')
-      expect(events).toContain('stream-start:WatchNotifications')
-      expect(events).toContain('stream-end:WatchNotifications')
+      expect(events).toContain('stream-start')
+      expect(events).toContain('stream-end')
       expect(events).toContain('request-end')
     })
   })

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

@@ -9,16 +9,29 @@ import { ProcedureValidationError } from '../../../errors.js'
 
 export type { StreamHttpRouteDoc, StreamMode }
 
-export type SSEYield = {
-  data: string | unknown
+export type SSEOptions = {
   event?: string
   id?: string
   retry?: number
 }
 
+const sseMetadata = new WeakMap<object, SSEOptions>()
+
+export function sse<T extends object>(data: T, options?: SSEOptions): T {
+  sseMetadata.set(data, options ?? {})
+  return data
+}
+
+function getSSEMeta(value: unknown): SSEOptions | undefined {
+  if (typeof value === 'object' && value !== null) {
+    return sseMetadata.get(value)
+  }
+  return undefined
+}
+
 /**
  * Result from onMidStreamError callback.
- * @property data - The data to write to the stream (should match yieldType schema)
+ * @property data - The data to write as the SSE `data:` field content (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)
@@ -96,7 +109,6 @@ export class HonoStreamAppBuilder {
         await next()
       })
     }
-
   }
 
   /**
@@ -242,11 +254,20 @@ export class HonoStreamAppBuilder {
       try {
         for await (const value of generator) {
           const currentId = eventId++
+          const meta = getSSEMeta(value)
+
+          const data =
+            typeof value === 'string'
+              ? value
+              : value != null
+                ? JSON.stringify(value)
+                : ''
+
           await stream.writeSSE({
-            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 }),
+            data,
+            event: meta?.event ?? procedure.name,
+            id: meta?.id ?? String(currentId),
+            ...(meta?.retry !== undefined && { retry: meta.retry }),
           })
         }
       } catch (error) {
@@ -369,7 +390,20 @@ export class HonoStreamAppBuilder {
     if (config.schema?.params) {
       jsonSchema.params = config.schema.params
     }
-    if (config.schema?.yieldType) {
+    if (streamMode === 'sse') {
+      jsonSchema.yieldType = {
+        type: 'object',
+        description: 'SSE message envelope. The data field contains the procedure yield value.',
+        required: ['data', 'event', 'id'],
+        properties: {
+          data: config.schema?.yieldType ?? {},
+          event: { type: 'string' },
+          id: { type: 'string' },
+          retry: { type: 'number' },
+        },
+      }
+    } else if (config.schema?.yieldType) {
+      // Text mode: pass through as-is
       jsonSchema.yieldType = config.schema.yieldType
     }
     if (config.schema?.returnType) {