@carlos-tzin/tzin 0.1.0

package/dist/openapi.js

@@ -0,0 +1,85 @@
+/** '/users/:id' -> '/users/{id}' (OpenAPI syntax) */
+function toOpenApiPath(path) {
+    return path.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+}
+function schemaRefOrInline(schema) {
+    // TypeBox schemas ARE JSON Schema; strip non-JSON symbol-keyed internals via JSON round-trip.
+    return JSON.parse(JSON.stringify(schema));
+}
+/**
+ * OpenAPI 3.1 document generated from contracts.
+ * Zero conversion layer: TypeBox == JSON Schema == OpenAPI component vocabulary.
+ */
+export function generateOpenApi(routes, info = { title: 'API', version: '0.0.0' }) {
+    const paths = {};
+    for (const { contract: c } of routes) {
+        const oaPath = toOpenApiPath(c.path);
+        const operation = {
+            operationId: c.name ?? `${c.method.toLowerCase()}_${oaPath.replace(/[^A-Za-z0-9]+/g, '_')}`,
+            ...(c.description ? { description: c.description } : {}),
+            responses: Object.fromEntries(Object.entries(c.responses).map(([status, schema]) => [
+                status,
+                {
+                    description: `Response ${status}`,
+                    content: { 'application/json': { schema: schemaRefOrInline(schema) } },
+                },
+            ])),
+        };
+        const parameters = [];
+        if ('params' in c && c.params) {
+            const shape = c.params.properties ?? {};
+            for (const [name, schema] of Object.entries(shape)) {
+                parameters.push({
+                    name,
+                    in: 'path',
+                    required: true,
+                    schema: schemaRefOrInline(schema),
+                });
+            }
+        }
+        if ('query' in c && c.query) {
+            const shape = c.query.properties ?? {};
+            for (const [name, schema] of Object.entries(shape)) {
+                parameters.push({ name, in: 'query', required: false, schema: schemaRefOrInline(schema) });
+            }
+        }
+        const isOptionalSchema = (schema) => schema[Symbol.for('TypeBox.Optional')] === 'Optional';
+        if ('headers' in c && c.headers) {
+            const shape = c.headers.properties ?? {};
+            for (const [name, schema] of Object.entries(shape)) {
+                parameters.push({
+                    name,
+                    in: 'header',
+                    required: !isOptionalSchema(schema),
+                    schema: schemaRefOrInline(schema),
+                });
+            }
+        }
+        if ('cookies' in c && c.cookies) {
+            const shape = c.cookies.properties ?? {};
+            for (const [name, schema] of Object.entries(shape)) {
+                parameters.push({
+                    name,
+                    in: 'cookie',
+                    required: !isOptionalSchema(schema),
+                    schema: schemaRefOrInline(schema),
+                });
+            }
+        }
+        if (parameters.length)
+            operation.parameters = parameters;
+        if ('body' in c && c.body) {
+            operation.requestBody = {
+                required: true,
+                content: { 'application/json': { schema: schemaRefOrInline(c.body) } },
+            };
+        }
+        paths[oaPath] ??= {};
+        paths[oaPath][c.method.toLowerCase()] = operation;
+    }
+    return {
+        openapi: '3.1.0',
+        info,
+        paths,
+    };
+}

package/dist/presence.d.ts

