ts-procedures 5.8.0 → 5.9.0

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

@@ -0,0 +1,525 @@
+# Hono Stream Implementation
+
+HTTP streaming and SSE endpoints for streaming procedures created with `CreateStream`.
+
+## Overview
+
+`HonoStreamAppBuilder` provides a builder pattern for creating streaming HTTP endpoints in Hono. It handles `AsyncGenerator` handlers and supports both Server-Sent Events (SSE) and plain text streaming modes.
+
+## Installation
+
+Requires `hono` as a peer dependency:
+
+```bash
+npm install hono
+```
+
+## Quick Start
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+// Define your context and config types
+type StreamContext = { userId: string }
+interface RPCConfig {
+  scope: string | string[]
+  version: number
+}
+
+// Create a procedures factory
+const StreamRPC = Procedures<StreamContext, RPCConfig>()
+
+// Create a streaming procedure — yield domain data directly
+StreamRPC.CreateStream(
+  'WatchNotifications',
+  {
+    scope: ['user', 'notifications'],
+    version: 1,
+    schema: {
+      yieldType: v.object({ id: v.number(), message: v.string() }),
+    },
+  },
+  async function* (ctx) {
+    for (let i = 1; i <= 10; i++) {
+      // Yield domain data directly — matches yieldType schema
+      yield { id: i, message: `Notification ${i}` }
+      await new Promise((r) => setTimeout(r, 1000))
+    }
+  }
+)
+
+// Build the Hono app
+const builder = new HonoStreamAppBuilder()
+  .register(StreamRPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+
+const app = builder.build()
+
+// Access documentation
+const docs = builder.docs
+```
+
+## HTTP Methods
+
+Both GET and POST methods are supported for each streaming endpoint:
+
+```
+GET  /{pathPrefix}/{scope...}/{procedureName}/{version}?param1=value1
+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
+
+## Yielding in SSE Mode
+
+Procedures yield **domain data directly** — the same shape as your `yieldType` schema. `HonoStreamAppBuilder` handles the SSE envelope (`event:`, `id:`, `data:`) automatically.
+
+```typescript
+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'
+}
+```
+
+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
+import { sse } from 'ts-procedures/hono-stream'
+
+async function* (ctx) {
+  // Custom event name
+  yield sse({ type: 'heartbeat' }, { event: 'ping' })
+
+  // Custom id
+  yield sse({ msg: 'hello' }, { id: 'msg-001' })
+
+  // All SSE options
+  yield sse({ done: true }, { event: 'complete', id: 'final', retry: 5000 })
+
+  // sse() with no options — same as plain yield (uses defaults)
+  yield sse({ count: 1 })
+}
+```
+
+`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
+
+### SSE Mode (default)
+
+Returns `text/event-stream` content type with SSE-formatted messages:
+
+```typescript
+const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+```
+
+Response format:
+```
+event: WatchNotifications
+data: {"id":1,"message":"Notification 1"}
+id: 0
+
+event: WatchNotifications
+data: {"id":2,"message":"Notification 2"}
+id: 1
+```
+
+Client usage:
+```typescript
+const eventSource = new EventSource('/user/notifications/watch-notifications/1')
+// Listen for default event (procedure name)
+eventSource.addEventListener('WatchNotifications', (event) => {
+  const data = JSON.parse(event.data)
+  console.log(data)
+})
+// Listen for custom events (when using sse() helper)
+eventSource.addEventListener('notification', (event) => {
+  const data = JSON.parse(event.data)
+  console.log(data)
+})
+```
+
+### Text Mode
+
+Returns `text/plain` content type with newline-delimited JSON:
+
+```typescript
+const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+```
+
+Response format:
+```
+{"key":"value"}
+{"key":"value2"}
+```
+
+Client usage:
+```typescript
+const response = await fetch('/user/notifications/watch-notifications/1')
+const reader = response.body.getReader()
+const decoder = new TextDecoder()
+
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+  const lines = decoder.decode(value).split('\n')
+  for (const line of lines) {
+    if (line) console.log(JSON.parse(line))
+  }
+}
+```
+
+## Configuration
+
+### Builder Config
+
+```typescript
+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, streamMode: StreamMode) => void
+  onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
+
+  // Error handling callbacks (see Error Handling section)
+  onPreStreamError?: (procedure, c, error: ProcedureValidationError | Error) => Response | Promise<Response>
+  onMidStreamError?: (procedure, c, error) => MidStreamErrorResult<TErrorData> | undefined
+}
+```
+
+### Per-Factory Options
+
+```typescript
+builder.register(factory, context, {
+  streamMode: 'text',  // Override default mode for this factory
+  extendProcedureDoc: ({ base, procedure }) => ({
+    summary: 'Custom documentation',
+    tags: ['streaming'],
+  }),
+})
+```
+
+## Lifecycle Hooks
+
+Hooks execute in the following order:
+
+```
+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
+
+`HonoStreamAppBuilder` validates parameters **before** starting the stream to return proper HTTP error responses. It passes `isPrevalidated: true` internally to skip redundant procedure-level validation. This is transparent to handler authors — the flag is not exposed on the handler context type.
+
+1. Params are validated by `HonoStreamAppBuilder` at the HTTP layer
+2. If validation fails, a 400 response is returned (no stream starts)
+3. If validation passes, the procedure handler runs without duplicate validation
+
+This design allows for:
+- Clean HTTP error responses (400 status code, JSON body) instead of stream errors
+- No duplicate validation overhead
+- Consistent error handling at the framework level
+
+## Error Handling
+
+Streaming has two distinct error phases with different semantics:
+
+| Phase | When | Response Type | Callback |
+|-------|------|---------------|----------|
+| **Pre-stream** | Validation, auth, context resolution | HTTP Response (400/500) | `onPreStreamError` |
+| **Mid-stream** | Generator throws during iteration | Value written to stream | `onMidStreamError` |
+
+### Pre-Stream Errors (`onPreStreamError`)
+
+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({
+  onPreStreamError: (procedure, c, error) => {
+    if (error instanceof ProcedureValidationError) {
+      return c.json({
+        error: 'Invalid parameters',
+        details: error.errors,
+        procedure: procedure.name,
+      }, 400)
+    }
+    return c.json({ error: error.message }, 500)
+  },
+})
+
+// Without handler, returns default JSON response:
+// Status: 400 (validation) or 500 (other)
+// Body: { "error": "Validation error for ProcedureName - ..." }
+```
+
+### Mid-Stream Errors (`onMidStreamError`)
+
+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 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,
+      }, { event: 'error', id: 'err-001' }),
+      // Optional: whether to close stream after (default: true)
+      closeStream: true,
+    }
+  },
+})
+```
+
+**Return values:**
+- `{ 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
+StreamRPC.CreateStream('WatchEvents', {
+  scope: 'events',
+  version: 1,
+  schema: {
+    params: v.object({ roomId: v.string() }),
+    // Union type: clients know exactly what to expect
+    yieldType: v.union([
+      v.object({
+        type: v.literal('event'),
+        eventType: v.string(),
+        data: v.any()
+      }),
+      v.object({
+        type: v.literal('error'),
+        code: v.string(),
+        message: v.string(),
+        retryable: v.boolean()
+      })
+    ])
+  }
+}, async function* (ctx, params) {
+  // 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
+})
+```
+
+**Output (SSE mode):**
+```
+event: WatchEvents
+data: {"type":"event","eventType":"user_joined","data":{"userId":"123"}}
+
+event: WatchEvents
+data: {"type":"error","code":"STREAM_ERROR","message":"Connection lost","retryable":false}
+```
+
+### Default Error Output
+
+Without custom callbacks, errors are written as:
+
+**SSE Mode:**
+```
+event: error
+data: {"error":"Error message"}
+```
+
+**Text Mode:**
+```
+{"error":"Error message"}
+```
+
+## Route Documentation
+
+Access generated documentation via `builder.docs`:
+
+```typescript
+interface StreamHttpRouteDoc {
+  name: string
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: 'sse' | 'text'
+  scope: string | string[]
+  version: number
+  jsonSchema: {
+    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" }
+  }
+}
+```
+
+## Procedure Filtering
+
+Only streaming procedures (created with `CreateStream`) are registered. Regular procedures created with `Create` are ignored by this builder.
+
+```typescript
+const RPC = Procedures<Context, RPCConfig>()
+
+// This will NOT be registered by HonoStreamAppBuilder
+RPC.Create('GetUser', config, async (ctx) => ({ user: 'data' }))
+
+// This WILL be registered
+RPC.CreateStream('WatchUser', config, async function* (ctx) {
+  yield { update: 'data' }
+})
+```
+
+## Client Disconnect Handling
+
+When a client disconnects, the stream's `onAbort` handler is triggered, which calls `generator.return()` to clean up. The `ctx.signal` in your handler will be aborted.
+
+`HonoStreamAppBuilder` injects the HTTP request's `AbortSignal` (`c.req.raw.signal`) into the handler context. This is combined with the stream's internal `AbortController` via `AbortSignal.any()`, so `ctx.signal` aborts on either client disconnect or normal stream completion.
+
+Use `signal.reason` to distinguish between the two:
+
+```typescript
+RPC.CreateStream('LongStream', config, async function* (ctx) {
+  try {
+    while (!ctx.signal.aborted) {
+      yield { tick: Date.now() }
+      await new Promise((r) => setTimeout(r, 1000))
+    }
+  } finally {
+    if (ctx.signal.reason === 'stream-completed') {
+      // Generator finished normally
+    } else {
+      // Client disconnected — clean up resources
+      await releaseResources()
+    }
+  }
+})
+```
+
+## TypeScript Types
+
+```typescript
+import {
+  HonoStreamAppBuilder,
+  HonoStreamAppBuilderConfig, // Generic: HonoStreamAppBuilderConfig<TErrorData = unknown>
+  StreamHttpRouteDoc,
+  StreamMode,
+  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.