ts-procedures 7.3.0 → 8.0.0

package/build/implementations/http/hono/handlers/stream.js

@@ -0,0 +1,147 @@
+import { streamSSE, streamText } from 'hono/streaming';
+import { ProcedureValidationError } from '../../../../errors.js';
+import { dispatchMidStreamError, dispatchPreStreamError } from '../../error-dispatch.js';
+import { buildStreamRouteDoc } from '../docs/stream-doc.js';
+const sseMetadata = new WeakMap();
+/**
+ * Marks an object yield as an SSE event with custom metadata. Stream handlers
+ * read this metadata to set the SSE `event:`, `id:`, and `retry:` fields.
+ */
+export function sse(data, options) {
+    sseMetadata.set(data, options ?? {});
+    return data;
+}
+function getSSEMeta(value) {
+    if (typeof value === 'object' && value !== null) {
+        return sseMetadata.get(value);
+    }
+    return undefined;
+}
+export function installRpcStreamRoute(params) {
+    const { app, procedure, factoryItem, cfg, docs, streamMode } = params;
+    const route = buildStreamRouteDoc(procedure, streamMode, cfg.pathPrefix, factoryItem.extendProcedureDoc);
+    docs.push(route);
+    const handler = async (c) => {
+        try {
+            const context = typeof factoryItem.factoryContext === 'function'
+                ? await factoryItem.factoryContext(c)
+                : factoryItem.factoryContext;
+            const reqParams = c.req.method === 'GET'
+                ? Object.fromEntries(new URL(c.req.url).searchParams)
+                : await c.req.json().catch(() => ({}));
+            // Pre-stream validation — throw so the catch routes through dispatchPreStreamError.
+            if (procedure.config.validation?.params) {
+                const { errors } = procedure.config.validation.params(reqParams);
+                if (errors) {
+                    throw new ProcedureValidationError(procedure.name, `Validation error for ${procedure.name}`, errors);
+                }
+            }
+            cfg.stream?.onStreamStart?.(procedure, c, streamMode);
+            return streamMode === 'sse'
+                ? handleSSE(procedure, context, reqParams, c, cfg)
+                : handleText(procedure, context, reqParams, c, cfg);
+        }
+        catch (error) {
+            return dispatchPreStreamError({
+                err: error,
+                procedure,
+                raw: c,
+                cfg: {
+                    errors: cfg.errors,
+                    unknownError: cfg.unknownError,
+                    onError: cfg.onError,
+                    onRequestError: cfg.onRequestError,
+                },
+            });
+        }
+    };
+    app.get(route.path, handler);
+    app.post(route.path, handler);
+}
+function handleSSE(procedure, context, reqParams, c, cfg) {
+    return streamSSE(c, async (stream) => {
+        const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, reqParams);
+        stream.onAbort(async () => { await generator.return(undefined); });
+        let eventId = 0;
+        try {
+            const iterator = generator[Symbol.asyncIterator]();
+            let it = await iterator.next();
+            while (!it.done) {
+                const value = it.value;
+                const meta = getSSEMeta(value);
+                const data = typeof value === 'string' ? value
+                    : value != null ? JSON.stringify(value)
+                        : '';
+                await stream.writeSSE({
+                    data,
+                    event: meta?.event ?? procedure.name,
+                    id: meta?.id ?? String(eventId++),
+                    ...(meta?.retry !== undefined && { retry: meta.retry }),
+                });
+                it = await iterator.next();
+            }
+            if (it.value !== undefined) {
+                const data = typeof it.value === 'string' ? it.value : JSON.stringify(it.value);
+                await stream.writeSSE({ data, event: 'return', id: String(eventId++) });
+            }
+        }
+        catch (error) {
+            const dispatched = await dispatchMidStreamError({
+                err: error,
+                procedure,
+                raw: c,
+                cfg: {
+                    errors: cfg.errors,
+                    unknownError: cfg.unknownError,
+                    onMidStreamError: cfg.stream?.onMidStreamError,
+                    onRequestError: cfg.onRequestError,
+                },
+            });
+            const meta = getSSEMeta(dispatched.data);
+            await stream.writeSSE({
+                data: typeof dispatched.data === 'string' ? dispatched.data : JSON.stringify(dispatched.data),
+                event: meta?.event ?? dispatched.sseEvent ?? 'error',
+                id: meta?.id ?? String(eventId++),
+                ...(meta?.retry !== undefined && { retry: meta.retry }),
+            });
+            if (dispatched.runOnCatch)
+                await dispatched.runOnCatch();
+        }
+        finally {
+            cfg.stream?.onStreamEnd?.(procedure, c, 'sse');
+            cfg.onRequestEnd?.(c);
+        }
+    });
+}
+function handleText(procedure, context, reqParams, c, cfg) {
+    return streamText(c, async (stream) => {
+        const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, reqParams);
+        stream.onAbort(async () => { await generator.return(undefined); });
+        try {
+            for await (const value of generator) {
+                await stream.writeln(JSON.stringify(value));
+            }
+        }
+        catch (error) {
+            const dispatched = await dispatchMidStreamError({
+                err: error,
+                procedure,
+                raw: c,
+                cfg: {
+                    errors: cfg.errors,
+                    unknownError: cfg.unknownError,
+                    onMidStreamError: cfg.stream?.onMidStreamError,
+                    onRequestError: cfg.onRequestError,
+                },
+            });
+            await stream.writeln(JSON.stringify(dispatched.data));
+            if (dispatched.runOnCatch)
+                await dispatched.runOnCatch();
+        }
+        finally {
+            cfg.stream?.onStreamEnd?.(procedure, c, 'text');
+            cfg.onRequestEnd?.(c);
+        }
+    });
+}
+//# sourceMappingURL=stream.js.map

