ts-procedures 4.0.1 → 5.0.0

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

@@ -3,7 +3,7 @@ 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'
 
 /**
@@ -23,7 +23,7 @@ describe('HonoStreamAppBuilder', () => {
 
       RPC.CreateStream('StreamMessages', { scope: 'messages', version: 1 }, async function* () {
         yield { message: 'hello' }
-        yield { data: { message: 'world' } }
+        yield { message: 'world' }
       })
 
       builder.register(RPC, () => ({ userId: '123' }))
@@ -45,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' }))
@@ -84,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, () => ({}))
@@ -111,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, () => ({}))
@@ -126,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, () => ({}))
@@ -191,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, () => ({}))
@@ -206,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, () => ({}))
@@ -268,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, () => ({}))
@@ -283,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, () => ({}))
@@ -298,7 +298,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}))
@@ -318,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, () => ({}))
@@ -336,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, () => ({}))
@@ -355,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, () => ({}))
@@ -373,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, () => ({}))
@@ -400,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, () => ({}))
@@ -448,7 +448,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { count: params.count }
         }
       )
 
@@ -471,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')
       })
 
@@ -521,7 +521,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { count: params.count }
         }
       )
 
@@ -558,7 +558,7 @@ describe('HonoStreamAppBuilder', () => {
           },
         },
         async function* (ctx, params) {
-          yield { data: { count: params.count } }
+          yield { count: params.count }
         }
       )
 
@@ -584,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, () => {
@@ -618,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')
       })
 
@@ -794,14 +794,15 @@ describe('HonoStreamAppBuilder', () => {
       expect(doc.jsonSchema.params).toBeDefined()
       expect(doc.jsonSchema.returnType).toBeDefined()
 
-      // SSE envelope fields are merged into yieldType
+      // 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 data property is preserved
-      expect(yt.properties.message).toBeDefined()
+      // 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', () => {
@@ -818,7 +819,9 @@ describe('HonoStreamAppBuilder', () => {
       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' })
@@ -849,25 +852,21 @@ describe('HonoStreamAppBuilder', () => {
       expect(yt.properties?.retry).toBeUndefined()
     })
 
-    test('developer-defined event/id in yieldType are preserved', () => {
+    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({
-        data: v.object({ msg: v.string() }),
-        event: v.string().const('custom-event'),
-        id: v.string().const('fixed-id'),
+        id: v.number(),
+        message: v.string(),
       })
       const builder = new HonoStreamAppBuilder()
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
-        'CustomSSE',
+        'Notifications',
         { 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'
-          }
+          yield { id: 42, message: 'hello' }
         }
       )
 
@@ -876,11 +875,11 @@ describe('HonoStreamAppBuilder', () => {
 
       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' })
+      // 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', () => {
@@ -927,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, () => ({}))
@@ -956,7 +955,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('StreamEvents', { scope: 'events', version: 1 }, async function* () {
-        yield { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}), {
@@ -979,7 +978,7 @@ describe('HonoStreamAppBuilder', () => {
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
-        yield { data: {} }
+        yield {}
       })
 
       builder.register(RPC, () => ({}), {
@@ -1050,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* () {
@@ -1114,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, () => ({}))
@@ -1200,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, () => ({}))
@@ -1220,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, () => ({}))
@@ -1244,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, () => ({}))
@@ -1265,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, () => ({}))
@@ -1288,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
   // --------------------------------------------------------------------------
@@ -1330,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) => ({
@@ -1360,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) {
@@ -370,34 +391,16 @@ export class HonoStreamAppBuilder {
       jsonSchema.params = config.schema.params
     }
     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,
-          },
-        }
+      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