@@ -0,0 +1,30 @@
+import type { Hub } from './hub.js';
+export interface MemberInfo {
+    member: string;
+    meta?: unknown;
+    onlineAt: number;
+    lastSeen: number;
+}
+/**
+ * Phoenix-style presence tracking over a Hub.
+ * Members heartbeat to stay listed; a TTL sweep removes ghosts and
+ * broadcasts `presence_diff`. Full `presence_state` is broadcast on joins.
+ *
+ * Cluster-aware: frames arriving from other nodes (via the hub's bus) are
+ * merged silently into the local map, so every node holds the full view —
+ * clients already receive the state/diff events through normal delivery.
+ * Any node's sweep can therefore expire ghosts left behind by a dead node.
+ */
+export declare class Presence {
+    #private;
+    private readonly hub;
+    private readonly ttlMs;
+    constructor(hub: Hub, ttlMs?: number);
+    startSweeping(intervalMs?: number): void;
+    stopSweeping(): void;
+    join(topic: string, member: string, meta?: unknown): void;
+    heartbeat(topic: string, member: string, meta?: unknown): void;
+    leave(topic: string, member: string): void;
+    snapshot(topic: string): MemberInfo[];
+    sweep(): void;
+}

package/dist/presence.js

@@ -0,0 +1,115 @@
+/**
+ * Phoenix-style presence tracking over a Hub.
+ * Members heartbeat to stay listed; a TTL sweep removes ghosts and
+ * broadcasts `presence_diff`. Full `presence_state` is broadcast on joins.
+ *
+ * Cluster-aware: frames arriving from other nodes (via the hub's bus) are
+ * merged silently into the local map, so every node holds the full view —
+ * clients already receive the state/diff events through normal delivery.
+ * Any node's sweep can therefore expire ghosts left behind by a dead node.
+ */
+export class Presence {
+    hub;
+    ttlMs;
+    #topics = new Map();
+    #sweeper;
+    constructor(hub, ttlMs = 30_000) {
+        this.hub = hub;
+        this.ttlMs = ttlMs;
+        hub.onRemote((e) => this.#applyRemote(e));
+    }
+    startSweeping(intervalMs = this.ttlMs) {
+        if (this.#sweeper)
+            return;
+        this.#sweeper = setInterval(() => this.sweep(), intervalMs);
+        this.#sweeper.unref?.();
+    }
+    stopSweeping() {
+        if (this.#sweeper)
+            clearInterval(this.#sweeper);
+        this.#sweeper = undefined;
+    }
+    join(topic, member, meta) {
+        const now = Date.now();
+        const members = this.#members(topic);
+        const existing = members.get(member);
+        members.set(member, {
+            member,
+            ...(meta !== undefined ? { meta } : {}),
+            onlineAt: existing?.onlineAt ?? now,
+            lastSeen: now,
+        });
+        this.hub.publish(topic, 'presence_state', { members: this.snapshot(topic) });
+        this.hub.emitRemote({ topic, event: 'presence_state', data: { members: this.snapshot(topic) } });
+    }
+    heartbeat(topic, member, meta) {
+        this.join(topic, member, meta);
+    }
+    leave(topic, member) {
+        const members = this.#topics.get(topic);
+        if (!members?.delete(member))
+            return;
+        if (members.size === 0)
+            this.#topics.delete(topic);
+        this.hub.publish(topic, 'presence_diff', { leaves: [member] });
+        this.hub.emitRemote({ topic, event: 'presence_diff', data: { leaves: [member] } });
+    }
+    snapshot(topic) {
+        return [...(this.#topics.get(topic)?.values() ?? [])].map((m) => ({ ...m }));
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [topic, members] of [...this.#topics]) {
+            const expired = [...members.values()].filter((m) => now - m.lastSeen > this.ttlMs);
+            for (const m of expired)
+                members.delete(m.member);
+            if (expired.length) {
+                if (members.size === 0)
+                    this.#topics.delete(topic);
+                this.hub.publish(topic, 'presence_diff', { leaves: expired.map((m) => m.member) });
+                this.hub.emitRemote({
+                    topic,
+                    event: 'presence_diff',
+                    data: { leaves: expired.map((m) => m.member) },
+                });
+            }
+        }
+    }
+    #members(topic) {
+        let m = this.#topics.get(topic);
+        if (!m) {
+            m = new Map();
+            this.#topics.set(topic, m);
+        }
+        return m;
+    }
+    /**
+     * Merge a frame from another node without re-publishing (no loops):
+     * state frames add/refresh replicas; leaf diffs remove them. `lastSeen`
+     * is stamped with the local clock so sweeps work despite node clock skew.
+     */
+    #applyRemote(e) {
+        if (e.event === 'presence_state') {
+            const members = e.data.members ?? [];
+            const map = this.#members(e.topic);
+            const now = Date.now();
+            for (const m of members) {
+                const known = map.get(m.member);
+                if (known)
+                    known.lastSeen = now;
+                else
+                    map.set(m.member, { ...m, lastSeen: now });
+            }
+        }
+        else if (e.event === 'presence_diff') {
+            const leaves = e.data.leaves ?? [];
+            const map = this.#topics.get(e.topic);
+            if (!map)
+                return;
+            for (const member of leaves)
+                map.delete(member);
+            if (map.size === 0)
+                this.#topics.delete(e.topic);
+        }
+    }
+}

package/dist/provide.d.ts

@@ -0,0 +1,13 @@
+import type { ContextKey } from './context.js';
+/**
+ * App-scoped dependency registration. A provided value is seeded into every
+ * request's Ctx, so handlers and middleware read it with ctx.require(key)
+ * and get the same instance each time (singleton lifetime).
+ *
+ * Request-scoped values (set by middleware at runtime) may overwrite seeds.
+ */
+export interface ProvidedEntry {
+    readonly key: ContextKey<never>;
+    readonly value: unknown;
+}
+export declare function provide<K extends ContextKey<unknown>>(key: K, value: K extends ContextKey<infer V> ? V : never): ProvidedEntry;

package/dist/provide.js

@@ -0,0 +1,3 @@
+export function provide(key, value) {
+    return { key: key, value };
+}

package/dist/router.d.ts

@@ -0,0 +1,23 @@
+export interface RouteMatch<T> {
+    route: T;
+    params: Record<string, string>;
+}
+/** The path resolves to a registered endpoint but the method differs (405). */
+export interface MethodMismatch {
+    allow: string[];
+}
+export type LookupResult<T> = RouteMatch<T> | MethodMismatch | null;
+export interface MatcherEntry<T> {
+    method: string;
+    path: string;
+    route: T;
+}
+/**
+ * Radix-trie matcher built once at app creation: lookup cost is O(path depth),
+ * independent of route count. Static segments win over dynamic ones; ties on
+ * the same terminal node resolve by insertion order (first registration wins).
+ *
+ * A resolved terminal node with handlers but none for the requested method
+ * yields a MethodMismatch (405 + Allow); an unresolved path yields null (404).
+ */
+export declare function createMatcher<T>(entries: MatcherEntry<T>[]): (method: string, pathname: string) => LookupResult<T>;

package/dist/router.js

@@ -0,0 +1,60 @@
+function emptyNode() {
+    return { static: new Map(), handlers: new Map() };
+}
+function segments(pathname) {
+    const s = pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
+    return s.split('/').filter(Boolean);
+}
+/**
+ * Radix-trie matcher built once at app creation: lookup cost is O(path depth),
+ * independent of route count. Static segments win over dynamic ones; ties on
+ * the same terminal node resolve by insertion order (first registration wins).
+ *
+ * A resolved terminal node with handlers but none for the requested method
+ * yields a MethodMismatch (405 + Allow); an unresolved path yields null (404).
+ */
+export function createMatcher(entries) {
+    const root = emptyNode();
+    let order = 0;
+    for (const entry of entries) {
+        let node = root;
+        for (const seg of segments(entry.path)) {
+            if (seg.startsWith(':')) {
+                const name = seg.slice(1);
+                if (!node.param) {
+                    node.param = { name, node: emptyNode() };
+                }
+                node = node.param.node;
+            }
+            else {
+                let child = node.static.get(seg);
+                if (!child) {
+                    child = emptyNode();
+                    node.static.set(seg, child);
+                }
+                node = child;
+            }
+        }
+        if (!node.handlers.has(entry.method)) {
+            node.handlers.set(entry.method, { route: entry.route, order: order++ });
+        }
+    }
+    return (method, pathname) => {
+        let node = root;
+        const params = {};
+        for (const seg of segments(pathname)) {
+            const next = node.static.get(seg) ?? node.param?.node;
+            if (!next)
+                return null;
+            if (!node.static.has(seg))
+                params[node.param.name] = decodeURIComponent(seg);
+            node = next;
+        }
+        const hit = node.handlers.get(method);
+        if (hit)
+            return { route: hit.route, params };
+        if (node.handlers.size > 0)
+            return { allow: [...node.handlers.keys()] };
+        return null;
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,4 @@
+import { Value as TbValue } from '@sinclair/typebox/value';
+export declare const t: import("@sinclair/typebox").JavaScriptTypeBuilder;
+export declare const Value: typeof TbValue;
+export type { Static, TSchema } from '@sinclair/typebox';

package/dist/schema.js

@@ -0,0 +1,17 @@
+import { Type as TbType, FormatRegistry } from '@sinclair/typebox';
+import { Value as TbValue } from '@sinclair/typebox/value';
+export const t = TbType;
+export const Value = TbValue;
+/* Sensible default formats. Users can extend via FormatRegistry. */
+const formats = {
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    uuid: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
+    'date-time': /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/,
+    date: /^\d{4}-\d{2}-\d{2}$/,
+    uri: /^https?:\/\/[^\s]+$/,
+    ipv4: /^(?:\d{1,3}\.){3}\d{1,3}$/,
+};
+for (const [name, pattern] of Object.entries(formats)) {
+    if (!FormatRegistry.Has(name))
+        FormatRegistry.Set(name, (value) => pattern.test(value));
+}

package/dist/server.d.ts

@@ -0,0 +1,45 @@
+import { type RouteImpl } from './contract.js';
+import { type Middleware } from './middleware.js';
+import type { ProvidedEntry } from './provide.js';
+import { type ApiMeta } from './llms.js';
+export interface App {
+    routes: RouteImpl<any>[];
+    fetch(req: Request): Promise<Response>;
+    /**
+     * Same dispatch as fetch(), without constructing undici Responses for
+     * tzin-built replies (~19µs/request under load). Adapters that can write
+     * status/text/headers natively should prefer it.
+     */
+    dispatchRaw?(req: Request): Promise<RawReply>;
+}
+/**
+ * A reply that hasn't been wrapped in an undici Response yet. Either fully
+ * materialized (text + headers) or a pass-through Response (raw()/SSE).
+ */
+export interface RawReply {
+    status: number;
+    /** Pre-serialized body; absent means empty body (e.g. 202). */
+    text?: string;
+    headers?: Record<string, string>;
+    /** Streaming/raw escape hatch — adapters fall back to Response handling. */
+    response?: Response;
+}
+export interface AppOptions {
+    middleware?: Middleware[];
+    provides?: ProvidedEntry[];
+    /** Serve the MCP Streamable HTTP transport at POST /mcp. */
+    mcp?: boolean;
+    /** Serve /llms.txt and /llms-full.txt generated from contracts. */
+    llms?: boolean;
+    /** Serve the OpenAPI 3.1 document at /openapi.json, generated from contracts. */
+    openapi?: boolean;
+    meta?: ApiMeta;
+}
+export declare function fastResponseText(res: Response): string | undefined;
+export declare function fastResponseHeaders(res: Response): Record<string, string> | undefined;
+/**
+ * Adapters may attach a signal factory instead of a real signal so Ctx can
+ * stay lazy; real Request objects carry a plain signal.
+ */
+export declare function signalSource(req: Request): AbortSignal | (() => AbortSignal | undefined) | undefined;
+export declare function createApp(routes: RouteImpl<any>[], options?: AppOptions): App;