package/build/implementations/http/hono/handlers/stream.js.map

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

package/build/implementations/http/hono/handlers/stream.test.d.ts

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

package/build/implementations/http/hono/handlers/stream.test.js

@@ -0,0 +1,177 @@
+import { describe, expect, test, vi } from 'vitest';
+import { Hono } from 'hono';
+import { Type } from 'typebox';
+import { Procedures } from '../../../../index.js';
+import { installRpcStreamRoute, sse } from './stream.js';
+function buildApp(setup, cfg = {}) {
+    const P = Procedures();
+    setup(P);
+    const app = new Hono();
+    const docs = [];
+    for (const proc of P.getProcedures().values()) {
+        if (proc.kind !== 'rpc-stream')
+            continue;
+        installRpcStreamRoute({
+            app,
+            procedure: proc,
+            factoryItem: { factory: P, factoryContext: () => ({ uid: 'u1' }) },
+            cfg,
+            docs,
+            streamMode: cfg.stream?.defaultStreamMode ?? 'sse',
+        });
+    }
+    return { app, docs };
+}
+describe('installRpcStreamRoute', () => {
+    test('SSE: yields are written as data events; final return as event:return', async () => {
+        const { app, docs } = buildApp((P) => {
+            P.CreateStream('Counts', { scope: 'c', version: 1 }, async function* () {
+                yield 1;
+                yield 2;
+                return 'done';
+            });
+        });
+        expect(docs[0].kind).toBe('stream');
+        expect(docs[0].path).toBe('/c/counts/1');
+        const res = await app.request('/c/counts/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } });
+        expect(res.status).toBe(200);
+        const text = await res.text();
+        expect(text).toContain('data: 1');
+        expect(text).toContain('data: 2');
+        expect(text).toContain('event: return');
+        expect(text).toContain('data: done');
+    });
+    test('mid-stream throw → dispatchMidStreamError default { error }', async () => {
+        const { app } = buildApp((P) => {
+            P.CreateStream('Boom', { scope: 'b', version: 1 }, async function* () {
+                yield 'first';
+                throw new Error('mid-boom');
+            });
+        });
+        const res = await app.request('/b/boom/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } });
+        const text = await res.text();
+        expect(text).toContain('event: error');
+        expect(text).toContain('"error":"mid-boom"');
+    });
+    test('pre-stream validation error → 400 via dispatchPreStreamError', async () => {
+        const { app } = buildApp((P) => {
+            P.CreateStream('NeedsParams', {
+                scope: 'n', version: 1,
+                schema: { params: Type.Object({ id: Type.String() }) },
+            }, async function* () { yield 'ok'; });
+        });
+        const res = await app.request('/n/needs-params/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } });
+        expect(res.status).toBe(400);
+        const body = await res.json();
+        expect(body.name).toBe('ProcedureValidationError');
+    });
+    test('onStreamStart and onStreamEnd fire', async () => {
+        const onStreamStart = vi.fn();
+        const onStreamEnd = vi.fn();
+        const { app } = buildApp((P) => {
+            P.CreateStream('Ev', { scope: 'e', version: 1 }, async function* () { yield 'x'; });
+        }, { stream: { onStreamStart, onStreamEnd } });
+        const res = await app.request('/e/ev/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } });
+        // Consume the stream body so the SSE writer's finally block runs
+        await res.text();
+        expect(onStreamStart).toHaveBeenCalled();
+        expect(onStreamEnd).toHaveBeenCalled();
+    });
+    test('validateYields: true → invalid yield surfaces ProcedureYieldValidationError on the wire', async () => {
+        const { app } = buildApp((P) => {
+            P.CreateStream('BadYield', {
+                scope: 'y', version: 1,
+                schema: { yieldType: Type.Object({ id: Type.Number() }) },
+                validateYields: true,
+            }, async function* () {
+                yield { id: 1 }; // valid
+                yield { id: 'not-a-number' }; // invalid → throws ProcedureYieldValidationError
+            });
+        });
+        const res = await app.request('/y/bad-yield/1', {
+            method: 'POST',
+            body: '{}',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        // Stream is already open by the time validation fails on the second yield;
+        // status is committed at 200 and the error shows up as an SSE error event.
+        expect(res.status).toBe(200);
+        const text = await res.text();
+        expect(text).toContain('event: error');
+        expect(text).toContain('"name":"ProcedureYieldValidationError"');
+        expect(text).toContain('"procedureName":"BadYield"');
+        // First valid yield still made it onto the wire.
+        expect(text).toContain('data: {"id":1}');
+    });
+    test('sse() helper propagates event/id/retry into SSE wire output', async () => {
+        const { app } = buildApp((P) => {
+            P.CreateStream('Tagged', { scope: 'tagged', version: 1 }, async function* () {
+                yield sse({ count: 1 }, { event: 'tick', id: 'evt-1', retry: 5000 });
+            });
+        });
+        const res = await app.request('/tagged/tagged/1', {
+            method: 'POST',
+            body: '{}',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const text = await res.text();
+        expect(text).toContain('event: tick');
+        expect(text).toContain('id: evt-1');
+        expect(text).toContain('retry: 5000');
+        expect(text).toContain('data: {"count":1}');
+    });
+    test('AbortSignal: natural completion → ctx.signal.reason === "stream-completed"', async () => {
+        let capturedSignal;
+        const { app } = buildApp((P) => {
+            P.CreateStream('Natural', { scope: 'sig', version: 1 }, async function* (ctx) {
+                capturedSignal = ctx.signal;
+                yield 'a';
+                yield 'b';
+                return 'done';
+            });
+        });
+        const res = await app.request('/sig/natural/1', {
+            method: 'POST',
+            body: '{}',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        // Drain the body so the wrappedHandler's finally block runs.
+        await res.text();
+        expect(capturedSignal).toBeInstanceOf(AbortSignal);
+        expect(capturedSignal.aborted).toBe(true);
+        expect(capturedSignal.reason).toBe('stream-completed');
+    });
+    test('AbortSignal: client disconnect (request signal aborted) → ctx.signal.reason !== "stream-completed"', async () => {
+        // NOTE: We can't directly simulate a real socket disconnect through
+        // `app.request()`. The closest test-friendly proxy: pre-abort the request
+        // signal so `c.req.raw.signal` is already aborted by the time the
+        // wrappedHandler in create-stream.ts builds the combined signal via
+        // `AbortSignal.any([incomingSignal, internalController.signal])`. The
+        // pre-existing reason wins over the internal 'stream-completed' that fires
+        // later in the wrappedHandler's finally clause.
+        let capturedSignal;
+        const { app } = buildApp((P) => {
+            P.CreateStream('Disconnect', { scope: 'sig', version: 1 }, async function* (ctx) {
+                capturedSignal = ctx.signal;
+                yield 'first';
+            });
+        });
+        const ac = new AbortController();
+        ac.abort('client-gone');
+        const req = new Request('http://localhost/sig/disconnect/1', {
+            method: 'POST',
+            body: '{}',
+            headers: { 'Content-Type': 'application/json' },
+            signal: ac.signal,
+        });
+        const res = await app.request(req);
+        // Drain the body in case anything was emitted before the abort propagated.
+        await res.text().catch(() => '');
+        expect(capturedSignal).toBeInstanceOf(AbortSignal);
+        expect(capturedSignal.aborted).toBe(true);
+        // The disconnect reason wins over the internal 'stream-completed' signal,
+        // so handlers can distinguish "client gave up" from "we finished normally".
+        expect(capturedSignal.reason).not.toBe('stream-completed');
+    });
+});
+//# sourceMappingURL=stream.test.js.map

package/build/implementations/http/hono/handlers/stream.test.js.map

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

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

@@ -0,0 +1,57 @@
+import { Context, Hono } from 'hono';
+import type { AnyHttpRouteDoc, ProceduresFactory, ExtractContext, StreamMode, DocEnvelope, ErrorDoc, HeaderDoc } from '../../types.js';
+import type { ErrorTaxonomy } from '../error-taxonomy.js';
+import { makeRoutePath as _makeRoutePath } from './path.js';
+import type { HonoAppBuilderConfig, ExtendProcedureDoc } from './types.js';
+export type { HonoAppBuilderConfig, OnRequestErrorContext, ExtendProcedureDoc } from './types.js';
+export type { AnyProcedureRegistration } from './types.js';
+export { sse } from './handlers/stream.js';
+export type { SSEOptions, MidStreamErrorResult } from './handlers/stream.js';
+export { defineErrorTaxonomy } from '../error-taxonomy.js';
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig } from '../error-taxonomy.js';
+export type { QueryParser } from './types.js';
+export declare class HonoAppBuilder<TStreamErrorData = unknown> {
+    readonly config?: HonoAppBuilderConfig<TStreamErrorData> | undefined;
+    private readonly _app;
+    private readonly factories;
+    private _docs;
+    private _skipped;
+    private _built;
+    constructor(config?: HonoAppBuilderConfig<TStreamErrorData> | undefined);
+    static makeRoutePath: typeof _makeRoutePath;
+    get app(): Hono;
+    /**
+     * Lazily computed on first read or `build()`. Computing without `build()`
+     * lets tests and tooling introspect routes without spinning up handlers.
+     */
+    get docs(): AnyHttpRouteDoc[];
+    get skippedProcedures(): {
+        name: string;
+        reason: string;
+    }[];
+    register<TFactory extends ProceduresFactory>(factory: TFactory, factoryContext: ExtractContext<TFactory> | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>), options?: {
+        streamMode?: StreamMode;
+        extendProcedureDoc?: ExtendProcedureDoc;
+    }): this;
+    private computeDocs;
+    /**
+     * Mounts every registered procedure on the Hono app and returns it.
+     * Idempotent: calling twice is a no-op on the second call.
+     */
+    build(): Hono;
+    /**
+     * Produces a {@link DocEnvelope} for single-app usage. For multi-app
+     * aggregation, use {@link DocRegistry} and `from(builder)` instead.
+     *
+     * Mirrors `DocRegistry.toJSON()` options so the two paths produce
+     * interchangeable envelopes for the codegen pipeline.
+     */
+    toDocEnvelope<T = DocEnvelope>(options?: {
+        basePath?: string;
+        errors?: ErrorTaxonomy | ErrorDoc[];
+        includeDefaults?: boolean;
+        headers?: HeaderDoc[];
+        filter?: (route: AnyHttpRouteDoc) => boolean;
+        transform?: (envelope: DocEnvelope) => T;
+    }): T;
+}

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

@@ -0,0 +1,149 @@
+import { Hono } from 'hono';
+import { DocRegistry } from '../doc-registry.js';
+import { buildRpcRouteDoc } from './docs/rpc-doc.js';
+import { buildStreamRouteDoc } from './docs/stream-doc.js';
+import { buildHttpRouteDoc } from './docs/http-doc.js';
+import { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js';
+import { installRpcRoute } from './handlers/rpc.js';
+import { installRpcStreamRoute } from './handlers/stream.js';
+import { installHttpRoute } from './handlers/http.js';
+import { installHttpStreamRoute } from './handlers/http-stream.js';
+import { makeRoutePath as _makeRoutePath } from './path.js';
+export { sse } from './handlers/stream.js';
+export { defineErrorTaxonomy } from '../error-taxonomy.js';
+export class HonoAppBuilder {
+    config;
+    _app;
+    factories = [];
+    _docs = null;
+    _skipped = [];
+    _built = false;
+    constructor(config) {
+        this.config = config;
+        this._app = config?.app ?? new Hono();
+        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);
+            });
+        }
+    }
+    static makeRoutePath = _makeRoutePath;
+    get app() {
+        return this._app;
+    }
+    /**
+     * Lazily computed on first read or `build()`. Computing without `build()`
+     * lets tests and tooling introspect routes without spinning up handlers.
+     */
+    get docs() {
+        if (this._docs === null)
+            this.computeDocs();
+        return this._docs;
+    }
+    get skippedProcedures() {
+        return this._skipped;
+    }
+    register(factory, factoryContext, options) {
+        this.factories.push({
+            factory,
+            factoryContext,
+            streamMode: options?.streamMode,
+            extendProcedureDoc: options?.extendProcedureDoc,
+        });
+        // Invalidate docs cache so the next read recomputes.
+        this._docs = null;
+        return this;
+    }
+    computeDocs() {
+        const docs = [];
+        const skipped = [];
+        for (const item of this.factories) {
+            for (const procedure of item.factory.getProcedures().values()) {
+                const prefix = this.config?.pathPrefix;
+                switch (procedure.kind) {
+                    case 'rpc':
+                        docs.push(buildRpcRouteDoc(procedure, prefix, item.extendProcedureDoc));
+                        break;
+                    case 'rpc-stream':
+                        docs.push(buildStreamRouteDoc(procedure, item.streamMode ?? this.config?.stream?.defaultStreamMode ?? 'sse', prefix, item.extendProcedureDoc));
+                        break;
+                    case 'http':
+                        docs.push(buildHttpRouteDoc(procedure, prefix, item.extendProcedureDoc));
+                        break;
+                    case 'http-stream':
+                        docs.push(buildHttpStreamRouteDoc(procedure, prefix, item.extendProcedureDoc));
+                        break;
+                    default: {
+                        const reason = `Unknown procedure kind "${procedure.kind}"`;
+                        skipped.push({ name: procedure.name, reason });
+                    }
+                }
+            }
+        }
+        this._docs = docs;
+        this._skipped = skipped;
+    }
+    /**
+     * Mounts every registered procedure on the Hono app and returns it.
+     * Idempotent: calling twice is a no-op on the second call.
+     */
+    build() {
+        if (this._built)
+            return this._app;
+        this._built = true;
+        const docs = [];
+        const skipped = [];
+        const cfg = this.config ?? {};
+        for (const item of this.factories) {
+            for (const procedure of item.factory.getProcedures().values()) {
+                switch (procedure.kind) {
+                    case 'rpc':
+                        installRpcRoute({ app: this._app, procedure: procedure, factoryItem: item, cfg, docs });
+                        break;
+                    case 'rpc-stream': {
+                        const streamMode = item.streamMode ?? cfg.stream?.defaultStreamMode ?? 'sse';
+                        installRpcStreamRoute({ app: this._app, procedure: procedure, factoryItem: item, cfg, docs, streamMode });
+                        break;
+                    }
+                    case 'http':
+                        installHttpRoute({ app: this._app, procedure: procedure, factoryItem: item, cfg, docs });
+                        break;
+                    case 'http-stream':
+                        installHttpStreamRoute({ app: this._app, procedure: procedure, factoryItem: item, cfg, docs });
+                        break;
+                    default: {
+                        const reason = `Unknown procedure kind "${procedure.kind}"`;
+                        skipped.push({ name: procedure.name, reason });
+                        console.warn(`[ts-procedures hono] Skipping procedure "${procedure.name}": ${reason}`);
+                    }
+                }
+            }
+        }
+        this._docs = docs;
+        this._skipped = skipped;
+        return this._app;
+    }
+    /**
+     * Produces a {@link DocEnvelope} for single-app usage. For multi-app
+     * aggregation, use {@link DocRegistry} and `from(builder)` instead.
+     *
+     * Mirrors `DocRegistry.toJSON()` options so the two paths produce
+     * interchangeable envelopes for the codegen pipeline.
+     */
+    toDocEnvelope(options) {
+        return new DocRegistry({
+            basePath: options?.basePath ?? this.config?.pathPrefix,
+            errors: options?.errors ?? this.config?.errors,
+            includeDefaults: options?.includeDefaults,
+            headers: options?.headers,
+        }).from(this).toJSON(options);
+    }
+}
+//# sourceMappingURL=index.js.map

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

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

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

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