ts-procedures 5.0.0 → 5.1.0

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

@@ -3,8 +3,9 @@ import { describe, expect, test, vi, beforeEach } from 'vitest'
 import { Hono } from 'hono'
 import { v } from 'suretype'
 import { Procedures } from '../../../index.js'
-import { HonoStreamAppBuilder, sse } from './index.js'
-import { RPCConfig } from '../../types.js'
+import { HonoStreamAppBuilder, sse, MidStreamErrorResult } from './index.js'
+import { RPCConfig, StreamMode } from '../../types.js'
+import { ProcedureValidationError } from '../../../errors.js'
 
 /**
  * HonoStreamAppBuilder Test Suite
@@ -349,7 +350,7 @@ describe('HonoStreamAppBuilder', () => {
       expect(onRequestEnd.mock.calls[0]![0]).toHaveProperty('req')
     })
 
-    test('onStreamStart is called before streaming begins', async () => {
+    test('onStreamStart is called before streaming begins with streamMode', async () => {
       const onStreamStart = vi.fn()
       const builder = new HonoStreamAppBuilder({ onStreamStart })
       const RPC = Procedures<{}, RPCConfig>()
@@ -365,9 +366,10 @@ describe('HonoStreamAppBuilder', () => {
 
       expect(onStreamStart).toHaveBeenCalledTimes(1)
       expect(onStreamStart.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+      expect(onStreamStart.mock.calls[0]![2]).toBe('sse')
     })
 
-    test('onStreamEnd is called after stream completes', async () => {
+    test('onStreamEnd is called after stream completes with streamMode', async () => {
       const onStreamEnd = vi.fn()
       const builder = new HonoStreamAppBuilder({ onStreamEnd })
       const RPC = Procedures<{}, RPCConfig>()
@@ -385,6 +387,7 @@ describe('HonoStreamAppBuilder', () => {
 
       expect(onStreamEnd).toHaveBeenCalledTimes(1)
       expect(onStreamEnd.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+      expect(onStreamEnd.mock.calls[0]![2]).toBe('sse')
     })
 
     test('hooks execute in correct order', async () => {
@@ -1387,6 +1390,212 @@ describe('HonoStreamAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // streamMode in Lifecycle Hooks
+  // --------------------------------------------------------------------------
+  describe('streamMode in lifecycle hooks', () => {
+    test('onStreamStart receives sse streamMode', 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)
+      const [, , streamMode] = onStreamStart.mock.calls[0]!
+      expect(streamMode).toBe('sse')
+    })
+
+    test('onStreamEnd receives text streamMode', async () => {
+      const onStreamEnd = vi.fn()
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text', 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')
+      await res.text()
+
+      expect(onStreamEnd).toHaveBeenCalledTimes(1)
+      const [, , streamMode] = onStreamEnd.mock.calls[0]!
+      expect(streamMode).toBe('text')
+    })
+
+    test('onStreamStart and onStreamEnd receive matching streamMode', async () => {
+      const modes: { start?: StreamMode; end?: StreamMode } = {}
+      const builder = new HonoStreamAppBuilder({
+        defaultStreamMode: 'text',
+        onStreamStart: (_proc, _c, mode) => { modes.start = mode },
+        onStreamEnd: (_proc, _c, mode) => { modes.end = mode },
+      })
+      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')
+      await res.text()
+
+      expect(modes.start).toBe('text')
+      expect(modes.end).toBe('text')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // sse() in onMidStreamError
+  // --------------------------------------------------------------------------
+  describe('sse() in onMidStreamError', () => {
+    test('sse() wraps error data with custom event and id', async () => {
+      const builder = new HonoStreamAppBuilder({
+        onMidStreamError: (procedure, c, error) => {
+          return {
+            data: sse(
+              { type: 'error', message: error.message },
+              { event: 'custom-error', id: 'err-1' }
+            ),
+          }
+        },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+        yield { type: 'data', value: 1 }
+        throw new Error('Something broke')
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/error/error-stream/1')
+      const text = await res.text()
+
+      // Normal yield
+      expect(text).toContain('data: {"type":"data","value":1}')
+      // Error yield with sse() metadata
+      expect(text).toContain('event: custom-error')
+      expect(text).toContain('id: err-1')
+      expect(text).toContain('"type":"error"')
+    })
+
+    test('string error data without sse() uses default event and id', async () => {
+      const builder = new HonoStreamAppBuilder({
+        onMidStreamError: () => {
+          return { data: 'plain error string' }
+        },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+        yield { count: 1 }
+        throw new Error('fail')
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/error/error-stream/1')
+      const text = await res.text()
+
+      // String data can't use sse() (not an object), so defaults apply
+      expect(text).toContain('data: plain error string')
+      // event defaults to procedure name when data is provided
+      expect(text).toContain('event: ErrorStream')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Generic TErrorData
+  // --------------------------------------------------------------------------
+  describe('generic TErrorData', () => {
+    test('typed builder constrains onMidStreamError return type', async () => {
+      type ErrorPayload = { type: 'error'; code: string; message: string }
+
+      const builder = new HonoStreamAppBuilder<ErrorPayload>({
+        onMidStreamError: (_procedure, _c, error) => {
+          // This satisfies MidStreamErrorResult<ErrorPayload>
+          return {
+            data: { type: 'error', code: 'STREAM_FAILED', message: error.message },
+          }
+        },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+        yield { value: 1 }
+        throw new Error('typed 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('"code":"STREAM_FAILED"')
+      // Error message may be wrapped by Procedures with prefix
+      expect(text).toContain('typed error')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // ProcedureValidationError narrowing in onPreStreamError
+  // --------------------------------------------------------------------------
+  describe('ProcedureValidationError narrowing', () => {
+    test('instanceof check works in onPreStreamError', async () => {
+      let wasValidationError = false
+
+      const builder = new HonoStreamAppBuilder({
+        onPreStreamError: (procedure, c, error) => {
+          if (error instanceof ProcedureValidationError) {
+            wasValidationError = true
+            return c.json({ validation: true, errors: error.errors }, 422)
+          }
+          return c.json({ error: error.message }, 500)
+        },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'Validated',
+        {
+          scope: 'validated',
+          version: 1,
+          schema: { params: v.object({ count: v.number() }) },
+        },
+        async function* (ctx, params) {
+          yield { count: params.count }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/validated/validated/1?count=not-a-number')
+
+      expect(res.status).toBe(422)
+      expect(wasValidationError).toBe(true)
+      const body = await res.json()
+      expect(body.validation).toBe(true)
+      expect(body.errors).toBeDefined()
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------

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

@@ -32,18 +32,14 @@ function getSSEMeta(value: unknown): SSEOptions | undefined {
 /**
  * Result from onMidStreamError callback.
  * @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)
  */
-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.
@@ -55,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.
@@ -64,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).
@@ -72,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
 }
 
 /**
@@ -94,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
     }
@@ -215,7 +213,7 @@ export class HonoStreamAppBuilder {
         }
 
         if (this.config?.onStreamStart) {
-          this.config.onStreamStart(procedure, c)
+          this.config.onStreamStart(procedure, c, streamMode)
         }
 
         if (streamMode === 'sse') {
@@ -272,7 +270,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)
@@ -280,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)
@@ -322,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)
@@ -333,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)
@@ -385,7 +386,7 @@ 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

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)
   }
 }