ts-procedures 3.1.0 → 3.3.0

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 {};