ts-procedures 5.4.0 → 5.5.0

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

@@ -1,526 +0,0 @@
-# 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. To avoid redundant validation, it passes `isPrevalidated: true` in the context when calling procedure handlers. This means:
-
-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 is called with `isPrevalidated: true`
-4. The procedure's internal validation is skipped, avoiding duplicate work
-
-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.