ts-procedures 4.0.1 → 5.1.0

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

@@ -9,28 +9,37 @@ 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 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 data - The data to write as the SSE `data:` field content (should match yieldType schema)
  * @property closeStream - Whether to close the stream after writing (defaults to true)
  */
-export type MidStreamErrorResult = {
-  data: unknown
-  event?: string
-  id?: string
+export type MidStreamErrorResult<TErrorData = unknown> = {
+  data: TErrorData
   closeStream?: boolean
 }
 
-export type HonoStreamAppBuilderConfig = {
+export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
   /**
    * An existing Hono application instance to use.
    * If not provided, a new instance will be created.
@@ -42,8 +51,8 @@ export type HonoStreamAppBuilderConfig = {
   defaultStreamMode?: StreamMode
   onRequestStart?: (c: Context) => void
   onRequestEnd?: (c: Context) => void
-  onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context) => void
-  onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context) => void
+  onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+  onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   /**
    * Called for errors BEFORE streaming starts (validation, auth, context resolution).
    * Return value IS used as the HTTP response.
@@ -51,7 +60,7 @@ export type HonoStreamAppBuilderConfig = {
   onPreStreamError?: (
     procedure: TStreamProcedureRegistration,
     c: Context,
-    error: Error
+    error: ProcedureValidationError | Error
   ) => Response | Promise<Response>
   /**
    * Called for errors DURING streaming (generator throws).
@@ -59,13 +68,15 @@ 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 { data, event?, id?, closeStream? } - data to yield, optional SSE fields, whether to close after (default true)
+   * Use sse() to attach SSE metadata (event, id, retry) to the error data object.
+   *
+   * @returns { data, closeStream? } - data to yield, whether to close after (default true)
    */
   onMidStreamError?: (
     procedure: TStreamProcedureRegistration,
     c: Context,
     error: Error
-  ) => MidStreamErrorResult | undefined
+  ) => MidStreamErrorResult<TErrorData> | undefined
 }
 
 /**
@@ -81,11 +92,11 @@ export type HonoStreamAppBuilderConfig = {
  *   const app = streamApp.app; // Hono application
  *   const docs = streamApp.docs; // Stream route documentation
  */
-export class HonoStreamAppBuilder {
+export class HonoStreamAppBuilder<TErrorData = unknown> {
   /**
    * Constructor for HonoStreamAppBuilder.
    */
-  constructor(readonly config?: HonoStreamAppBuilderConfig) {
+  constructor(readonly config?: HonoStreamAppBuilderConfig<TErrorData>) {
     if (config?.app) {
       this._app = config.app
     }
@@ -96,7 +107,6 @@ export class HonoStreamAppBuilder {
         await next()
       })
     }
-
   }
 
   /**
@@ -203,7 +213,7 @@ export class HonoStreamAppBuilder {
         }
 
         if (this.config?.onStreamStart) {
-          this.config.onStreamStart(procedure, c)
+          this.config.onStreamStart(procedure, c, streamMode)
         }
 
         if (streamMode === 'sse') {
@@ -242,16 +252,25 @@ 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) {
         // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult | undefined
+        let errorResult: MidStreamErrorResult<TErrorData> | undefined
 
         if (this.config?.onMidStreamError) {
           errorResult = this.config.onMidStreamError(procedure, c, error as Error)
@@ -259,17 +278,20 @@ export class HonoStreamAppBuilder {
 
         // Write error value to stream
         const errorData = errorResult?.data ?? { error: (error as Error).message }
+        const sseMeta = getSSEMeta(errorData)
+
         await stream.writeSSE({
           data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
-          event: errorResult?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
-          id: errorResult?.id ?? String(eventId++),
+          event: sseMeta?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
+          id: sseMeta?.id ?? String(eventId++),
+          ...(sseMeta?.retry !== undefined && { retry: sseMeta.retry }),
         })
 
         // closeStream defaults to true if not specified
         // (stream closes naturally after this handler completes)
       } finally {
         if (this.config?.onStreamEnd) {
-          this.config.onStreamEnd(procedure, c)
+          this.config.onStreamEnd(procedure, c, 'sse')
         }
         if (this.config?.onRequestEnd) {
           this.config.onRequestEnd(c)
@@ -301,7 +323,7 @@ export class HonoStreamAppBuilder {
         }
       } catch (error) {
         // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult | undefined
+        let errorResult: MidStreamErrorResult<TErrorData> | undefined
 
         if (this.config?.onMidStreamError) {
           errorResult = this.config.onMidStreamError(procedure, c, error as Error)
@@ -312,7 +334,7 @@ export class HonoStreamAppBuilder {
         await stream.writeln(JSON.stringify(errorData))
       } finally {
         if (this.config?.onStreamEnd) {
-          this.config.onStreamEnd(procedure, c)
+          this.config.onStreamEnd(procedure, c, 'text')
         }
         if (this.config?.onRequestEnd) {
           this.config.onRequestEnd(c)
@@ -364,40 +386,22 @@ export class HonoStreamAppBuilder {
       prefix: this.config?.pathPrefix,
     })
     const methods = ['get', 'post'] as const
-    const jsonSchema: { params?: object; yieldType?: object; returnType?: object } = {}
+    const jsonSchema: { params?: Record<string, unknown>; yieldType?: Record<string, unknown>; returnType?: Record<string, unknown> } = {}
 
     if (config.schema?.params) {
       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

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

@@ -10,9 +10,9 @@ export interface StreamHttpRouteDoc extends RPCConfig {
   methods: ('get' | 'post')[]
   streamMode: StreamMode
   jsonSchema: {
-    params?: object
-    yieldType?: object
-    returnType?: object
+    params?: Record<string, unknown>
+    yieldType?: Record<string, unknown>
+    returnType?: Record<string, unknown>
   }
 }
 

package/src/implementations/types.ts

@@ -16,8 +16,8 @@ export interface RPCHttpRouteDoc extends RPCConfig {
   path: string
   method: 'post'
   jsonSchema: {
-    body?: object
-    response?: object
+    body?: Record<string, unknown>
+    response?: Record<string, unknown>
   }
 }
 
@@ -29,9 +29,9 @@ export interface StreamHttpRouteDoc extends RPCConfig {
   methods: ('get' | 'post')[]
   streamMode: StreamMode
   jsonSchema: {
-    params?: object    // Query params (GET) or body (POST)
-    yieldType?: object // Schema for each streamed value
-    returnType?: object // Final return (optional)
+    params?: Record<string, unknown>    // Query params (GET) or body (POST)
+    yieldType?: Record<string, unknown> // Schema for each streamed value
+    returnType?: Record<string, unknown> // Final return (optional)
   }
 }