ts-procedures 8.5.0 → 9.0.0

package/build/server/request/params.test.js

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'vitest';
+import { BODY_METHODS, defaultSuccessStatus, extractReqChannels } from './params.js';
+import { parseQueryNative } from './query.js';
+function makeSource(overrides) {
+    return {
+        pathParams: () => ({ id: '42' }),
+        url: () => 'http://localhost/users/42?limit=10&tag=a&tag=b',
+        json: async () => ({ name: 'Ada' }),
+        headers: () => ({ 'x-api-key': 'secret' }),
+        ...overrides,
+    };
+}
+describe('extractReqChannels', () => {
+    test('extracts only the declared channels', async () => {
+        const params = await extractReqChannels(makeSource(), 'get', { query: {} }, parseQueryNative);
+        expect(Object.keys(params)).toEqual(['query']);
+        expect(params.query).toEqual({ limit: '10', tag: ['a', 'b'] });
+    });
+    test('extracts pathParams channel', async () => {
+        const params = await extractReqChannels(makeSource(), 'get', { pathParams: {} }, parseQueryNative);
+        expect(params).toEqual({ pathParams: { id: '42' } });
+    });
+    test('extracts headers channel (lowercased keys come from the source)', async () => {
+        const params = await extractReqChannels(makeSource(), 'get', { headers: {} }, parseQueryNative);
+        expect(params).toEqual({ headers: { 'x-api-key': 'secret' } });
+    });
+    test('extracts all four channels for a body-carrying method', async () => {
+        const params = await extractReqChannels(makeSource(), 'post', { pathParams: {}, query: {}, body: {}, headers: {} }, parseQueryNative);
+        expect(params).toEqual({
+            pathParams: { id: '42' },
+            query: { limit: '10', tag: ['a', 'b'] },
+            body: { name: 'Ada' },
+            headers: { 'x-api-key': 'secret' },
+        });
+    });
+    test.each(['post', 'put', 'patch'])('parses the body for %s', async (method) => {
+        const params = await extractReqChannels(makeSource(), method, { body: {} }, parseQueryNative);
+        expect(params.body).toEqual({ name: 'Ada' });
+    });
+    test.each(['get', 'head', 'delete'])('skips the body for %s (never calls source.json)', async (method) => {
+        let jsonCalled = false;
+        const source = makeSource({
+            json: async () => {
+                jsonCalled = true;
+                return {};
+            },
+        });
+        const params = await extractReqChannels(source, method, { body: {} }, parseQueryNative);
+        expect(jsonCalled).toBe(false);
+        expect('body' in params).toBe(false);
+    });
+    test('JSON parse failure yields {} so validation reports the missing fields', async () => {
+        const source = makeSource({
+            json: async () => {
+                throw new SyntaxError('Unexpected token');
+            },
+        });
+        const params = await extractReqChannels(source, 'post', { body: {} }, parseQueryNative);
+        expect(params.body).toEqual({});
+    });
+    test('unknown channel is set to undefined (key present, no extraction)', async () => {
+        const params = await extractReqChannels(makeSource(), 'get', { cookies: {} }, parseQueryNative);
+        expect('cookies' in params).toBe(true);
+        expect(params.cookies).toBeUndefined();
+    });
+    test('empty schema extracts nothing', async () => {
+        const params = await extractReqChannels(makeSource(), 'post', {}, parseQueryNative);
+        expect(params).toEqual({});
+    });
+    test('custom query parser is used for the query channel', async () => {
+        const params = await extractReqChannels(makeSource(), 'get', { query: {} }, (raw) => ({ raw }));
+        expect(params.query).toEqual({ raw: 'limit=10&tag=a&tag=b' });
+    });
+});
+describe('BODY_METHODS', () => {
+    test('contains exactly post, put, patch', () => {
+        expect(BODY_METHODS).toEqual(['post', 'put', 'patch']);
+    });
+});
+describe('defaultSuccessStatus', () => {
+    test('post → 201', () => {
+        expect(defaultSuccessStatus('post')).toBe(201);
+    });
+    test('delete → 204', () => {
+        expect(defaultSuccessStatus('delete')).toBe(204);
+    });
+    test.each(['get', 'put', 'patch', 'head'])('%s → 200', (method) => {
+        expect(defaultSuccessStatus(method)).toBe(200);
+    });
+});
+//# sourceMappingURL=params.test.js.map

