ts-procedures 4.0.1 → 5.1.0

package/src/implementations/http/hono-stream/README.md

@@ -18,7 +18,7 @@ npm install hono
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoStreamAppBuilder } from 'ts-procedures/hono-stream'
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
 
 // Define your context and config types
 type StreamContext = { userId: string }
@@ -30,7 +30,7 @@ interface RPCConfig {
 // Create a procedures factory
 const StreamRPC = Procedures<StreamContext, RPCConfig>()
 
-// Create a streaming procedure
+// Create a streaming procedure — yield domain data directly
 StreamRPC.CreateStream(
   'WatchNotifications',
   {
@@ -42,8 +42,8 @@ StreamRPC.CreateStream(
   },
   async function* (ctx) {
     for (let i = 1; i <= 10; i++) {
-      // SSE mode: yield { data, event?, id?, retry? }
-      yield { data: { id: i, message: `Notification ${i}` }, event: 'notification' }
+      // Yield domain data directly — matches yieldType schema
+      yield { id: i, message: `Notification ${i}` }
       await new Promise((r) => setTimeout(r, 1000))
     }
   }
@@ -73,41 +73,52 @@ POST /{pathPrefix}/{scope...}/{procedureName}/{version}  (JSON body)
 - **GET**: For EventSource/SSE clients, params passed via query string
 - **POST**: For clients needing complex JSON body params
 
-## SSE Yield Shape
+## Yielding in SSE Mode
 
-In SSE mode, generators yield `SSEYield` objects that control the SSE wire format directly:
+Procedures yield **domain data directly** — the same shape as your `yieldType` schema. `HonoStreamAppBuilder` handles the SSE envelope (`event:`, `id:`, `data:`) automatically.
 
 ```typescript
-type SSEYield = {
-  data: string | unknown  // Required. Strings pass through as-is; objects are JSON.stringify'd
-  event?: string          // SSE event name. Defaults to procedure name
-  id?: string             // SSE event id. Auto-incremented if not provided
-  retry?: number          // SSE retry interval in ms. Passed through if present
+async function* (ctx) {
+  // Domain objects are JSON.stringify'd into the SSE data: field
+  yield { count: 1 }
+
+  // Strings are passed through as-is (no double-stringify)
+  yield 'raw string value'
 }
 ```
 
-This gives procedure authors full control over SSE event names, IDs, and data formatting — enabling native AI SDK streams, OpenAI-compatible streams, or any custom SSE protocol without frontend adapters.
+By default, SSE events use the procedure name as the `event:` field and auto-increment the `id:` field.
+
+### `sse()` Helper
+
+To override SSE metadata (event name, id, retry) for individual yields, use the `sse()` helper:
 
 ```typescript
-async function* (ctx) {
-  // Minimal: only data required (event defaults to procedure name, id auto-increments)
-  yield { data: { count: 1 } }
+import { sse } from 'ts-procedures/hono-stream'
 
+async function* (ctx) {
   // Custom event name
-  yield { data: { type: 'heartbeat' }, event: 'ping' }
+  yield sse({ type: 'heartbeat' }, { event: 'ping' })
 
   // Custom id
-  yield { data: { msg: 'hello' }, id: 'msg-001' }
+  yield sse({ msg: 'hello' }, { id: 'msg-001' })
 
-  // String data (no double-stringify)
-  yield { data: 'data: raw SSE line' }
+  // All SSE options
+  yield sse({ done: true }, { event: 'complete', id: 'final', retry: 5000 })
 
-  // All fields
-  yield { data: { done: true }, event: 'complete', id: 'final', retry: 5000 }
+  // sse() with no options — same as plain yield (uses defaults)
+  yield sse({ count: 1 })
 }
 ```
 
-**Text mode is unaffected** — text-mode generators still yield plain domain objects.
+`sse()` attaches metadata via a `WeakMap` side-channel, so:
+- The domain object passes through core validation (`validateYields`) unmodified
+- `JSON.stringify` only sees domain properties
+- AJV's `removeAdditional: true` doesn't affect the metadata
+
+> **Note:** `sse()` requires object values (used as `WeakMap` keys). Strings and other primitives cannot carry SSE metadata — they use the default event name (procedure name) and auto-incremented id.
+
+**Text mode is unaffected** — both plain objects and `sse()`-tagged objects are JSON-stringified identically. SSE metadata is ignored in text mode.
 
 ## Stream Modes
 
@@ -125,7 +136,7 @@ event: WatchNotifications
 data: {"id":1,"message":"Notification 1"}
 id: 0
 
-event: notification
+event: WatchNotifications
 data: {"id":2,"message":"Notification 2"}
 id: 1
 ```
@@ -138,7 +149,7 @@ eventSource.addEventListener('WatchNotifications', (event) => {
   const data = JSON.parse(event.data)
   console.log(data)
 })
-// Listen for custom events
+// Listen for custom events (when using sse() helper)
 eventSource.addEventListener('notification', (event) => {
   const data = JSON.parse(event.data)
   console.log(data)
@@ -180,18 +191,18 @@ while (true) {
 ### Builder Config
 
 ```typescript
-interface HonoStreamAppBuilderConfig {
+interface HonoStreamAppBuilderConfig<TErrorData = unknown> {
   app?: Hono                    // Use existing Hono instance
   pathPrefix?: string           // Prefix for all routes
   defaultStreamMode?: 'sse' | 'text'  // Default: 'sse'
   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
 
   // Error handling callbacks (see Error Handling section)
-  onPreStreamError?: (procedure, c, error) => Response | Promise<Response>
-  onMidStreamError?: (procedure, c, error) => { data: unknown; event?: string; id?: string; closeStream?: boolean } | undefined
+  onPreStreamError?: (procedure, c, error: ProcedureValidationError | Error) => Response | Promise<Response>
+  onMidStreamError?: (procedure, c, error) => MidStreamErrorResult<TErrorData> | undefined
 }
 ```
 
@@ -212,15 +223,17 @@ builder.register(factory, context, {
 Hooks execute in the following order:
 
 ```
-onRequestStart → [validation] → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
-                      ↓                              ↓
-               (validation error)              (stream error)
-                      ↓                              ↓
-             HTTP 400 response              error sent in stream
-                                                     ↓
-                                               onStreamEnd
+onRequestStart → [validation] → onStreamStart(proc, c, streamMode) → [yields...] → onStreamEnd(proc, c, streamMode) → onRequestEnd
+                      ↓                                                    ↓
+               (validation error)                                    (stream error)
+                      ↓                                                    ↓
+             HTTP 400 response                                    error sent in stream
+                                                                           ↓
+                                                                     onStreamEnd
 ```
 
+`onStreamStart` and `onStreamEnd` receive the resolved `streamMode` (`'sse'` or `'text'`) as their third argument.
+
 ## Validation
 
 ### Pre-validation
@@ -248,7 +261,7 @@ Streaming has two distinct error phases with different semantics:
 
 ### Pre-Stream Errors (`onPreStreamError`)
 
-Errors that occur **before** the stream starts (validation failures, context resolution errors). The return value **IS** used as the HTTP response:
+Errors that occur **before** the stream starts (validation failures, context resolution errors). The `error` parameter is typed as `ProcedureValidationError | Error`, allowing `instanceof` narrowing. The return value **IS** used as the HTTP response:
 
 ```typescript
 const builder = new HonoStreamAppBuilder({
@@ -271,23 +284,22 @@ const builder = new HonoStreamAppBuilder({
 
 ### Mid-Stream Errors (`onMidStreamError`)
 
-Errors that occur **during** streaming (generator throws). Since the stream is already open, HTTP status cannot change. Instead, return a value to write to the stream:
+Errors that occur **during** streaming (generator throws). Since the stream is already open, HTTP status cannot change. Return `{ data, closeStream? }` — the `data` value is written as the SSE `data:` field content.
+
+To control SSE metadata (event name, id, retry) on the error yield, wrap the data object with `sse()`:
 
 ```typescript
 const builder = new HonoStreamAppBuilder({
   onMidStreamError: (procedure, c, error) => {
     return {
-      // Data to write to stream (should match your yieldType schema)
-      data: {
+      // Data written as the SSE data: field (should match your yieldType schema)
+      // Use sse() to attach custom event/id/retry metadata
+      data: sse({
         type: 'error',
         code: 'STREAM_ERROR',
         message: error.message,
         retryable: false,
-      },
-      // Optional SSE event name (defaults to procedure name if data provided, 'error' otherwise)
-      event: 'error',
-      // Optional SSE event id (auto-incremented if not provided)
-      id: 'err-001',
+      }, { event: 'error', id: 'err-001' }),
       // Optional: whether to close stream after (default: true)
       closeStream: true,
     }
@@ -296,11 +308,36 @@ const builder = new HonoStreamAppBuilder({
 ```
 
 **Return values:**
-- `{ data, event?, id?, closeStream? }` - Write `data` to stream with optional SSE fields, optionally keep stream open
+- `{ data, closeStream? }` - Write `data` to stream. Use `sse(data, opts)` for custom SSE event/id/retry
 - `undefined` - Use default behavior: `{ error: message }` with `event: 'error'`
 
+Without `sse()`, the event defaults to the procedure name when custom data is provided, or `'error'` when using the default error format. The id auto-increments.
+
 ### Type-Safe Error Handling with Union Types
 
+Use the generic `TErrorData` parameter on `HonoStreamAppBuilder` to constrain the `onMidStreamError` return type:
+
+```typescript
+type ErrorPayload = {
+  type: 'error'
+  code: string
+  message: string
+  retryable: boolean
+}
+
+// TErrorData constrains what onMidStreamError can return
+const builder = new HonoStreamAppBuilder<ErrorPayload>({
+  onMidStreamError: (proc, c, error) => ({
+    data: {
+      type: 'error',
+      code: 'STREAM_ERROR',
+      message: error.message,
+      retryable: false,
+    }
+  })
+})
+```
+
 For type-safe error handling, define your `yieldType` as a discriminated union:
 
 ```typescript
@@ -325,21 +362,10 @@ StreamRPC.CreateStream('WatchEvents', {
     ])
   }
 }, async function* (ctx, params) {
-  yield { data: { type: 'event', eventType: 'user_joined', data: { userId: ctx.userId } } }
+  // Yield domain data directly — matches yieldType schema
+  yield { type: 'event', eventType: 'user_joined', data: { userId: ctx.userId } }
   // On error, the procedure throws and onMidStreamError handles it
 })
-
-// Configure error callback to return union-compatible error value
-const builder = new HonoStreamAppBuilder({
-  onMidStreamError: (proc, c, error) => ({
-    data: {
-      type: 'error',
-      code: 'STREAM_ERROR',
-      message: error.message,
-      retryable: false,
-    }
-  })
-})
 ```
 
 **Output (SSE mode):**
@@ -379,9 +405,25 @@ interface StreamHttpRouteDoc {
   scope: string | string[]
   version: number
   jsonSchema: {
-    params?: object     // From schema.params
-    yieldType?: object  // From schema.yieldType
-    returnType?: object // From schema.returnType
+    params?: Record<string, unknown>     // From schema.params
+    yieldType?: Record<string, unknown>  // SSE: envelope with data/event/id/retry; Text: from schema.yieldType
+    returnType?: Record<string, unknown> // From schema.returnType
+  }
+}
+```
+
+In SSE mode, the documented `yieldType` is an SSE envelope schema with the user's `yieldType` nested under the `data` property:
+
+```json
+{
+  "type": "object",
+  "description": "SSE message envelope. The data field contains the procedure yield value.",
+  "required": ["data", "event", "id"],
+  "properties": {
+    "data": { /* user's yieldType schema */ },
+    "event": { "type": "string" },
+    "id": { "type": "string" },
+    "retry": { "type": "number" }
   }
 }
 ```
@@ -398,7 +440,7 @@ RPC.Create('GetUser', config, async (ctx) => ({ user: 'data' }))
 
 // This WILL be registered
 RPC.CreateStream('WatchUser', config, async function* (ctx) {
-  yield { data: { update: 'data' } }
+  yield { update: 'data' }
 })
 ```
 
@@ -409,7 +451,7 @@ When a client disconnects, the stream's `onAbort` handler is triggered, which ca
 ```typescript
 RPC.CreateStream('LongStream', config, async function* (ctx) {
   while (!ctx.signal.aborted) {
-    yield { data: { tick: Date.now() } }
+    yield { tick: Date.now() }
     await new Promise((r) => setTimeout(r, 1000))
   }
 })
@@ -420,10 +462,52 @@ RPC.CreateStream('LongStream', config, async function* (ctx) {
 ```typescript
 import {
   HonoStreamAppBuilder,
-  HonoStreamAppBuilderConfig,
+  HonoStreamAppBuilderConfig, // Generic: HonoStreamAppBuilderConfig<TErrorData = unknown>
   StreamHttpRouteDoc,
   StreamMode,
-  SSEYield,              // Yield shape for SSE mode generators
-  MidStreamErrorResult,  // Return type for onMidStreamError callback
+  sse,                   // Helper to attach SSE metadata (event/id/retry) to yielded objects
+  SSEOptions,            // Type for sse() options: { event?, id?, retry? }
+  MidStreamErrorResult,  // Generic: MidStreamErrorResult<TErrorData = unknown>
 } from 'ts-procedures/hono-stream'
 ```
+
+## Migration Notes
+
+### Migrating from v5
+
+**Breaking: `MidStreamErrorResult` no longer has `event` and `id` fields.** Use `sse()` to attach SSE metadata to error data instead:
+
+```typescript
+// Before (v5)
+onMidStreamError: (proc, c, error) => ({
+  data: { type: 'error', message: error.message },
+  event: 'custom-error',
+  id: 'err-1',
+})
+
+// After (v6)
+onMidStreamError: (proc, c, error) => ({
+  data: sse(
+    { type: 'error', message: error.message },
+    { event: 'custom-error', id: 'err-1' }
+  ),
+})
+```
+
+**Breaking: `onStreamStart` / `onStreamEnd` now receive `streamMode` as a third parameter.**
+
+```typescript
+// Before (v5)
+onStreamStart: (procedure, c) => { ... }
+onStreamEnd: (procedure, c) => { ... }
+
+// After (v6)
+onStreamStart: (procedure, c, streamMode) => { ... }
+onStreamEnd: (procedure, c, streamMode) => { ... }
+```
+
+**Breaking: `StreamHttpRouteDoc.jsonSchema` fields narrowed from `object` to `Record<string, unknown>`.**
+
+**New: Generic `TErrorData` parameter** on `HonoStreamAppBuilder` and `MidStreamErrorResult` for type-safe `onMidStreamError` callbacks.
+
+**New: `onPreStreamError` error parameter** typed as `ProcedureValidationError | Error` for `instanceof` narrowing.