ts-procedures 5.7.2 → 5.9.0

package/docs/streaming.md

@@ -0,0 +1,199 @@
+[Home](../README.md) | [Core](./core.md) | **Streaming** | [HTTP Integrations](./http-integrations.md) | [Client & Codegen](./client-and-codegen.md) | [AI Agent Setup](./ai-agent-setup.md)
+
+# Streaming Procedures
+
+Streaming procedures use async generators to yield values over time, enabling SSE (Server-Sent Events), HTTP streaming, and real-time data feeds.
+
+For the `CreateStream` function signature and config options, see [Core Procedures](./core.md#createstream-function).
+
+## Basic Streaming
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { v } from 'suretype'
+
+const { CreateStream } = Procedures<{ userId: string }>()
+
+const { StreamUpdates } = CreateStream(
+  'StreamUpdates',
+  {
+    description: 'Stream real-time updates',
+    schema: {
+      params: v.object({ topic: v.string().required() }),
+      yieldType: v.object({
+        id: v.string().required(),
+        message: v.string().required(),
+        timestamp: v.number().required(),
+      }),
+    },
+  },
+  async function* (ctx, params) {
+    // Types are inferred from schema:
+    // - params.topic: string
+    // - yield value must match { id, message, timestamp }
+    // - ctx.signal: AbortSignal for cancellation
+
+    let counter = 0
+    while (!ctx.signal.aborted) {
+      yield {
+        id: `${counter++}`,
+        message: `Update for ${params.topic}`,
+        timestamp: Date.now(),
+      }
+      await new Promise(r => setTimeout(r, 1000))
+    }
+  },
+)
+
+// Consume the stream
+for await (const update of StreamUpdates({ userId: 'user-123' }, { topic: 'news' })) {
+  console.log(update.message)
+}
+```
+
+## Yield Validation
+
+By default, yielded values are not validated for performance. Enable validation with `validateYields: true`:
+
+```typescript
+const { ValidatedStream } = CreateStream(
+  'ValidatedStream',
+  {
+    schema: {
+      yieldType: v.object({ count: v.number().required() }),
+    },
+    validateYields: true, // Enable runtime validation of each yield
+  },
+  async function* () {
+    yield { count: 1 }  // Valid
+    yield { count: 2 }  // Valid
+    // yield { count: 'invalid' } // Would throw ProcedureYieldValidationError
+  },
+)
+```
+
+## Abort Signal Integration
+
+For abort signal behavior in regular (non-streaming) procedures, see [Core Procedures — Abort Signal](./core.md#abort-signal).
+
+The `ctx.signal` allows stream handlers to detect when consumers stop iterating. After completion, `signal.reason` indicates why the stream ended:
+
+```typescript
+const { CancellableStream } = CreateStream(
+  'CancellableStream',
+  {},
+  async function* (ctx) {
+    try {
+      while (!ctx.signal.aborted) {
+        yield await fetchNextItem()
+      }
+    } finally {
+      // Distinguish normal completion from client disconnect
+      if (ctx.signal.reason === 'stream-completed') {
+        // Stream finished normally
+      } else {
+        // Client disconnected or external abort
+      }
+      await cleanup()
+    }
+  },
+)
+
+// Consumer can break early - signal.aborted becomes true
+for await (const item of CancellableStream({}, {})) {
+  if (shouldStop) break // Triggers abort
+}
+```
+
+## SSE Integration Example
+
+```typescript
+import express from 'express'
+import { Procedures } from 'ts-procedures'
+
+const app = express()
+
+const { CreateStream, getProcedures } = Procedures<{ req: express.Request }>({
+  onCreate: (proc) => {
+    if (proc.isStream) {
+      // Register streaming procedures as SSE endpoints
+      app.get(`/stream/${proc.name}`, async (req, res) => {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection': 'keep-alive',
+        })
+
+        const generator = proc.handler({ req }, req.query)
+
+        req.on('close', async () => {
+          // Client disconnected - stop the generator
+          await generator.return(undefined)
+        })
+
+        try {
+          for await (const data of generator) {
+            res.write(`data: ${JSON.stringify(data)}\n\n`)
+          }
+        } finally {
+          res.end()
+        }
+      })
+    }
+  },
+})
+
+// Define a streaming procedure
+CreateStream(
+  'LiveFeed',
+  {
+    schema: {
+      params: v.object({ channel: v.string() }),
+      yieldType: v.object({ event: v.string(), data: v.any() }),
+    },
+  },
+  async function* (ctx, params) {
+    while (!ctx.signal.aborted) {
+      const event = await pollForEvent(params.channel)
+      yield event
+    }
+  },
+)
+
+app.listen(3000)
+// SSE endpoint: GET /stream/LiveFeed?channel=updates
+```
+
+For the built-in Hono streaming integration, see the [Hono Stream README](../src/implementations/http/hono-stream/README.md).
+
+## Stream Errors
+
+Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)):
+
+```typescript
+const { StreamWithErrors } = CreateStream(
+  'StreamWithErrors',
+  {},
+  async function* (ctx) {
+    yield { status: 'starting' }
+
+    const data = await fetchData()
+    if (!data) {
+      throw ctx.error('No data available', { code: 'NO_DATA' })
+    }
+
+    yield { status: 'complete', data }
+  },
+)
+
+try {
+  for await (const item of StreamWithErrors({}, {})) {
+    console.log(item)
+  }
+} catch (e) {
+  if (e instanceof ProcedureError) {
+    console.log(e.message) // 'No data available'
+    console.log(e.meta)    // { code: 'NO_DATA' }
+  }
+}
+```