package/build/server/request/params.test.js.map

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

package/build/server/request/query.d.ts

@@ -0,0 +1,9 @@
+/** Parses a raw query string into a params record. */
+export type QueryParser = (queryString: string) => Record<string, unknown>;
+/**
+ * Default query parser using URLSearchParams. Multi-value keys become arrays;
+ * single-value keys remain scalars (matches browser-native behavior).
+ */
+export declare function parseQueryNative(queryString: string): Record<string, unknown>;
+/** Extracts and parses the query string portion of a URL (empty object when none). */
+export declare function extractQuery(url: string, parser: QueryParser): Record<string, unknown>;

package/build/server/request/query.js

@@ -0,0 +1,22 @@
+/**
+ * Default query parser using URLSearchParams. Multi-value keys become arrays;
+ * single-value keys remain scalars (matches browser-native behavior).
+ */
+export function parseQueryNative(queryString) {
+    const sp = new URLSearchParams(queryString);
+    const result = {};
+    for (const key of new Set(sp.keys())) {
+        const values = sp.getAll(key);
+        result[key] = values.length > 1 ? values : values[0];
+    }
+    return result;
+}
+/** Extracts and parses the query string portion of a URL (empty object when none). */
+export function extractQuery(url, parser) {
+    const q = url.indexOf('?');
+    if (q === -1)
+        return {};
+    const raw = url.slice(q + 1);
+    return raw ? parser(raw) : {};
+}
+//# sourceMappingURL=query.js.map

package/build/server/request/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/server/request/query.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,WAAW,CAAC,CAAA;IAC3C,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAmB;IAC3D,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAA;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC/B,CAAC"}

package/build/server/request/query.test.d.ts

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

package/build/server/request/query.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'vitest';
+import { extractQuery, parseQueryNative } from './query.js';
+describe('parseQueryNative', () => {
+    test('single-value keys remain scalars', () => {
+        expect(parseQueryNative('a=1&b=two')).toEqual({ a: '1', b: 'two' });
+    });
+    test('multi-value keys become arrays', () => {
+        expect(parseQueryNative('tag=a&tag=b&tag=c')).toEqual({ tag: ['a', 'b', 'c'] });
+    });
+    test('mixes scalars and arrays', () => {
+        expect(parseQueryNative('limit=10&tag=a&tag=b')).toEqual({ limit: '10', tag: ['a', 'b'] });
+    });
+    test('empty string parses to an empty object', () => {
+        expect(parseQueryNative('')).toEqual({});
+    });
+    test('decodes URL-encoded values (URLSearchParams semantics)', () => {
+        expect(parseQueryNative('q=hello%20world&plus=a+b')).toEqual({
+            q: 'hello world',
+            plus: 'a b',
+        });
+    });
+    test('key without a value yields an empty string', () => {
+        expect(parseQueryNative('flag')).toEqual({ flag: '' });
+    });
+});
+describe('extractQuery', () => {
+    test('parses the query portion of a URL', () => {
+        expect(extractQuery('http://localhost/users?limit=10&tag=a', parseQueryNative)).toEqual({
+            limit: '10',
+            tag: 'a',
+        });
+    });
+    test('returns {} when the URL has no "?"', () => {
+        expect(extractQuery('http://localhost/users', parseQueryNative)).toEqual({});
+    });
+    test('returns {} for a trailing "?" with an empty query', () => {
+        expect(extractQuery('http://localhost/users?', parseQueryNative)).toEqual({});
+    });
+    test('custom parser receives the raw query string and its result passes through', () => {
+        let receivedRaw;
+        const custom = (raw) => {
+            receivedRaw = raw;
+            return { parsed: true };
+        };
+        const result = extractQuery('http://localhost/p?a=1&b=2', custom);
+        expect(receivedRaw).toBe('a=1&b=2');
+        expect(result).toEqual({ parsed: true });
+    });
+    test('custom parser is NOT invoked when there is no query string', () => {
+        let called = false;
+        const custom = (raw) => {
+            called = true;
+            return { raw };
+        };
+        expect(extractQuery('http://localhost/p', custom)).toEqual({});
+        expect(extractQuery('http://localhost/p?', custom)).toEqual({});
+        expect(called).toBe(false);
+    });
+});
+//# sourceMappingURL=query.test.js.map

