ts-procedures 3.2.0 → 3.3.0

package/src/implementations/http/README.md

@@ -1,19 +1,38 @@
-# HTTP-RPC Implementations
+# HTTP Implementations
 
-HTTP-RPC builders for `ts-procedures` that create type-safe, versioned RPC endpoints with automatic path generation, schema-based validation, and route documentation.
+HTTP implementation builders for `ts-procedures` that create type-safe, versioned endpoints with automatic path generation, schema-based validation, and route documentation.
 
 ## Available Implementations
 
+### RPC (Request/Response)
+
+For procedures created with `Create()` - standard request/response pattern using POST.
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| [Express RPC](./express-rpc/README.md) | `express-rpc` | Express.js integration |
+| [Hono RPC](./hono-rpc/README.md) | `hono-rpc` | Hono integration (Bun, Deno, Cloudflare Workers, Node.js) |
+
+### Streaming
+
+For procedures created with `CreateStream()` - server-sent events and streaming responses.
+
 | Framework | Package | Description |
 |-----------|---------|-------------|
-| [Express](./express-rpc/README.md) | `express-rpc` | Express.js integration |
-| [Hono](./hono-rpc/README.md) | `hono-rpc` | Hono integration (Bun, Deno, Cloudflare Workers, Node.js) |
+| [Hono Stream](./hono-stream/README.md) | `hono-stream` | SSE and text streaming for async generators |
+
+## Procedure Types
+
+| Type | Created With | Handler Return | HTTP Methods | Use Case |
+|------|--------------|----------------|--------------|----------|
+| RPC | `Create()` | `Promise<T>` | POST | Standard request/response |
+| Stream | `CreateStream()` | `AsyncGenerator<T>` | GET, POST | Real-time updates, SSE |
 
 ## Core Concepts
 
-### RPCConfig Interface
+### Config Interface
 
-All HTTP-RPC implementations use a shared configuration interface:
+All HTTP implementations use a shared configuration interface:
 
 ```typescript
 interface RPCConfig {
@@ -24,13 +43,13 @@ interface RPCConfig {
 
 ### Path Generation
 
-Routes are generated using kebab-case conversion with the formula:
+Routes are generated using kebab-case conversion:
 
 ```
 /{pathPrefix}/{scope...}/{procedureName}/{version}
 ```
 
-**Conversion Examples:**
+**Examples:**
 
 | Scope | Procedure Name | Version | Generated Path |
 |-------|----------------|---------|----------------|
@@ -46,85 +65,98 @@ Routes are generated using kebab-case conversion with the formula:
 | `'users'` | `'Create'` | `1` | `/api/v1/users/create/1` |
 | `['users', 'admin']` | `'Delete'` | `2` | `/api/v1/users/admin/delete/2` |
 
-### Context Resolution Patterns
+### Context Resolution
 
 The `factoryContext` parameter supports three patterns:
 
 ```typescript
 // 1. Static object
-builder.register(RPC, { userId: 'static-123' })
+builder.register(Factory, { userId: 'static-123' })
 
 // 2. Sync function
