ts-procedures 3.2.0 → 3.3.1

package/README.md

@@ -71,6 +71,34 @@ Create(name, config, handler)
 - `procedure` - Generic reference to the handler
 - `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
 
+### CreateStream Function
+
+The `CreateStream` function defines streaming procedures that yield values over time using async generators:
+
+```typescript
+CreateStream(name, config, handler)
+```
+
+**Config Options:**
+- `schema.params` - Input parameter schema (validated at runtime)
+- `schema.yieldType` - Schema for each yielded value (validated if `validateYields: true`)
+- `schema.returnType` - Schema for final return value (documentation only)
+- `validateYields` - Enable runtime validation of yielded values (default: `false`)
+
+**Handler Signature:**
+```typescript
+async function* (ctx, params) => AsyncGenerator<TYield, TReturn | void>
+```
+
+**Context Extensions:**
+- `ctx.error(message, meta?)` - Create a ProcedureError
+- `ctx.signal` - AbortSignal for cancellation support
+
+**Returns:**
+- `{ [name]: handler }` - Named generator export
+- `procedure` - Generic reference to the generator
+- `info` - Procedure meta with `isStream: true`
+
 ## Using Generics
 
 ### Base Context
@@ -237,6 +265,193 @@ AJV is configured with:
 
 **Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
 
+## Streaming Procedures
+
+Streaming procedures use async generators to yield values over time, enabling SSE (Server-Sent Events), HTTP streaming, and real-time data feeds.
+
+### 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
+
+The `ctx.signal` allows handlers to detect when consumers stop iterating:
+
+```typescript
+const { CancellableStream } = CreateStream(
+  'CancellableStream',
+  {},
+  async function* (ctx) {
+    try {
+      while (!ctx.signal.aborted) {
+        yield await fetchNextItem()
+      }
+    } finally {
+      // Cleanup when stream ends (consumer stopped or completed)
+      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
+```
+
+### Stream Errors
+
+Streaming procedures support the same error handling as regular procedures:
+
+```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' }
+  }
+}
+```
+
 ## Error Handling
 
 ### Using ctx.error()
@@ -262,7 +477,8 @@ Create(
 | Error Class | Trigger |
 |-------------|---------|
 | ProcedureError | `ctx.error()` in handlers |
-| ProcedureValidationError | Schema validation failure |
+| ProcedureValidationError | Schema validation failure (params) |
+| ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
 | ProcedureRegistrationError | Invalid schema at registration |
 
 ### Error Properties
@@ -470,10 +686,13 @@ import {
   ProcedureError,
   ProcedureValidationError,
   ProcedureRegistrationError,
-  
+  ProcedureYieldValidationError,  // For streaming yield validation
+
   // Types
   TLocalContext,
+  TStreamContext,               // Streaming context with AbortSignal
   TProcedureRegistration,
+  TStreamProcedureRegistration, // Streaming procedure registration
   TNoContextProvided,
 
   // Schema utilities
@@ -485,6 +704,7 @@ import {
   // Schema types
   TJSONSchema,
   TSchemaLib,
+  TSchemaLibGenerator,          // AsyncGenerator type utility
   TSchemaParsed,
   TSchemaValidationError,
   Prettify,

package/build/errors.d.ts

@@ -26,3 +26,8 @@ export declare class ProcedureRegistrationError extends ProcedureError {
     readonly procedureName: string;
     constructor(procedureName: string, message: string, definitionInfo?: DefinitionInfo);
 }
+export declare class ProcedureYieldValidationError extends ProcedureError {
+    readonly procedureName: string;
+    readonly errors?: TSchemaValidationError[] | undefined;
+    constructor(procedureName: string, message: string, errors?: TSchemaValidationError[] | undefined, definitionInfo?: DefinitionInfo);
+}

package/build/errors.js

@@ -70,4 +70,18 @@ export class ProcedureRegistrationError extends ProcedureError {
         Object.setPrototypeOf(this, ProcedureRegistrationError.prototype);
     }
 }
+export class ProcedureYieldValidationError extends ProcedureError {
+    procedureName;
+    errors;
+    constructor(procedureName, message, errors, 
+    // Used for error stack trace details
+    definitionInfo) {
+        super(procedureName, message, undefined, definitionInfo);
+        this.procedureName = procedureName;
+        this.errors = errors;
+        this.name = 'ProcedureYieldValidationError';
+        // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+        Object.setPrototypeOf(this, ProcedureYieldValidationError.prototype);
+    }
+}
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAsC,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAE3F,MAAM,OAAO,cAAe,SAAQ,KAAK;IAM5B;IACA;IACA;IAPX,KAAK,CAAU;IACN,SAAS,CAAqB;IAC9B,eAAe,CAAS;IAEjC,YACW,aAAqB,EACrB,OAAe,EACf,IAAa;IACtB,qCAAqC;IACrC,cAA+B;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAA;QANL,kBAAa,GAAb,aAAa,CAAQ;QACrB,YAAO,GAAP,OAAO,CAAQ;QACf,SAAI,GAAJ,IAAI,CAAS;QAKtB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAE5B,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,CAAC,SAAS,GAAG,cAAc,CAAC,SAAS,CAAA;YACzC,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC,eAAe,CAAA;YACrD,IAAI,CAAC,YAAY,EAAE,CAAA;QACrB,CAAC;QAED,mGAAmG;QACnG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;IACvD,CAAC;IAED;;OAEG;IACH,qBAAqB;QACnB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAA;IACjF,CAAC;IAED;;OAEG;IACK,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,OAAM;QACR,CAAC;QAED,MAAM,iBAAiB,GAAG,oBAAoB,CAC5C,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,EACpE,IAAI,CAAC,aAAa,CACnB,CAAA;QAED,IAAI,iBAAiB,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,iBAAiB,CAAA;QAC7C,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAE/C;IAEA;IAHX,YACW,aAAqB,EAC9B,OAAe,EACN,MAAiC;IAC1C,qCAAqC;IACrC,cAA+B;QAE/B,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAA;QAN/C,kBAAa,GAAb,aAAa,CAAQ;QAErB,WAAM,GAAN,MAAM,CAA2B;QAK1C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;QAEtC,mGAAmG;QACnG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAA;IACjE,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAEjD;IADX,YACW,aAAqB,EAC9B,OAAe;IACf,qCAAqC;IACrC,cAA+B;QAE/B,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,CAAA;QAL/C,kBAAa,GAAb,aAAa,CAAQ;QAM9B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;QAExC,mGAAmG;QACnG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAA;IACnE,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/hono-stream/index.d.ts

@@ -0,0 +1,92 @@
+import { Hono, Context } from 'hono';
+import { TStreamProcedureRegistration } from '../../../index.js';
+import { ExtractConfig, ExtractContext, ProceduresFactory, RPCConfig } from '../../types.js';
+import { StreamHttpRouteDoc, StreamMode } from './types.js';
+export type { StreamHttpRouteDoc, StreamMode };
+export type HonoStreamAppBuilderConfig = {
+    /**
+     * An existing Hono application instance to use.
+     * If not provided, a new instance will be created.
+     */
+    app?: Hono;
+    /** Optional path prefix for all stream routes. */
+    pathPrefix?: string;
+    /** Default stream mode for all routes. Defaults to 'sse'. */
+    defaultStreamMode?: StreamMode;
+    onRequestStart?: (c: Context) => void;
+    onRequestEnd?: (c: Context) => void;
+    onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context) => void;
+    onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context) => void;
+    /**
+     * Error handler called when a streaming procedure throws an error.
+     */
+    onStreamError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>;
+};
+/**
+ * Builder class for creating a Hono application with streaming RPC routes.
+ *
+ * Usage:
+ *   const StreamRPC = Procedures<StreamContext, RPCConfig>()
+ *
+ *   const streamApp = new HonoStreamAppBuilder()
+ *     .register(StreamRPC, (c): Promise<StreamContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = streamApp.app; // Hono application
+ *   const docs = streamApp.docs; // Stream route documentation
+ */
+export declare class HonoStreamAppBuilder {
+    readonly config?: HonoStreamAppBuilderConfig | undefined;
+    /**
+     * Constructor for HonoStreamAppBuilder.
+     */
+    constructor(config?: HonoStreamAppBuilderConfig | undefined);
+    /**
+     * Generates the stream route path based on the RPC configuration.
+     */
+    static makeStreamHttpRoutePath({ name, config, prefix, }: {
+        name: string;
+        prefix?: string;
+        config: RPCConfig;
+    }): string;
+    /**
+     * Instance method wrapper for makeStreamHttpRoutePath that uses the builder's pathPrefix.
+     */
+    makeStreamHttpRoutePath(name: string, config: RPCConfig): string;
+    private factories;
+    private _app;
+    private _docs;
+    get app(): Hono;
+    get docs(): StreamHttpRouteDoc[];
+    /**
+     * Registers a procedure factory with its context.
+     * Only streaming procedures (created with CreateStream) will be registered.
+     */
+    register<TFactory extends ProceduresFactory>(factory: TFactory, factoryContext: ExtractContext<TFactory> | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>), options?: {
+        streamMode?: StreamMode;
+        extendProcedureDoc?: (params: {
+            base: StreamHttpRouteDoc;
+            procedure: TStreamProcedureRegistration<any, ExtractConfig<TFactory>>;
+        }) => Record<string, any>;
+    }): this;
+    /**
+     * Creates a route handler for streaming procedures.
+     */
+    private createStreamHandler;
+    /**
+     * Handles SSE streaming mode.
+     */
+    private handleSSEStream;
+    /**
+     * Handles text streaming mode.
+     */
+    private handleTextStream;
+    /**
+     * Builds and returns the Hono application with registered streaming routes.
+     */
+    build(): Hono;
+    /**
+     * Generates the Stream HTTP route documentation for the given procedure.
+     */
+    private buildStreamHttpRouteDoc;
+}

package/build/implementations/http/hono-stream/index.js

@@ -0,0 +1,229 @@
+import { Hono } from 'hono';
+import { streamSSE, streamText } from 'hono/streaming';
+import { kebabCase } from 'es-toolkit/string';
+import { castArray } from 'es-toolkit/compat';
+/**
+ * Builder class for creating a Hono application with streaming RPC routes.
+ *
+ * Usage:
+ *   const StreamRPC = Procedures<StreamContext, RPCConfig>()
+ *
+ *   const streamApp = new HonoStreamAppBuilder()
+ *     .register(StreamRPC, (c): Promise<StreamContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = streamApp.app; // Hono application
+ *   const docs = streamApp.docs; // Stream route documentation
+ */
+export class HonoStreamAppBuilder {
+    config;
+    /**
+     * Constructor for HonoStreamAppBuilder.
+     */
+    constructor(config) {
+        this.config = config;
+        if (config?.app) {
+            this._app = config.app;
+        }
+        if (config?.onRequestStart) {
+            this._app.use('*', async (c, next) => {
+                config.onRequestStart(c);
+                await next();
+            });
+        }
+        if (config?.onRequestEnd) {
+            this._app.use('*', async (c, next) => {
+                await next();
+                config.onRequestEnd(c);
+            });
+        }
+    }
+    /**
+     * Generates the stream route path based on the RPC configuration.
+     */
+    static makeStreamHttpRoutePath({ name, config, prefix, }) {
+        const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : '';
+        return `${normalizedPrefix}/${castArray(config.scope).map(kebabCase).join('/')}/${kebabCase(name)}/${String(config.version).trim()}`;
+    }
+    /**
+     * Instance method wrapper for makeStreamHttpRoutePath that uses the builder's pathPrefix.
+     */
+    makeStreamHttpRoutePath(name, config) {
+        return HonoStreamAppBuilder.makeStreamHttpRoutePath({
+            name,
+            config,
+            prefix: this.config?.pathPrefix,
+        });
+    }
+    factories = [];
+    _app = new Hono();
+    _docs = [];
+    get app() {
+        return this._app;
+    }
+    get docs() {
+        return this._docs;
+    }
+    /**
+     * Registers a procedure factory with its context.
+     * Only streaming procedures (created with CreateStream) will be registered.
+     */
+    register(factory, factoryContext, options) {
+        this.factories.push({
+            factory,
+            factoryContext,
+            streamMode: options?.streamMode,
+            extendProcedureDoc: options?.extendProcedureDoc,
+        });
+        return this;
+    }
+    /**
+     * Creates a route handler for streaming procedures.
+     */
+    createStreamHandler(procedure, factoryContext, streamMode) {
+        return async (c) => {
+            try {
+                const context = typeof factoryContext === 'function'
+                    ? await factoryContext(c)
+                    : factoryContext;
+                // GET: query params, POST: JSON body
+                const params = c.req.method === 'GET'
+                    ? Object.fromEntries(new URL(c.req.url).searchParams)
+                    : await c.req.json().catch(() => ({}));
+                if (this.config?.onStreamStart) {
+                    this.config.onStreamStart(procedure, c);
+                }
+                if (streamMode === 'sse') {
+                    return this.handleSSEStream(procedure, context, params, c);
+                }
+                else {
+                    return this.handleTextStream(procedure, context, params, c);
+                }
+            }
+            catch (error) {
+                if (this.config?.onStreamError) {
+                    return this.config.onStreamError(procedure, c, error);
+                }
+                return c.json({ error: error.message }, 500);
+            }
+        };
+    }
+    /**
+     * Handles SSE streaming mode.
+     */
+    handleSSEStream(procedure, context, params, c) {
+        return streamSSE(c, async (stream) => {
+            const generator = procedure.handler(context, params);
+            stream.onAbort(async () => {
+                await generator.return(undefined);
+            });
+            try {
+                let eventId = 0;
+                for await (const value of generator) {
+                    await stream.writeSSE({
+                        data: JSON.stringify(value),
+                        event: procedure.name,
+                        id: String(eventId++),
+                    });
+                }
+            }
+            catch (error) {
+                // Write error as SSE event before closing
+                await stream.writeSSE({
+                    data: JSON.stringify({ error: error.message }),
+                    event: 'error',
+                });
+            }
+            finally {
+                if (this.config?.onStreamEnd) {
+                    this.config.onStreamEnd(procedure, c);
+                }
+            }
+        });
+    }
+    /**
+     * Handles text streaming mode.
+     */
+    handleTextStream(procedure, context, params, c) {
+        return streamText(c, async (stream) => {
+            const generator = procedure.handler(context, params);
+            stream.onAbort(async () => {
+                await generator.return(undefined);
+            });
+            try {
+                for await (const value of generator) {
+                    await stream.writeln(JSON.stringify(value));
+                }
+            }
+            catch (error) {
+                // Write error as JSON line before closing
+                await stream.writeln(JSON.stringify({ error: error.message }));
+            }
+            finally {
+                if (this.config?.onStreamEnd) {
+                    this.config.onStreamEnd(procedure, c);
+                }
+            }
+        });
+    }
+    /**
+     * Builds and returns the Hono application with registered streaming routes.
+     */
+    build() {
+        this.factories.forEach(({ factory, factoryContext, streamMode, extendProcedureDoc }) => {
+            const mode = streamMode ?? this.config?.defaultStreamMode ?? 'sse';
+            factory
+                .getProcedures()
+                .filter((p) => p.isStream === true)
+                .forEach((procedure) => {
+                const route = this.buildStreamHttpRouteDoc(procedure, mode, extendProcedureDoc);
+                this._docs.push(route);
+                const handler = this.createStreamHandler(procedure, factoryContext, mode);
+                // Register both GET and POST handlers
+                this._app.get(route.path, handler);
+                this._app.post(route.path, handler);
+            });
+        });
+        return this._app;
+    }
+    /**
+     * Generates the Stream HTTP route documentation for the given procedure.
+     */
+    buildStreamHttpRouteDoc(procedure, streamMode, extendProcedureDoc) {
+        const { config } = procedure;
+        const path = HonoStreamAppBuilder.makeStreamHttpRoutePath({
+            name: procedure.name,
+            config,
+            prefix: this.config?.pathPrefix,
+        });
+        const methods = ['get', 'post'];
+        const jsonSchema = {};
+        if (config.schema?.params) {
+            jsonSchema.params = config.schema.params;
+        }
+        if (config.schema?.yieldType) {
+            jsonSchema.yieldType = config.schema.yieldType;
+        }
+        if (config.schema?.returnType) {
+            jsonSchema.returnType = config.schema.returnType;
+        }
+        const base = {
+            name: procedure.name,
+            version: config.version,
+            scope: config.scope,
+            path,
+            methods: [...methods],
+            streamMode,
+            jsonSchema,
+        };
+        let extendedDoc = {};
+        if (extendProcedureDoc) {
+            extendedDoc = extendProcedureDoc({ base, procedure });
+        }
+        return {
+            ...extendedDoc,
+            ...base,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/build/implementations/http/hono-stream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/implementations/http/hono-stream/index.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/hono-stream/index.test.d.ts

@@ -0,0 +1 @@
+export {};