package/build/server/request/query.test.js.map

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

package/build/server/sse.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SSE metadata attachment, shared by every server adapter's stream handlers.
+ */
+export type SSEOptions = {
+    event?: string;
+    id?: string;
+    retry?: number;
+};
+/**
+ * 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:
+ *
+ * ```ts
+ * yield sse({ progress: 0.5 }, { event: 'progress', id: 'p-1' })
+ * ```
+ *
+ * The value is returned unchanged — metadata rides in a WeakMap, never on
+ * the payload.
+ */
+export declare function sse<T extends object>(data: T, options?: SSEOptions): T;
+/** Reads metadata attached via {@link sse}. Undefined for plain values. */
+export declare function getSSEMeta(value: unknown): SSEOptions | undefined;
+/** One wire-ready SSE event, as handed to the adapter's write function. */
+export type SseEvent = {
+    data: string;
+    event: string;
+    id: string;
+    retry?: number;
+};
+/** Adapter-provided sink (e.g. Hono's `stream.writeSSE`). */
+export type SseWrite = (event: SseEvent) => void | Promise<void>;
+/** Yield payloads: strings pass through, `null`/`undefined` become empty data. */
+export declare function serializeSseValue(value: unknown): string;
+/**
+ * The SSE wire protocol shared by every stream handler: auto-incrementing
+ * event ids, `sse()` metadata overrides, the `event: 'return'` envelope for
+ * the generator's return value, and the error-event shape after mid-stream
+ * dispatch. Adapters supply only the framework write function.
+ */
+export declare class SseEventSequencer {
+    private readonly write;
+    /** Event name for yields without `sse()` metadata — the procedure name. */
+    private readonly defaultEvent;
+    private eventId;
+    constructor(write: SseWrite, 
+    /** Event name for yields without `sse()` metadata — the procedure name. */
+    defaultEvent: string);
+    /** Writes one yielded value; `sse()` metadata overrides event/id/retry. */
+    writeYield(value: unknown): Promise<void>;
+    /**
+     * Writes the generator's return value as the `event: 'return'` payload
+     * (clients resolve it via `TypedStream.result`). Skipped for `undefined` —
+     * a `void` generator produces no return event.
+     */
+    writeReturn(value: unknown): Promise<void>;
+    /**
+     * Writes a dispatched mid-stream error. `sse()` metadata on the payload
+     * (attachable inside `onMidStreamError`) wins over the dispatcher's event.
+     */
+    writeError(dispatched: {
+        data: unknown;
+        sseEvent?: string;
+    }): Promise<void>;
+    /**
+     * Drives a complete stream: every yield, then the return event. Errors from
+     * the iterator propagate to the caller, which dispatches them and writes the
+     * result via {@link writeError} (the id sequence continues across the two).
+     */
+    pump(iterator: AsyncIterator<unknown, unknown>): Promise<void>;
+}

package/build/server/sse.js