-builder.register(RPC, (req) => ({
-  userId: req.headers['x-user-id']
+builder.register(Factory, (c) => ({
+  userId: c.req.header('x-user-id')
 }))
 
 // 3. Async function
-builder.register(RPC, async (req) => {
-  const user = await validateToken(req.headers.authorization)
+builder.register(Factory, async (c) => {
+  const user = await validateToken(c.req.header('authorization'))
   return { userId: user.id }
 })
 ```
 
 ### Lifecycle Hooks
 
-Hooks execute in the following order:
+**RPC Implementations:**
 
 ```
 onRequestStart → handler → onSuccess → onRequestEnd
                     ↓
               (on error)
                     ↓
-            error handler
+              onError handler
                     ↓
-            onRequestEnd
+              onRequestEnd
+```
+
+**Stream Implementations:**
+
+```
+onRequestStart → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
+                      ↓
+                 (on error)
+                      ↓
+               error in stream
+                      ↓
+                onStreamEnd
 ```
 
-| Hook | Trigger | Use Case |
-|------|---------|----------|
-| `onRequestStart` | Before route handler | Logging, request tracking |
-| `onSuccess` | After successful handler execution | Metrics, audit logging |
-| `onRequestEnd` | After response sent | Cleanup, timing metrics |
-| `error` | On handler error | Custom error responses |
+| Hook | Available In | Trigger |
+|------|--------------|---------|
+| `onRequestStart` | Both | Before route handler |
+| `onRequestEnd` | Both | After response sent |
+| `onSuccess` | RPC | After successful handler |
+| `onError` | RPC | On handler error |
+| `onStreamStart` | Stream | Before first yield |
+| `onStreamEnd` | Stream | After stream completes |
+| `onStreamError` | Stream | On stream error |
 
 ### Route Documentation
 
-Each registered procedure generates an `RPCHttpRouteDoc`:
+Each registered procedure generates documentation accessible via `builder.docs`.
+
+**RPC Documentation (`RPCHttpRouteDoc`):**
 
 ```typescript
 interface RPCHttpRouteDoc {
-  path: string           // Generated route path
-  method: 'post'         // Always POST for RPC
+  name: string
+  path: string
+  method: 'post'
+  scope: string | string[]
+  version: number
   jsonSchema: {
-    body?: object        // JSON Schema from schema.params
-    response?: object    // JSON Schema from schema.returnType
+    body?: object      // From schema.params
+    response?: object  // From schema.returnType
   }
 }
 ```
 
-Access documentation via `builder.docs` after calling `build()`:
+**Stream Documentation (`StreamHttpRouteDoc`):**
 
 ```typescript
-const builder = new ExpressRPCAppBuilder()
-builder.register(RPC, () => ({}))
-builder.build()
-
-// Generate OpenAPI documentation
-const openApiPaths = builder.docs.reduce((acc, doc) => {
-  acc[doc.path] = {
-    post: {
-      requestBody: doc.jsonSchema.body ? {
-        content: { 'application/json': { schema: doc.jsonSchema.body } }
-      } : undefined,
-      responses: {
-        200: doc.jsonSchema.response ? {
-          content: { 'application/json': { schema: doc.jsonSchema.response } }
-        } : undefined
-      }
-    }
+interface StreamHttpRouteDoc {
+  name: string
+  path: string
+  methods: ('get' | 'post')[]
+  streamMode: 'sse' | 'text'
+  scope: string | string[]
+  version: number
+  jsonSchema: {
+    params?: object     // From schema.params
+    yieldType?: object  // From schema.yieldType
+    returnType?: object // From schema.returnType
   }
-  return acc
-}, {})
+}
 ```
 
 ### Builder Pattern
@@ -132,9 +164,9 @@ const openApiPaths = builder.docs.reduce((acc, doc) => {
 All implementations follow the same builder pattern:
 
 ```typescript
-const builder = new RPCAppBuilder(config)
-  .register(PublicRPC, publicContextResolver)
-  .register(ProtectedRPC, protectedContextResolver)
+const builder = new AppBuilder(config)
+  .register(PublicFactory, publicContextResolver)
+  .register(ProtectedFactory, protectedContextResolver)
 
 const app = builder.build()
 const docs = builder.docs
@@ -144,16 +176,15 @@ const docs = builder.docs
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `register(factory, context)` | `this` | Register a procedure factory with context resolver |
+| `register(factory, context, options?)` | `this` | Register a procedure factory |
 | `build()` | Framework app | Create routes and return the application |
-| `makeRPCHttpRoutePath(config)` | `string` | Generate path for an RPCConfig |
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `app` | Framework app | The underlying framework application |
-| `docs` | `RPCHttpRouteDoc[]` | Route documentation (populated after `build()`) |
+| `docs` | Route doc array | Route documentation (populated after `build()`) |
 
 ## Framework Comparison
 
@@ -164,9 +195,10 @@ const docs = builder.docs
 | Body access | `req.body` | `await c.req.json()` |
 | Header access | `req.headers['x-id']` | `c.req.header('x-id')` |
 | JSON middleware | Auto-added (or manual) | Built-in |
+| Streaming support | Not yet | `hono-stream` |
 
 ## TypeScript Types
 
 ```typescript
-import { RPCConfig, RPCHttpRouteDoc } from 'ts-procedures/http-rpc'
+import { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/implementations/types'
 ```

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

@@ -0,0 +1,261 @@
+# 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 } from 'ts-procedures/implementations/http/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
+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 { 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
+
+## 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: ProcedureName
+data: {"key":"value"}
+id: 0
+
+event: ProcedureName
+data: {"key":"value2"}
+id: 1
+```
+
+Client usage:
+```typescript
+const eventSource = new EventSource('/user/notifications/watch-notifications/1')
+eventSource.addEventListener('WatchNotifications', (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 {
+  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
+  onStreamError?: (procedure, c, error) => Response | Promise<Response>
+}
+```
+
+### 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 → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
+                      ↓
+                 (on error)
+                      ↓
+              error sent in stream
+                      ↓
+                onStreamEnd
+```
+
+## Error Handling
+
+Errors during streaming are sent as special messages:
+
+**SSE Mode:**
+```
+event: error
+data: {"error":"Error message"}
+```
+
+**Text Mode:**
+```
+{"error":"Error message"}
+```
+
+For errors before streaming starts (e.g., context resolution), use `onStreamError`:
+
+```typescript
+const builder = new HonoStreamAppBuilder({
+  onStreamError: (procedure, c, error) => {
+    return c.json({ error: error.message }, 500)
+  },
+})
+```
+
+## 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?: object     // From schema.params
+    yieldType?: object  // From schema.yieldType
+    returnType?: object // From schema.returnType
+  }
+}
+```
+
+## 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:
+
+```typescript
+RPC.CreateStream('LongStream', config, async function* (ctx) {
+  while (!ctx.signal.aborted) {
+    yield { tick: Date.now() }
+    await new Promise((r) => setTimeout(r, 1000))
+  }
+})
+```
+
+## TypeScript Types
+
+```typescript
+import {
+  HonoStreamAppBuilder,
+  HonoStreamAppBuilderConfig,
+  StreamHttpRouteDoc,
+  StreamMode,
+} from 'ts-procedures/implementations/http/hono-stream'
+```