@carlos-tzin/tzin 0.1.0

package/dist/cli.js

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+function usage() {
+    console.error(`tzin CLI
+
+  tzin dev <entry-file> [--port N]   start dev server with hot reload
+                                     entry must default-export a tzin App`);
+    process.exit(1);
+}
+const [, , cmd, ...rest] = process.argv;
+if (cmd !== 'dev' || rest.length === 0)
+    usage();
+const entry = rest[0];
+let port = '3000';
+const portFlag = rest.indexOf('--port');
+if (portFlag !== -1 && rest[portFlag + 1])
+    port = rest[portFlag + 1];
+const devServer = fileURLToPath(new URL('./dev-server.ts', import.meta.url));
+const child = spawn('npx', ['tsx', 'watch', '--clear-screen=false', devServer, entry, port], {
+    stdio: 'inherit',
+});
+process.on('SIGINT', () => child.kill('SIGINT'));
+child.on('exit', (code) => process.exit(code ?? 0));

package/dist/client-browser.d.ts

@@ -0,0 +1,47 @@
+/**
+ * tzin channels client for browsers and Node >= 22.
+ *
+ * Zero dependencies: uses the platform's EventSource and fetch.
+ *
+ *   import { joinChannel } from 'tzin/client-browser'
+ *
+ *   const chat = joinChannel('https://api.example.com', 'lobby', { member: 'ada' })
+ *   chat.on('message', (data) => console.log(data))
+ *   await chat.push('message', { text: 'hello' })
+ */
+interface SSELike {
+    addEventListener(type: string, listener: (ev: MessageEventLike) => void): void;
+    close(): void;
+}
+interface MessageEventLike {
+    data: unknown;
+}
+export interface JoinOptions {
+    /** Appear in presence under this name. */
+    member?: string;
+    /** Metadata attached to your presence entry. */
+    meta?: unknown;
+    /** Presence refresh interval. Must stay below the server's presence TTL. Default 15s. */
+    heartbeatMs?: number;
+    /**
+     * Custom EventSource implementation. Browsers provide one globally;
+     * Node >= 22 needs a polyfill (e.g. from the 'eventsource' package).
+     */
+    eventSource?: new (url: string) => SSELike;
+}
+export type Unsubscribe = () => void;
+export interface Channel {
+    readonly topic: string;
+    /** Listen to a named event; returns an unsubscribe function. */
+    on(event: string, cb: (data: any) => void): Unsubscribe;
+    /** Broadcast to every subscriber of this channel. */
+    push(event: string, data?: unknown): Promise<{
+        delivered: number;
+    }>;
+    /** Refresh your presence immediately (the client also does this automatically). */
+    heartbeat(): void;
+    /** Close the subscription and leave presence. */
+    close(): void;
+}
+export declare function joinChannel(baseUrl: string, topic: string, options?: JoinOptions): Channel;
+export {};

package/dist/client-browser.js