@@ -0,0 +1,94 @@
+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:
+ *
+ * ```ts
+ * yield sse({ progress: 0.5 }, { event: 'progress', id: 'p-1' })
+ * ```
+ *
+ * The value is returned unchanged — metadata rides in a WeakMap, never on
+ * the payload.
+ */
+export function sse(data, options) {
+    sseMetadata.set(data, options ?? {});
+    return data;
+}
+/** Reads metadata attached via {@link sse}. Undefined for plain values. */
+export function getSSEMeta(value) {
+    if (typeof value === 'object' && value !== null) {
+        return sseMetadata.get(value);
+    }
+    return undefined;
+}
+/** Yield payloads: strings pass through, `null`/`undefined` become empty data. */
+export function serializeSseValue(value) {
+    if (typeof value === 'string')
+        return value;
+    return value != null ? JSON.stringify(value) : '';
+}
+/**
+ * The SSE wire protocol shared by every stream handler: auto-incrementing
+ * event ids, `sse()` metadata overrides, the `event: 'return'` envelope for
+ * the generator's return value, and the error-event shape after mid-stream
+ * dispatch. Adapters supply only the framework write function.
+ */
+export class SseEventSequencer {
+    write;
+    defaultEvent;
+    eventId = 0;
+    constructor(write, 
+    /** Event name for yields without `sse()` metadata — the procedure name. */
+    defaultEvent) {
+        this.write = write;
+        this.defaultEvent = defaultEvent;
+    }
+    /** Writes one yielded value; `sse()` metadata overrides event/id/retry. */
+    async writeYield(value) {
+        const meta = getSSEMeta(value);
+        await this.write({
+            data: serializeSseValue(value),
+            event: meta?.event ?? this.defaultEvent,
+            id: meta?.id ?? String(this.eventId++),
+            ...(meta?.retry !== undefined && { retry: meta.retry }),
+        });
+    }
+    /**
+     * Writes the generator's return value as the `event: 'return'` payload
+     * (clients resolve it via `TypedStream.result`). Skipped for `undefined` —
+     * a `void` generator produces no return event.
+     */
+    async writeReturn(value) {
+        if (value === undefined)
+            return;
+        const data = typeof value === 'string' ? value : JSON.stringify(value);
+        await this.write({ data, event: 'return', id: String(this.eventId++) });
+    }
+    /**
+     * Writes a dispatched mid-stream error. `sse()` metadata on the payload
+     * (attachable inside `onMidStreamError`) wins over the dispatcher's event.
+     */
+    async writeError(dispatched) {
+        const meta = getSSEMeta(dispatched.data);
+        await this.write({
+            data: serializeSseValue(dispatched.data),
+            event: meta?.event ?? dispatched.sseEvent ?? 'error',
+            id: meta?.id ?? String(this.eventId++),
+            ...(meta?.retry !== undefined && { retry: meta.retry }),
+        });
+    }
+    /**
+     * Drives a complete stream: every yield, then the return event. Errors from
+     * the iterator propagate to the caller, which dispatches them and writes the
+     * result via {@link writeError} (the id sequence continues across the two).
+     */
+    async pump(iterator) {
+        let result = await iterator.next();
+        while (!result.done) {
+            await this.writeYield(result.value);
+            result = await iterator.next();
+        }
+        await this.writeReturn(result.value);
+    }
+}
+//# sourceMappingURL=sse.js.map

package/build/server/sse.js.map

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

package/build/server/sse.test.d.ts

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

package/build/server/sse.test.js

