@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,345 @@
+// @tiaforge-ui/sinter/testing: compile in memory with the real compiler, mount
+// into the test DOM, and drive requests, streams and time deterministically.
+// No test-runner imports: works with Vitest or anything else, on jsdom or happy-dom.
+import { compileParts } from '../compiler/compile.js';
+import { formatDiagnostic } from '../compiler/diagnostics.js';
+import { mount } from '../runtime/app.js';
+import { config } from '../runtime/config.js';
+import { $k } from '../runtime/security.js';
+import * as builtins from '../runtime/helpers.js';
+import cache from '../cache.js';
+import dev from '../dev.js';
+import optimistic from '../optimistic.js';
+import paginate from '../paginate.js';
+import persist from '../persist.js';
+import sse from '../sse.js';
+const FEATURES = { dev, sse, optimistic, paginate, persist, cache };
+function isResponseSpec(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const keys = Object.keys(v);
+    return typeof v.status === 'number' && keys.every((k) => k === 'status' || k === 'body' || k === 'headers');
+}
+function toResponse(v) {
+    if (v instanceof Response)
+        return v;
+    if (isResponseSpec(v)) {
+        const headers = new Headers(v.headers);
+        let body = null;
+        if (v.body !== undefined && v.body !== null) {
+            if (typeof v.body === 'string') {
+                body = v.body;
+                if (!headers.has('Content-Type'))
+                    headers.set('Content-Type', 'text/plain');
+            }
+            else {
+                body = JSON.stringify(v.body);
+                if (!headers.has('Content-Type'))
+                    headers.set('Content-Type', 'application/json');
+            }
+        }
+        return new Response(v.status === 204 ? null : body, { status: v.status, headers });
+    }
+    if (v === undefined || v === null)
+        return new Response(null, { status: 204 });
+    return new Response(JSON.stringify(v), { status: 200, headers: { 'Content-Type': 'application/json' } });
+}
+/** Request middleware answering `'METHOD /path'` routes. Responses are held until `settle()`. */
+export function mockRequests(routes) {
+    const calls = [];
+    const errors = [];
+    const queue = [];
+    const table = Object.entries(routes).map(([k, v]) => {
+        const [method, path] = k.trim().split(/\s+/, 2);
+        return { method: method.toUpperCase(), path, value: v, key: k };
+    });
+    const mw = (async (req) => {
+        const url = new URL(req.url);
+        const text = req.method === 'GET' || req.method === 'HEAD' ? '' : await req.clone().text();
+        const ct = req.headers.get('Content-Type') ?? '';
+        let body = null;
+        if (text) {
+            if (ct.includes('json')) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = text;
+                }
+            }
+            else if (ct.includes('multipart/form-data')) {
+                try {
+                    body = await req.clone().formData();
+                }
+                catch {
+                    body = text;
+                }
+            }
+            else
+                body = text;
+        }
+        const headers = {};
+        req.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
+        const call = { method: req.method, url: url.pathname + url.search, path: url.pathname, body, headers };
+        calls.push(call);
+        const route = table.find((r) => r.method === req.method && (r.path.includes('?') ? r.path === call.url : r.path === url.pathname));
+        if (!route) {
+            const err = new Error(`unmatched request: ${req.method} ${call.url}\nregistered routes:\n${table.map((r) => `  ${r.key}`).join('\n') || '  (none)'}`);
+            errors.push(err);
+            throw err;
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => reject(req.signal.reason ?? new DOMException('aborted', 'AbortError'));
+            if (req.signal.aborted)
+                return onAbort();
+            req.signal.addEventListener('abort', onAbort, { once: true });
+            queue.push(async () => {
+                req.signal.removeEventListener('abort', onAbort);
+                if (req.signal.aborted)
+                    return;
+                try {
+                    const v = typeof route.value === 'function' ? await route.value(call) : route.value;
+                    resolve(toResponse(structuredClone(v)));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    });
+    Object.defineProperties(mw, {
+        calls: { value: calls },
+        errors: { value: errors },
+        pending: { get: () => queue.length },
+        deliver: {
+            value: async () => {
+                const batch = queue.splice(0);
+                for (const fn of batch)
+                    await fn();
+                return batch.length;
+            },
+        },
+    });
+    return mw;
+}
+export function mockStream() {
+    let onEvent = null;
+    let onState = null;
+    let connected = false;
+    return {
+        get connected() { return connected; },
+        emit(name, payload) {
+            if (!connected)
+                throw new Error(`mockStream: cannot emit \`${name}\` while disconnected`);
+            // through JSON, as over the wire: the page never shares the test's object
+            onEvent?.(name, JSON.parse(JSON.stringify(payload ?? null)));
+        },
+        drop() {
+            if (!connected)
+                return;
+            connected = false;
+            onState?.('error');
+        },
+        transport() {
+            return {
+                connect(_url, ev, st) {
+                    onEvent = ev;
+                    onState = st;
+                    connected = true;
+                    queueMicrotask(() => { if (connected && onState === st)
+                        st('open'); });
+                },
+                close() { connected = false; onEvent = null; onState = null; },
+            };
+        },
+    };
+}
+let current = null;
+const realSetTimeout = globalThis.setTimeout.bind(globalThis);
+const tick = () => new Promise((r) => realSetTimeout(r, 0));
+const PAGE = '/test/page.html';
+export async function render(html, options = {}) {
+    if (current) {
+        current.destroy();
+        current = null;
+    }
+    // compile with the real compiler
+    const helpers = options.helpers ?? {};
+    const manifest = { module: null, names: [], namespaces: {} };
+    for (const [k, v] of Object.entries(helpers)) {
+        if (typeof v === 'function')
+            manifest.names.push(k);
+        else if (v && typeof v === 'object')
+            manifest.namespaces[k] = { module: k, members: Object.keys(v) };
+    }
+    const files = options.files ?? {};
+    const parts = compileParts(html, {
+        file: PAGE, root: '/test', dev: true, helpers: manifest, moduleSrc: 'about:blank',
+        readFile: (p) => {
+            const rel = p.startsWith('/test/') ? p.slice('/test/'.length) : p;
+            const hit = files[rel] ?? files[`./${rel}`] ?? files[p];
+            if (hit === undefined)
+                throw new Error(`no such file: ${p}`);
+            return hit;
+        },
+    });
+    const errors = parts.diagnostics.filter((d) => d.severity === 'error');
+    if (errors.length)
+        throw new Error(`sinter: build failed\n${errors.map(formatDiagnostic).join('\n')}`);
+    // function table, with helpers and namespace members in scope
+    const names = ['$k'];
+    const values = [$k];
+    for (const h of parts.helpers.builtin) {
+        names.push(h);
+        values.push(builtins[h]);
+    }
+    for (const h of parts.helpers.user) {
+        names.push(h);
+        values.push(helpers[h]);
+    }
+    for (const [ns, members] of Object.entries(parts.namespaces)) {
+        for (const m of members) {
+            names.push(`${ns}$${m}`);
+            values.push(helpers[ns][m]);
+        }
+    }
+    // eslint-disable-next-line no-new-func -- tests only; pages load a compiled module
+    const fns = new Function(...names, `"use strict"; return [\n${parts.fns.join(',\n')}\n];`)(...values);
+    // the page
+    const doc = document;
+    const inner = /<html[^>]*>([\s\S]*)<\/html>/i.exec(parts.html)?.[1] ?? parts.html;
+    doc.documentElement.innerHTML = inner.replace(/<script type="module" src="about:blank"><\/script>/, '');
+    // environment: fake clock, recorded navigation, in-memory storage
+    let now = options.now instanceof Date ? options.now.getTime() : options.now ?? Date.parse('2026-01-01T09:00:00Z');
+    let href = options.url ? new URL(options.url, 'http://localhost/').href : 'http://localhost/';
+    const timers = [];
+    let nextTimer = 1;
+    const navigations = [];
+    const store = options.storage ?? memoryStorage(), session = options.session ?? memoryStorage();
+    const winListeners = new Map();
+    const env = {
+        now: () => now,
+        setTimeout: (fn, ms, kind = 'timeout') => { const t = { id: nextTimer++, at: now + ms, fn, kind }; timers.push(t); return t.id; },
+        clearTimeout: (id) => { const i = timers.findIndex((t) => t.id === id); if (i >= 0)
+            timers.splice(i, 1); },
+        queueMicrotask: (fn) => queueMicrotask(fn),
+        navigate: (url) => { navigations.push(url); },
+        fetch: (req) => Promise.reject(new Error(`unexpected network request: ${req.method} ${req.url}; pass \`requests: mockRequests({...})\``)),
+        storage: () => store,
+        session: () => session,
+        href: () => href,
+        replaceState: (url) => { href = new URL(url, href).href; },
+        random: () => 0.5,
+        listen: (type, fn) => {
+            if (!winListeners.has(type))
+                winListeners.set(type, new Set());
+            winListeners.get(type).add(fn);
+            return () => winListeners.get(type)?.delete(fn);
+        },
+    };
+    config.env = env;
+    if (options.locale !== undefined) {
+        let locale = options.locale;
+        config.locale = { get: () => locale, set: (l) => { locale = l; } };
+    }
+    const requests = options.requests;
+    const app = mount(doc, {
+        ir: parts.ir, fns, env,
+        features: parts.features.map((f) => FEATURES[f]),
+        request: [...config.request, ...(requests ? [requests] : [])],
+        transport: (url) => {
+            const path = new URL(url, href).pathname;
+            const stream = options.streams?.[url] ?? options.streams?.[path];
+            if (stream)
+                return stream.transport();
+            // a transport from configure() (e.g. a WebSocket or SignalR adapter over a fake connection)
+            const configured = config.transport?.(url);
+            if (configured)
+                return configured;
+            throw new Error(`no mock stream for ${url}; pass \`streams: { '${url}': mockStream() }\``);
+        },
+    });
+    current = app;
+    const check = () => {
+        if (requests?.errors.length)
+            throw requests.errors[0];
+    };
+    const flush = async () => {
+        for (let i = 0; i < 50; i++) {
+            for (let j = 0; j < 10; j++)
+                await Promise.resolve();
+            if (!app.isDirty)
+                break;
+            app.flush();
+        }
+        check();
+    };
+    const runDue = (until, kinds) => {
+        for (;;) {
+            const due = timers.filter((t) => t.at <= until && (!kinds || kinds.has(t.kind))).sort((a, b) => a.at - b.at || a.id - b.id)[0];
+            if (!due)
+                return;
+            timers.splice(timers.indexOf(due), 1);
+            if (due.at > now)
+                now = due.at;
+            due.fn();
+        }
+    };
+    const settle = async () => {
+        for (let round = 0; round < 1000; round++) {
+            await flush();
+            await tick();
+            if (requests && requests.pending) {
+                await requests.deliver();
+                continue;
+            }
+            const debounce = timers.filter((t) => t.kind === 'debounce').sort((a, b) => a.at - b.at)[0];
+            if (debounce) {
+                runDue(debounce.at, new Set(['debounce']));
+                continue;
+            }
+            if (app.req.inflight > 0 || app.busy > 0 || app.isDirty)
+                continue;
+            await flush();
+            return;
+        }
+        throw new Error('settle(): requests did not finish after 1000 rounds');
+    };
+    const advance = async (ms) => {
+        const until = now + ms;
+        for (;;) {
+            await flush();
+            const before = timers.length;
+            runDue(until);
+            if (timers.length === before || !timers.some((t) => t.at <= until))
+                break;
+        }
+        now = until;
+        await flush();
+    };
+    await flush();
+    return {
+        root: doc.body, app, flush, settle, advance, navigations,
+        url: () => href,
+        window: async (type) => {
+            const e = new Event(type);
+            if (type === 'pageshow')
+                Object.defineProperty(e, 'persisted', { value: true });
+            for (const fn of winListeners.get(type) ?? [])
+                fn(e);
+            await flush();
+        },
+    };
+}
+/** An in-memory `Storage`, e.g. to share `session` between two render() calls. */
+export function memoryStorage() {
+    const m = new Map();
+    return {
+        get length() { return m.size; },
+        key: (i) => [...m.keys()][i] ?? null,
+        getItem: (k) => m.get(k) ?? null,
+        setItem: (k, v) => { m.set(k, String(v)); },
+        removeItem: (k) => { m.delete(k); },
+        clear: () => m.clear(),
+    };
+}

package/dist/vite.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from 'vite';
+import { type ProjectOptions } from './project.js';
+export interface SinterOptions extends ProjectOptions {
+    /** run `sinter check` at the end of `vite build` and fail it on type errors (needs TypeScript) */
+    typecheck?: boolean;
+}
+export default function sinter(options?: SinterOptions): Plugin & {
+    api: {
+        options: SinterOptions;
+    };
+};

package/dist/vite.js

@@ -0,0 +1,94 @@
+// Vite adapter: a thin wrapper around compile(). Every HTML entry is compiled
+// in transformIndexHtml; its page module is served as a virtual module.
+import { relative, sep } from 'node:path';
+import { compile, formatDiagnostic } from './compiler/index.js';
+import { project } from './project.js';
+const PREFIX = '/@sinter/';
+export default function sinter(options = {}) {
+    let root = process.cwd();
+    let dev = false;
+    let server = null;
+    const modules = new Map();
+    const watched = new Set();
+    const units = new Map();
+    const watch = (file) => {
+        if (watched.has(file))
+            return;
+        watched.add(file);
+        server?.watcher.add(file);
+    };
+    return {
+        name: 'sinter',
+        enforce: 'pre',
+        api: { options },
+        configResolved(config) {
+            root = config.root;
+            dev = config.command === 'serve';
+        },
+        configureServer(s) {
+            server = s;
+            // an HTML, partial or helpers change triggers a full reload in v0.1
+            s.watcher.on('change', (file) => {
+                if (watched.has(file))
+                    s.ws.send({ type: 'full-reload' });
+            });
+        },
+        resolveId(id) {
+            if (id.startsWith(PREFIX))
+                return '\0' + id;
+            return null;
+        },
+        load(id) {
+            if (!id.startsWith('\0' + PREFIX))
+                return null;
+            const code = modules.get(id.slice(1));
+            if (code === undefined)
+                throw new Error(`sinter: page module ${id.slice(1)} requested before its HTML was compiled`);
+            return code;
+        },
+        async buildEnd(error) {
+            if (error || !options.typecheck || dev || !units.size)
+                return;
+            const { check } = await import('./check/index.js');
+            const p = project(root, options);
+            const r = check({ root, units: [...units.values()], helpers: p.helpers, types: p.types, openapi: p.openapi });
+            units.clear();
+            if (r.diagnostics.length)
+                this.error(`sinter check: ${r.diagnostics.length} type error(s)\n${r.diagnostics.map(formatDiagnostic).join('\n')}`);
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            handler(html, ctx) {
+                const file = ctx.filename;
+                const rel = relative(root, file).split(sep).join('/');
+                const moduleSrc = `${PREFIX}${rel}.js`;
+                const p = project(root, options);
+                if (p.diagnostics.length)
+                    throw new Error(`sinter: ${p.diagnostics.map(formatDiagnostic).join('\n')}`);
+                const out = compile(html, {
+                    file, root, dev, helpers: p.helpers, moduleSrc, config: p.config, readFile: p.readFile,
+                    check: !!options.typecheck && !dev, openapi: p.openapi,
+                });
+                if (out.check)
+                    units.set(file, out.check);
+                for (const f of out.files)
+                    watch(f);
+                if (p.helpersFile)
+                    watch(p.helpersFile);
+                const errors = out.diagnostics.filter((d) => d.severity === 'error');
+                for (const d of out.diagnostics)
+                    if (d.severity === 'warning')
+                        console.warn(formatDiagnostic(d));
+                if (errors.length) {
+                    const err = new Error(`sinter: ${errors.length} error(s)\n${errors.map(formatDiagnostic).join('\n')}`);
+                    err.id = errors[0].file;
+                    err.loc = { file: errors[0].file, line: errors[0].line, column: errors[0].col };
+                    throw err;
+                }
+                modules.set(moduleSrc, out.module);
+                server?.moduleGraph.getModuleById('\0' + moduleSrc) && server.moduleGraph.invalidateModule(server.moduleGraph.getModuleById('\0' + moduleSrc));
+                return out.html;
+            },
+        },
+    };
+}

package/dist/ws.d.ts

@@ -0,0 +1,18 @@
+import type { Transport } from './runtime/app.js';
+export interface WebSocketTransportOptions {
+    /** subprotocols for the WebSocket constructor */
+    protocols?: string | string[];
+    /**
+     * Turns one text message into `[event name, payload]`, or `null` to skip it. Default: the
+     * message is JSON `{"event": "<name>", "data": <payload>}`.
+     */
+    decode?: (message: string) => [name: string, payload: unknown] | null;
+}
+/** The default message format: `{"event": "contact_updated", "data": {…}}`. */
+export declare function decodeMessage(message: string): [string, unknown] | null;
+/**
+ * One WebSocket per stream. Delivers the mapped event names and those islands listen to later;
+ * other messages are dropped, as EventSource drops events nobody listens for. A close, clean or
+ * not, reports `error`: `<sn-sync>` then runs the session probe, backs off and reconnects.
+ */
+export declare function webSocketTransport(options?: WebSocketTransportOptions): Transport;

package/dist/ws.js

@@ -0,0 +1,57 @@
+// WebSocket transport for <sn-sync>. Opt in from the config module:
+//   configure({ transport: (url) => url.startsWith('/ws/') ? webSocketTransport() : undefined })
+// The stream URL stays an http(s) URL in the HTML (the compiler's URL rules apply); the
+// transport opens it as ws(s). Server to client only: actions still go over HTTP.
+import { config } from './runtime/config.js';
+/** The default message format: `{"event": "contact_updated", "data": {…}}`. */
+export function decodeMessage(message) {
+    let m;
+    try {
+        m = JSON.parse(message);
+    }
+    catch {
+        return null;
+    }
+    if (!m || typeof m !== 'object' || typeof m.event !== 'string')
+        return null;
+    return [m.event, m.data ?? null];
+}
+/**
+ * One WebSocket per stream. Delivers the mapped event names and those islands listen to later;
+ * other messages are dropped, as EventSource drops events nobody listens for. A close, clean or
+ * not, reports `error`: `<sn-sync>` then runs the session probe, backs off and reconnects.
+ */
+export function webSocketTransport(options = {}) {
+    const decode = options.decode ?? decodeMessage;
+    let ws = null;
+    const names = new Set();
+    return {
+        connect(url, onEvent, onState, initial) {
+            const u = new URL(url, config.env.href());
+            u.protocol = u.protocol === 'http:' ? 'ws:' : u.protocol === 'https:' ? 'wss:' : u.protocol;
+            names.clear();
+            for (const n of initial)
+                names.add(n);
+            const s = ws = new WebSocket(u.href, options.protocols);
+            s.onopen = () => { if (ws === s)
+                onState('open'); };
+            s.onclose = () => { if (ws === s) {
+                ws = null;
+                onState('error');
+            } };
+            s.onmessage = (e) => {
+                if (ws !== s || typeof e.data !== 'string')
+                    return;
+                const m = decode(e.data);
+                if (m && names.has(m[0]))
+                    onEvent(m[0], m[1]);
+            };
+        },
+        listen(name) { names.add(name); },
+        close() {
+            const s = ws;
+            ws = null; // handlers check this first: nothing is reported after close()
+            s?.close();
+        },
+    };
+}