@@ -0,0 +1,87 @@
+/**
+ * tzin channels client for browsers and Node >= 22.
+ *
+ * Zero dependencies: uses the platform's EventSource and fetch.
+ *
+ *   import { joinChannel } from 'tzin/client-browser'
+ *
+ *   const chat = joinChannel('https://api.example.com', 'lobby', { member: 'ada' })
+ *   chat.on('message', (data) => console.log(data))
+ *   await chat.push('message', { text: 'hello' })
+ */
+function parseData(raw) {
+    try {
+        return typeof raw === 'string' ? JSON.parse(raw) : raw;
+    }
+    catch {
+        return raw;
+    }
+}
+export function joinChannel(baseUrl, topic, options = {}) {
+    const base = baseUrl.replace(/\/$/, '');
+    const { member, meta } = options;
+    const heartbeatMs = options.heartbeatMs ?? 15_000;
+    const EsCtor = options.eventSource ??
+        globalThis.EventSource;
+    if (!EsCtor)
+        throw new Error('EventSource is not available in this runtime');
+    const qs = member !== undefined ? `?member=${encodeURIComponent(member)}` : '';
+    const es = new EsCtor(`${base}/channels/${encodeURIComponent(topic)}${qs}`);
+    const post = async (path, body) => fetch(`${base}/channels/${encodeURIComponent(topic)}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const listeners = new Map();
+    const dispatch = (event, data) => {
+        const set = listeners.get(event);
+        if (set)
+            for (const cb of set)
+                cb(data);
+    };
+    // Known presence events plus any event registered later via .on().
+    es.addEventListener('presence_state', (ev) => dispatch('presence_state', parseData(ev.data)));
+    es.addEventListener('presence_diff', (ev) => dispatch('presence_diff', parseData(ev.data)));
+    es.addEventListener('message', (ev) => dispatch('message', parseData(ev.data)));
+    let timer;
+    if (member !== undefined && heartbeatMs > 0) {
+        timer = setInterval(() => {
+            void post('/heartbeat', { member, meta }).catch(() => { });
+        }, heartbeatMs);
+    }
+    return {
+        topic,
+        on(event, cb) {
+            let set = listeners.get(event);
+            if (!set) {
+                set = new Set();
+                listeners.set(event, set);
+                if (event !== 'message' && event !== 'presence_state' && event !== 'presence_diff') {
+                    es.addEventListener(event, (ev) => dispatch(event, parseData(ev.data)));
+                }
+            }
+            set.add(cb);
+            return () => {
+                set.delete(cb);
+            };
+        },
+        async push(event, data) {
+            const res = await post('', { event, data });
+            if (!res.ok)
+                throw new Error(`push failed: HTTP ${res.status}`);
+            return (await res.json());
+        },
+        heartbeat() {
+            if (member === undefined)
+                return;
+            void post('/heartbeat', { member, meta }).catch(() => { });
+        },
+        close() {
+            if (timer !== undefined)
+                clearInterval(timer);
+            es.close();
+            if (member !== undefined)
+                void post('/leave', { member }).catch(() => { });
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { AnyContract, StaticOf, SectionsOf } from './contract.js';
+/**
+ * One union member per declared response status: checking `res.status === 200`
+ * narrows `body` to exactly what the contract promised. The client trusts the
+ * contract completely — an undeclared status is a contract violation.
+ */
+export type ClientResult<C extends AnyContract> = {
+    [K in keyof C['responses']]: {
+        status: K extends number ? K : K extends `${infer N extends number}` ? N : never;
+        body: StaticOf<C['responses'][K]>;
+    };
+}[keyof C['responses']];
+export type CallerFn<C extends AnyContract> = (input: SectionsOf<C> & {
+    fetchInit?: RequestInit;
+}) => Promise<ClientResult<C>>;
+/** Flat mapped type over a record of contracts: O(routes), no nesting. */
+export type ClientOf<Routes extends Record<string, AnyContract>> = {
+    [K in keyof Routes]: CallerFn<Routes[K]>;
+};
+export declare function client<Routes extends Record<string, AnyContract>>(routes: Routes, baseUrl?: string): ClientOf<Routes>;

package/dist/client.js

@@ -0,0 +1,36 @@
+export function client(routes, baseUrl = '') {
+    return new Proxy({}, {
+        get(_target, key) {
+            if (typeof key !== 'string' || !(key in routes))
+                return undefined;
+            const c = routes[key];
+            return async (input = {}) => {
+                let path = c.path.replace(/:([A-Za-z0-9_]+)/g, (_m, name) => encodeURIComponent(String(input.params?.[name] ?? `{${name}}`)));
+                if (input.query) {
+                    const qs = new URLSearchParams(Object.entries(input.query).map(([k, v]) => [k, String(v)])).toString();
+                    if (qs)
+                        path += `?${qs}`;
+                }
+                const init = { method: c.method, ...input.fetchInit };
+                if ('body' in c && c.body)
+                    init.body = JSON.stringify(input.body);
+                const headers = { ...input.headers };
+                if (input.cookies) {
+                    headers.cookie = Object.entries(input.cookies)
+                        .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+                        .join('; ');
+                }
+                init.headers = { ...init.headers, ...headers };
+                const res = await fetch(baseUrl + path, init);
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    body = null;
+                }
+                return { status: res.status, body };
+            };
+        },
+    });
+}

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+declare const brand: unique symbol;
+/** Typed key for the request context bag. Create once per piece of data. */
+export interface ContextKey<T> {
+    readonly name: string;
+    readonly [brand]?: T;
+}
+export declare function defineContext<T>(name: string): ContextKey<T>;
+/**
+ * Per-request typed store. Middleware writes values; handlers read them.
+ * Keys carry their value type, so get/require are fully inferred.
+ */
+export declare class Ctx {
+    #private;
+    /**
+     * Accepts a ready signal or a factory. Adapters pass a factory so the
+     * AbortController + close-listener wiring only happens when something
+     * actually reads ctx.signal (SSE, channels) — not on the JSON hot path.
+     */
+    constructor(signal?: AbortSignal | (() => AbortSignal | undefined), seed?: ReadonlyMap<ContextKey<never>, unknown>);
+    get signal(): AbortSignal | undefined;
+    get<T>(key: ContextKey<T>): T | undefined;
+    /** Read a mandatory value; a missing one is a server bug -> 500. */
+    require<T>(key: ContextKey<T>): T;
+    set<T>(key: ContextKey<T>, value: T): void;
+}
+export {};

package/dist/context.js

@@ -0,0 +1,49 @@
+import { HttpError } from './contract.js';
+export function defineContext(name) {
+    return { name };
+}
+/**
+ * Per-request typed store. Middleware writes values; handlers read them.
+ * Keys carry their value type, so get/require are fully inferred.
+ */
+export class Ctx {
+    /** Allocated on first use — most requests never touch the bag. */
+    #map;
+    #signal;
+    #getSignal;
+    /**
+     * Accepts a ready signal or a factory. Adapters pass a factory so the
+     * AbortController + close-listener wiring only happens when something
+     * actually reads ctx.signal (SSE, channels) — not on the JSON hot path.
+     */
+    constructor(signal, seed) {
+        if (typeof signal === 'function')
+            this.#getSignal = signal;
+        else
+            this.#signal = signal;
+        if (seed && seed.size > 0) {
+            this.#map = new Map(seed);
+        }
+    }
+    get signal() {
+        if (this.#signal === undefined && this.#getSignal) {
+            this.#signal = this.#getSignal();
+            this.#getSignal = undefined;
+        }
+        return this.#signal;
+    }
+    get(key) {
+        return this.#map?.get(key);
+    }
+    /** Read a mandatory value; a missing one is a server bug -> 500. */
+    require(key) {
+        const v = this.get(key);
+        if (v === undefined)
+            throw new HttpError(500, `Missing context '${key.name}'`);
+        return v;
+    }
+    set(key, value) {
+        ;
+        (this.#map ??= new Map()).set(key, value);
+    }
+}

package/dist/contract.d.ts

@@ -0,0 +1,71 @@
+import type { Static, TSchema } from './schema.js';
+import type { Ctx } from './context.js';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * A Contract is the single source of truth for an endpoint.
+ * Plain object literal -> shallow types -> no deep instantiation.
+ */
+export interface ContractDef {
+    method: HttpMethod;
+    path: string;
+    /** Stable identifier reused by OpenAPI operationId and MCP tool name. */
+    name?: string;
+    /** Human/agent-readable summary, surfaced in OpenAPI and MCP. */
+    description?: string;
+    params?: TSchema;
+    query?: TSchema;
+    body?: TSchema;
+    responses: Record<number, TSchema>;
+}
+/** Identity function with `const` generics: preserves literal method/path/status keys. */
+export declare function contract<const C extends ContractDef>(def: C): C;
+export type AnyContract = ContractDef;
+export type StaticOf<S> = S extends TSchema ? Static<S> : never;
+/** '/users/:id/posts/:postId' -> 'id' | 'postId' */
+export type PathParamNames<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? Name | PathParamNames<Rest> : P extends `${string}:${infer Name}` ? Name : never;
+/**
+ * The request sections a contract declares. Shared by server input and
+ * client call args so both sides stay in sync.
+ */
+export type SectionsOf<C extends AnyContract> = ('params' extends keyof C ? {
+    params: StaticOf<C['params']>;
+} : {}) & ('query' extends keyof C ? {
+    query: StaticOf<C['query']>;
+} : {}) & ('body' extends keyof C ? {
+    body: StaticOf<C['body']>;
+} : {}) & ('headers' extends keyof C ? {
+    headers: StaticOf<C['headers']>;
+} : {}) & ('cookies' extends keyof C ? {
+    cookies: StaticOf<C['cookies']>;
+} : {});
+/** Extractor-style handler input: declared sections + per-request context. */
+export type HandlerInput<C extends AnyContract> = {
+    ctx: Ctx;
+} & SectionsOf<C>;
+/** Discriminated union of every declared success response. */
+export type ResponseOf<C extends AnyContract> = {
+    [K in keyof C['responses']]: {
+        status: K extends number ? K : K extends `${infer N extends number}` ? N : never;
+        body: StaticOf<C['responses'][K]>;
+    };
+}[keyof C['responses']];
+export type Handler<C extends AnyContract> = (input: HandlerInput<C>) => ResponseOf<C> | RawResult | Promise<ResponseOf<C> | RawResult>;
+/** Escape hatch: return a pre-built Response (streaming, files, proxies...). */
+export interface RawResult {
+    readonly __tzin_raw: Response;
+}
+export declare function raw(res: Response): RawResult;
+export declare function isRawResult(v: unknown): v is RawResult;
+export interface RouteImpl<C extends AnyContract = AnyContract> {
+    contract: C;
+    handler: Handler<C>;
+}
+/** Bind an implementation to a contract. The compiler checks inputs AND outputs. */
+export declare function impl<const C extends AnyContract>(c: C, handler: Handler<C>): RouteImpl<C>;
+/** Thrown inside handlers -> converted to an HTTP error response. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    constructor(status: number, message: string, details?: unknown | undefined, headers?: Record<string, string> | undefined);
+}

package/dist/contract.js

@@ -0,0 +1,28 @@
+/** Identity function with `const` generics: preserves literal method/path/status keys. */
+export function contract(def) {
+    return def;
+}
+const RAW_MARKER = '__tzin_raw';
+export function raw(res) {
+    return { [RAW_MARKER]: res };
+}
+export function isRawResult(v) {
+    return typeof v === 'object' && v !== null && RAW_MARKER in v;
+}
+/** Bind an implementation to a contract. The compiler checks inputs AND outputs. */
+export function impl(c, handler) {
+    return { contract: c, handler };
+}
+/** Thrown inside handlers -> converted to an HTTP error response. */
+export class HttpError extends Error {
+    status;
+    details;
+    headers;
+    constructor(status, message, details, headers) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.headers = headers;
+        this.name = 'HttpError';
+    }
+}

package/dist/cors.d.ts

@@ -0,0 +1,27 @@
+import type { Middleware } from './middleware.js';
+/**
+ * How Access-Control-Allow-Origin is computed for a request origin.
+ * - '*': literal wildcard (invalid alongside credentials:true)
+ * - true: reflect any request origin (credentials-safe)
+ * - string[]: allow-list; the matching entry is echoed back
+ */
+export interface CorsOptions {
+    origin?: string | true | string[];
+    /** Default: GET, HEAD, PUT, PATCH, POST, DELETE. */
+    methods?: string[];
+    /** Echoed back when the browser asks via access-control-request-headers. */
+    allowHeaders?: string[];
+    /** Response headers the browser may read from JS. */
+    exposeHeaders?: string[];
+    credentials?: boolean;
+    /** Preflight cache lifetime in seconds. Default 24h. */
+    maxAge?: number;
+}
+/**
+ * CORS as onion middleware. Register outermost so preflight OPTIONS requests
+ * short-circuit before routing (a preflight never matches a route).
+ *
+ * A disallowed origin does not error: the response simply carries no
+ * Access-Control-Allow-Origin header and the browser enforces the block.
+ */
+export declare function cors(options?: CorsOptions): Middleware;

package/dist/cors.js

@@ -0,0 +1,53 @@
+/**
+ * CORS as onion middleware. Register outermost so preflight OPTIONS requests
+ * short-circuit before routing (a preflight never matches a route).
+ *
+ * A disallowed origin does not error: the response simply carries no
+ * Access-Control-Allow-Origin header and the browser enforces the block.
+ */
+export function cors(options = {}) {
+    const { origin = '*', methods = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'], allowHeaders, exposeHeaders, credentials = false, maxAge = 86400, } = options;
+    const methodsHeader = methods.join(', ');
+    function allowOriginFor(requestOrigin) {
+        if (Array.isArray(origin)) {
+            return requestOrigin && origin.includes(requestOrigin) ? requestOrigin : undefined;
+        }
+        if (origin === true)
+            return requestOrigin ?? undefined;
+        // origin is now '*' or an explicit string.
+        return credentials ? undefined : origin;
+    }
+    return async ({ req, next }) => {
+        const requestOrigin = req.headers.get('origin');
+        const requestedMethod = req.headers.get('access-control-request-method');
+        const isPreflight = req.method === 'OPTIONS' && requestedMethod !== null;
+        // Not a CORS request (same-origin GETs, curl, server-to-server): untouched.
+        if (!requestOrigin && !isPreflight)
+            return next();
+        const allowOrigin = allowOriginFor(requestOrigin);
+        const baseHeaders = {
+            vary: 'Origin',
+            ...(allowOrigin ? { 'access-control-allow-origin': allowOrigin } : {}),
+            ...(allowOrigin && credentials ? { 'access-control-allow-credentials': 'true' } : {}),
+        };
+        if (isPreflight) {
+            const requestedHeaders = req.headers.get('access-control-request-headers') ?? allowHeaders?.join(', ');
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    ...baseHeaders,
+                    'access-control-allow-methods': methodsHeader,
+                    'access-control-max-age': String(maxAge),
+                    ...(requestedHeaders ? { 'access-control-allow-headers': requestedHeaders } : {}),
+                },
+            });
+        }
+        const res = await next();
+        for (const [k, v] of Object.entries(baseHeaders))
+            res.headers.set(k, v);
+        if (exposeHeaders?.length) {
+            res.headers.set('access-control-expose-headers', exposeHeaders.join(', '));
+        }
+        return res;
+    };
+}

package/dist/dev-server.d.ts

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

package/dist/dev-server.js

@@ -0,0 +1,30 @@
+import { pathToFileURL } from 'node:url';
+import { listen } from './node.js';
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+function printRouteTable(routes) {
+    console.log(`\ntzin dev · ${routes.length} routes\n`);
+    for (const { contract: c } of routes) {
+        const method = `\x1b[36m${pad(c.method, 7)}\x1b[0m`;
+        const name = c.name ? ` \x1b[2m${c.name}\x1b[0m` : '';
+        const desc = c.description ? `  \x1b[2m— ${c.description}\x1b[0m` : '';
+        console.log(`  ${method} ${pad(c.path, 34)}${name}${desc}`);
+    }
+    console.log('');
+}
+const entry = process.argv[2];
+const port = Number(process.argv[3] ?? 3000);
+if (!entry) {
+    console.error('usage: dev-server <entry-file> [port]');
+    process.exit(1);
+}
+const mod = await import(pathToFileURL(entry).href);
+const app = mod.default ?? mod.app;
+if (!app || typeof app.fetch !== 'function' || !Array.isArray(app.routes)) {
+    console.error('entry file must default-export (or export `app`) a tzin App');
+    process.exit(1);
+}
+printRouteTable(app.routes);
+listen(app, port);
+console.log(`\x1b[32m➜\x1b[0m http://localhost:${port}  (watching for changes)`);

package/dist/hub.d.ts

@@ -0,0 +1,39 @@
+export interface ChannelEvent {
+    topic: string;
+    event: string;
+    data: unknown;
+}
+export type Subscriber = (e: ChannelEvent) => void;
+export interface BusLike {
+    publish(channel: string, message: string): void;
+    subscribe(channel: string, handler: (message: string) => void): () => void;
+}
+export interface HubOptions {
+    /**
+     * Wire this hub into a cluster: publishes fan out over the bus and remote
+     * frames are delivered to local subscribers (own frames are ignored).
+     * See src/bus.ts — Redis PUBLISH/SUBSCRIBE maps directly onto it.
+     */
+    bus?: BusLike;
+    channelPrefix?: string;
+}
+/**
+ * In-process pub/sub hub — the local delivery point of a realtime node.
+ * Standalone by default; pass `bus` to join a multi-node deployment.
+ */
+export declare class Hub {
+    #private;
+    constructor(options?: HubOptions);
+    /**
+     * Infrastructure hook: invoked for every frame arriving from OTHER nodes
+     * over the dedicated infra channel, even when the topic has no local
+     * subscribers (e.g. presence replication). Returns an unsubscribe function.
+     */
+    onRemote(fn: Subscriber): () => void;
+    /** Broadcast an infrastructure event to every other node's onRemote listeners. */
+    emitRemote(e: ChannelEvent): void;
+    subscribe(topic: string, fn: Subscriber): () => void;
+    /** Deliver locally and, when clustered, broadcast to every other node. */
+    publish(topic: string, event: string, data: unknown): number;
+    subscriberCount(topic: string): number;
+}