@@ -0,0 +1,98 @@
+import { describe, expect, it, test } from 'vitest';
+import { SseEventSequencer, getSSEMeta, serializeSseValue, sse } from './sse.js';
+describe('sse', () => {
+    test('returns the value unchanged (same reference)', () => {
+        const payload = { progress: 0.5 };
+        const result = sse(payload, { event: 'progress' });
+        expect(result).toBe(payload);
+        // Metadata rides in a WeakMap — never on the payload itself.
+        expect(Object.keys(result)).toEqual(['progress']);
+    });
+    test('getSSEMeta round-trips the attached options', () => {
+        const payload = sse({ progress: 0.5 }, { event: 'progress', id: 'p-1', retry: 3000 });
+        expect(getSSEMeta(payload)).toEqual({ event: 'progress', id: 'p-1', retry: 3000 });
+    });
+    test('defaults to {} when no options are given', () => {
+        const payload = sse({ done: true });
+        expect(getSSEMeta(payload)).toEqual({});
+    });
+    test('metadata is per-object — two payloads keep separate options', () => {
+        const a = sse({ n: 1 }, { event: 'a' });
+        const b = sse({ n: 2 }, { event: 'b' });
+        expect(getSSEMeta(a)).toEqual({ event: 'a' });
+        expect(getSSEMeta(b)).toEqual({ event: 'b' });
+    });
+});
+describe('getSSEMeta', () => {
+    test('returns undefined for plain (undecorated) objects', () => {
+        expect(getSSEMeta({ progress: 0.5 })).toBeUndefined();
+    });
+    test('returns undefined for primitives', () => {
+        expect(getSSEMeta('text')).toBeUndefined();
+        expect(getSSEMeta(42)).toBeUndefined();
+        expect(getSSEMeta(true)).toBeUndefined();
+        expect(getSSEMeta(undefined)).toBeUndefined();
+    });
+    test('returns undefined for null', () => {
+        expect(getSSEMeta(null)).toBeUndefined();
+    });
+});
+describe('SseEventSequencer', () => {
+    function collector() {
+        const written = [];
+        return { written, write: (e) => void written.push(e) };
+    }
+    async function* gen(values, ret) {
+        for (const v of values)
+            yield v;
+        return ret;
+    }
+    it('writes yields with the default event and auto-incrementing ids', async () => {
+        const { written, write } = collector();
+        await new SseEventSequencer(write, 'Watch').pump(gen([{ a: 1 }, { a: 2 }]));
+        expect(written).toEqual([
+            { data: '{"a":1}', event: 'Watch', id: '0' },
+            { data: '{"a":2}', event: 'Watch', id: '1' },
+        ]);
+    });
+    it('sse() metadata overrides event/id/retry on yields', async () => {
+        const { written, write } = collector();
+        const tagged = sse({ p: 1 }, { event: 'progress', id: 'p-1', retry: 5 });
+        await new SseEventSequencer(write, 'Watch').pump(gen([tagged, { p: 2 }]));
+        expect(written[0]).toEqual({ data: '{"p":1}', event: 'progress', id: 'p-1', retry: 5 });
+        // counter not consumed by the custom id — next auto id is still 0
+        expect(written[1]).toEqual({ data: '{"p":2}', event: 'Watch', id: '0' });
+    });
+    it('emits the return value as event: return and skips undefined returns', async () => {
+        const { written, write } = collector();
+        await new SseEventSequencer(write, 'W').pump(gen([1], { total: 1 }));
+        expect(written[1]).toEqual({ data: '{"total":1}', event: 'return', id: '1' });
+        const second = collector();
+        await new SseEventSequencer(second.write, 'W').pump(gen([1]));
+        expect(second.written).toHaveLength(1);
+    });
+    it('writeError continues the id sequence and honors dispatched/meta events', async () => {
+        const { written, write } = collector();
+        const seq = new SseEventSequencer(write, 'W');
+        await seq.writeYield('x');
+        await seq.writeError({ data: { error: 'boom' }, sseEvent: 'error' });
+        expect(written[1]).toEqual({ data: '{"error":"boom"}', event: 'error', id: '1' });
+        await seq.writeError({ data: sse({ msg: 'm' }, { event: 'custom-fail' }) });
+        expect(written[2].event).toBe('custom-fail');
+    });
+    it('serializeSseValue: strings pass through, null/undefined become empty', () => {
+        expect(serializeSseValue('raw')).toBe('raw');
+        expect(serializeSseValue(null)).toBe('');
+        expect(serializeSseValue(undefined)).toBe('');
+        expect(serializeSseValue(7)).toBe('7');
+    });
+    it('propagates iterator errors to the caller (dispatch happens outside)', async () => {
+        const { write } = collector();
+        async function* boom() {
+            yield 1;
+            throw new Error('mid');
+        }
+        await expect(new SseEventSequencer(write, 'W').pump(boom())).rejects.toThrow('mid');
+    });
+});
+//# sourceMappingURL=sse.test.js.map

package/build/server/sse.test.js.map

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

package/build/{implementations → server}/types.d.ts

@@ -1,5 +1,13 @@
-import type { Procedures } from '../index.js';
-import type { ErrorTaxonomy } from './http/error-taxonomy.js';
+/**
+ * Transport-agnostic HTTP server types.
+ *
+ * The doc shapes here (`*RouteDoc`, `DocEnvelope`, `ErrorDoc`, `HeaderDoc`)
+ * are a FROZEN wire contract: they are the input to client codegen, and v9
+ * guarantees byte-identical generated output vs v8. Do not change field names,
+ * optionality, or nesting without re-validating the codegen goldens.
+ */
+import type { ProcedureKind } from '../core/types.js';
+import type { ErrorTaxonomy } from './errors/taxonomy.js';
 /**
  * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
  * (unconstrained). Narrow it by passing `keyof typeof yourTaxonomy & string`
@@ -15,10 +23,6 @@ export interface RPCConfig<TErrorKey extends string = string> {
      */
     errors?: TErrorKey[];
 }
-export type FactoryItem<C> = {
-    factory: ReturnType<typeof Procedures<C, RPCConfig>>;
-    factoryContext: (req: Request) => C;
-};
 export interface RPCHttpRouteDoc extends RPCConfig {
     kind: 'rpc';
     name: string;
@@ -39,7 +43,7 @@ export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head';
  * typo protection on `errors`.
  */
 export interface APIConfig<TErrorKey extends string = string> {
-    /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
+    /** HTTP route path (supports path params, e.g., '/users/:id') */
     path: string;
     /** HTTP method for this endpoint */
     method: HttpMethod;
@@ -78,12 +82,12 @@ export interface APIHttpRouteDoc {
     };
 }
 /**
- * Constrains schema.input channel names to valid HTTP input sources.
- * Use with `satisfies` or as a type annotation to catch typos at compile time:
+ * Constrains `schema.req` channel names to valid HTTP input sources.
+ * Use with `satisfies` to catch typos at compile time:
  *
  * @example
  * schema: {
- *   input: {
+ *   req: {
  *     pathParams: Type.Object({ id: Type.String() }),
  *     qurey: Type.Object({ ... }), // TS error: 'qurey' not in APIInput
  *   } satisfies APIInput
@@ -162,8 +166,7 @@ export type ExtractConfig<TFactory> = TFactory extends {
 export type ProceduresFactory = {
     getProcedures: () => Array<{
         name: string;
-        kind?: import('../types.js').ProcedureKind;
-        isStream?: boolean;
+        kind?: ProcedureKind;
         config: any;
         handler: (ctx: any, params?: any) => Promise<any> | AsyncGenerator<any, any, unknown>;
     }>;
@@ -177,9 +180,8 @@ export interface DocSource<T = AnyHttpRouteDoc> {
     readonly docs: T[];
     /**
      * Optional list of procedures that were registered with this builder but
-     * couldn't be served by it (e.g. a streaming procedure registered with an
-     * RPC builder). DocRegistry aggregates these across sources and warns at
-     * `toJSON()` time so silently-dropped procedures don't slip through.
+     * couldn't be served by it. DocRegistry aggregates these across sources and
+     * warns at `toJSON()` time so silently-dropped procedures don't slip through.
      */
     readonly skippedProcedures?: {
         name: string;

package/build/{implementations → server}/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/implementations/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":""}

package/docs/astro-adapter.md

@@ -26,7 +26,6 @@ my-astro-app/
 ```ts
 // src/server/procedures/users.ts
 import { Procedures } from 'ts-procedures'
-import type { APIConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
 
 type UserContext = {
@@ -34,17 +33,17 @@ type UserContext = {
   currentUser: { id: string } | null
 }
 
-export const usersAPI = Procedures<UserContext, APIConfig>()
+export const usersAPI = Procedures<UserContext>()
 
-usersAPI.Create(
+usersAPI.CreateHttp(
   'GetUser',
   {
     path: '/users/:id',
     method: 'get',
     scope: 'users', // drives the generated client namespace: api.users.GetUser(...)
     schema: {
-      input: { pathParams: Type.Object({ id: Type.String() }) },
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+      req: { pathParams: Type.Object({ id: Type.String() }) },
+      res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
     },
   },
   async (ctx, { pathParams }) => {
@@ -128,8 +127,7 @@ The adapter does NOT couple to `DocRegistry`. Wire codegen separately, against t
 
 ```ts
 // scripts/build-docs.ts
-import { writeFileSync } from 'node:fs'
-import { DocRegistry } from 'ts-procedures/http-docs'
+import { writeDocEnvelope } from 'ts-procedures'
 import { HonoAppBuilder } from 'ts-procedures/hono'
 import { usersAPI } from '../src/server/procedures/users'
 
@@ -138,10 +136,11 @@ import { usersAPI } from '../src/server/procedures/users'
 const builder = new HonoAppBuilder().register(usersAPI, () => ({} as never))
 builder.build()
 
-const envelope = new DocRegistry().from(builder).toEnvelope()
-writeFileSync('envelope.json', JSON.stringify(envelope, null, 2))
+await writeDocEnvelope(builder, 'envelope.json')
 ```
 
+`writeDocEnvelope` accepts a built `HonoAppBuilder` (it calls `toDocEnvelope()` for you), a `DocRegistry`, or a plain `DocEnvelope` object, and writes pretty JSON to disk.
+
 ### Wire it as an npm script
 
 ```jsonc