@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/runtime/store.js

@@ -0,0 +1,142 @@
+// The store: one keyed (or single-object) cache per resource. It knows nothing
+// about the DOM, fetch or SSE. Each resource holds a base (what the server last
+// confirmed) and ordered optimistic layers; readers see base + layers.
+import { BAD_KEY } from './security.js';
+/** Copies own enumerable fields, dropping keys that could pollute prototypes. */
+export function clean(obj) {
+    if (!obj || typeof obj != 'object' || Array.isArray(obj))
+        return obj;
+    const out = {};
+    for (const k of Object.keys(obj))
+        if (!BAD_KEY.test(k))
+            out[k] = obj[k];
+    return out;
+}
+export function createResource(name, o) {
+    const meta = { loading: false, error: null, loadedAt: null, pending: 0, total: null };
+    const coll = !!o.key, field = o.order?.replace(/^-/, ''), dir = o.order?.[0] == '-' ? -1 : 1;
+    const subs = new Set();
+    const prep = (x) => (o.prep ? o.prep(x) : x);
+    let base = new Map(), single = null, total = null;
+    let layers = [], lastLayer = 0;
+    let view = null;
+    let journal = null, loads = 0;
+    const keyOf = (x) => typeof x == 'string' ? x : (o.key ?? []).map((f) => {
+        if (x[f] === undefined)
+            o.warn?.(14, name, f);
+        return x[f];
+    }).join('\x1f');
+    const merge = (cur, op) => op.op == 'upsert' ? prep(op.item)
+        : op.op == 'remove' ? null
+            : cur && prep({ ...cur, ...clean(op.fields) });
+    /** Applies one op to a keyed map; counts removals of present items. */
+    const applyTo = (m, op, removed) => {
+        const k = op.op == 'upsert' ? keyOf(op.item) : op.key, v = merge(m.get(k), op);
+        if (v)
+            m.set(k, v);
+        else if (m.delete(k) && removed)
+            removed.n++;
+    };
+    const changed = (what = 'data') => {
+        view = null;
+        r.onDirty('data');
+        if (what == 'meta')
+            r.onDirty('meta');
+    };
+    function visible() {
+        if (view)
+            return view;
+        let t = total, m = base, s = single;
+        const removed = { n: 0 };
+        for (const l of layers)
+            for (const op of l.ops)
+                coll ? (m == base && (m = new Map(base)), applyTo(m, op, removed)) : (s = merge(s, op));
+        if (t != null)
+            t = Math.max(0, t - removed.n);
+        const l = [...m.values()];
+        if (field) {
+            const c = new Intl.Collator(o.locale?.(), { numeric: true });
+            l.sort((a, b) => {
+                const x = a[field], y = b[field];
+                if (x == null || y == null)
+                    return +(x == null) - +(y == null);
+                return dir * (typeof x == 'string' && typeof y == 'string' ? c.compare(x, y) : +(x > y) - +(x < y));
+            });
+        }
+        view = { l: Object.freeze(l), m, s };
+        if (meta.total !== t) {
+            meta.total = t;
+            r.onDirty('meta');
+        }
+        return view;
+    }
+    function write(op) {
+        if (r.recording)
+            return void r.recording.push(op);
+        journal?.push(op);
+        coll ? applyTo(base, op) : (single = merge(single, op));
+        changed();
+        for (const f of subs)
+            f({ resource: name, ...op });
+    }
+    const r = {
+        name, meta, key: o.key, isCollection: coll, keyOf, recording: null, loader: null, onDirty() { },
+        get: (k) => (coll ? visible().m.get(keyOf(k)) : visible().s ?? undefined),
+        has: (k) => r.get(k) !== undefined,
+        all: () => visible().l,
+        value: () => (coll ? visible().l : visible().s),
+        replace(items) {
+            if (coll) {
+                base = new Map();
+                for (const x of Array.isArray(items) ? items : []) {
+                    const k = keyOf(x);
+                    if (base.has(k))
+                        o.warn?.(13, name, k);
+                    base.delete(k);
+                    base.set(k, prep(x));
+                }
+            }
+            else
+                single = items == null ? null : prep(items);
+            changed();
+            for (const f of subs)
+                f({ resource: name, op: 'refetch' });
+        },
+        upsert: (item) => write({ op: 'upsert', item }),
+        patch: (k, fields) => write({ op: 'patch', key: keyOf(k), fields }),
+        remove: (k) => write({ op: 'remove', key: keyOf(k) }),
+        refetch: () => r.loader?.refetch() ?? Promise.resolve(),
+        subscribe: (fn) => (subs.add(fn), () => subs.delete(fn)),
+        startLoad() {
+            loads++;
+            journal ??= [];
+            return journal.length;
+        },
+        endLoad(mark, loaded) {
+            const ops = journal.slice(mark);
+            if (--loads == 0)
+                journal = null;
+            if (!loaded || !ops.length)
+                return;
+            for (const op of ops)
+                coll ? applyTo(base, op) : (single = merge(single, op));
+            changed();
+        },
+        addLayer(ops) {
+            layers.push({ id: ++lastLayer, ops });
+            meta.pending = layers.length;
+            changed('meta');
+            return lastLayer;
+        },
+        dropLayer(id) {
+            const n = layers.length;
+            layers = layers.filter((l) => l.id != id);
+            meta.pending = layers.length;
+            if (n != layers.length)
+                changed('meta');
+        },
+        setTotal(t) { total = t; changed(); },
+        base: () => ({ items: coll ? [...base.values()] : single, total }),
+    };
+    return r;
+}

package/dist/sse.d.ts

@@ -0,0 +1,7 @@
+import type { Feature, Transport } from './runtime/app.js';
+/** JSON payloads are parsed; anything else is delivered as the raw string. */
+export declare const parsePayload: (data: string) => unknown;
+/** The default transport: one EventSource. */
+export declare function eventSourceTransport(): Transport;
+declare const sse: Feature;
+export default sse;

package/dist/sse.js

@@ -0,0 +1,206 @@
+import { config, SinterError } from './runtime/config.js';
+import { clean } from './runtime/store.js';
+const MIN_BACKOFF = 1000;
+const MAX_BACKOFF = 30_000;
+/** JSON payloads are parsed; anything else is delivered as the raw string. */
+export const parsePayload = (data) => { try {
+    return JSON.parse(data);
+}
+catch {
+    return data;
+} };
+/** The default transport: one EventSource. */
+export function eventSourceTransport() {
+    let es = null;
+    let deliver = null;
+    const names = new Set();
+    const add = (name) => {
+        if (!es || names.has(name))
+            return;
+        names.add(name);
+        es.addEventListener(name, (e) => deliver?.(name, parsePayload(e.data)));
+    };
+    return {
+        connect(url, onEvent, onState, initial) {
+            deliver = onEvent;
+            es = new EventSource(url, { withCredentials: true });
+            es.onopen = () => onState('open');
+            es.onerror = () => onState('error');
+            names.clear();
+            for (const n of initial)
+                add(n);
+        },
+        listen: add,
+        close() { es?.close(); es = null; },
+    };
+}
+class Connection {
+    app;
+    def;
+    t = null;
+    backoff = MIN_BACKOFF;
+    timer = null;
+    closed = false;
+    hidden = false;
+    everOpen = false;
+    url;
+    fed;
+    constructor(app, def) {
+        this.app = app;
+        this.def = def;
+        this.url = app.url(def.src, app.page);
+        this.fed = [...new Set(def.events.map((e) => e.resource))];
+    }
+    start() {
+        const env = this.app.env;
+        this.app.addCleanup(env.listen('pagehide', () => { this.hidden = true; this.stop(); }));
+        this.app.addCleanup(env.listen('pageshow', () => {
+            if (!this.hidden)
+                return;
+            this.hidden = false;
+            this.closed = false;
+            void this.probe();
+        }));
+        this.app.onListen.push((name) => this.t?.listen?.(name));
+        this.app.addCleanup(() => { this.closed = true; this.stop(); });
+        this.open();
+    }
+    names() {
+        return [...new Set(this.def.events.map((e) => e.name))];
+    }
+    open() {
+        if (this.closed && !this.hidden)
+            return;
+        const custom = this.app.transport(this.url) ?? config.transport?.(this.url);
+        const t = custom ?? eventSourceTransport();
+        this.t = t;
+        const reconnect = this.everOpen;
+        t.connect(this.url, (name, data) => this.event(name, data), (state) => {
+            if (this.t !== t)
+                return;
+            if (state === 'open') {
+                this.backoff = MIN_BACKOFF;
+                this.everOpen = true;
+                if (!custom)
+                    this.app.streamOpened?.(this.url);
+                // events sent while disconnected are lost: refetch everything this stream feeds
+                if (reconnect)
+                    for (const name of this.fed)
+                        void this.app.resource(name).refetch();
+            }
+            else {
+                t.close();
+                this.t = null;
+                void this.probe();
+            }
+        }, this.names());
+    }
+    stop() {
+        this.t?.close();
+        this.t = null;
+        if (this.timer != null) {
+            this.app.env.clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /** The session probe gates every reconnect: 2xx reconnects, 401 leads to login, an outage backs off. */
+    async probe() {
+        if (this.closed || this.hidden)
+            return;
+        if (!config.sessionProbe) {
+            this.wait(() => this.open());
+            return;
+        }
+        let status;
+        try {
+            status = (await this.app.req.raw(config.sessionProbe)).status;
+        }
+        catch (e) {
+            status = e instanceof SinterError ? e.status : 0;
+        }
+        if (this.closed || this.hidden)
+            return;
+        if (status >= 200 && status < 300)
+            this.open();
+        else if (status !== 401)
+            this.wait(() => void this.probe());
+        // 401: the request layer's onUnauthorized handles login
+    }
+    wait(fn) {
+        const delay = Math.round(this.backoff * (0.75 + this.app.env.random() * 0.5));
+        this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF);
+        this.timer = this.app.env.setTimeout(() => { this.timer = null; fn(); }, delay, 'backoff');
+    }
+    event(name, payload) {
+        for (const def of this.def.events)
+            if (def.name === name)
+                this.apply(def, payload);
+        this.app.serverEvent(name, payload);
+    }
+    apply(def, payload) {
+        const app = this.app;
+        const scope = Object.create(app.page);
+        scope.$p = payload && typeof payload === 'object' ? payload : {};
+        const r = app.resource(def.resource);
+        try {
+            if (def.when != null && !app.fns[def.when](scope))
+                return;
+            const paginated = !!app.ir.resources.find((x) => x.name === def.resource)?.paginate;
+            switch (def.op) {
+                case 'refetch':
+                    void r.refetch();
+                    return;
+                case 'upsert': {
+                    const item = def.item != null ? app.fns[def.item](scope) : payload;
+                    if (item == null || typeof item !== 'object') {
+                        if (def.fallback === 'refetch')
+                            void r.refetch();
+                        return;
+                    }
+                    if (paginated && !r.has(item)) {
+                        void r.refetch();
+                        return;
+                    }
+                    r.upsert(clean(item));
+                    return;
+                }
+                case 'patch': {
+                    if (r.isCollection && !this.hasKey(r.key, scope.$p, def))
+                        return;
+                    const key = r.keyOf(scope.$p);
+                    if (r.isCollection && !r.has(key))
+                        return;
+                    r.patch(key, clean(app.fns[def.set](scope)));
+                    return;
+                }
+                case 'remove': {
+                    if (r.isCollection && !this.hasKey(r.key, scope.$p, def))
+                        return;
+                    const key = r.keyOf(scope.$p);
+                    r.remove(key);
+                    return;
+                }
+            }
+        }
+        catch (e) {
+            app.warn(`event \`${def.name}\` could not be applied: ${e.message}`, payload);
+        }
+    }
+    hasKey(fields, payload, def) {
+        const missing = fields.filter((f) => payload[f] === undefined);
+        if (missing.length)
+            this.app.warn(`event \`${def.name}\` payload is missing key field(s) ${missing.join(', ')} for \`${def.resource}\``, payload);
+        return missing.length === 0;
+    }
+}
+const sse = {
+    name: 'sse',
+    install(app) {
+        // connect after mount has created resources and loaders
+        app.env.queueMicrotask(() => {
+            for (const def of app.ir.syncs)
+                new Connection(app, def).start();
+        });
+    },
+};
+export default sse;

package/dist/testing/index.d.ts

@@ -0,0 +1,71 @@
+import { type App, type Transport } from '../runtime/app.js';
+import { type Middleware } from '../runtime/config.js';
+export type RouteResponse = ((call: RecordedCall) => unknown) | {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+} | object | string | number | boolean | null;
+export interface RecordedCall {
+    method: string;
+    url: string;
+    path: string;
+    body: unknown;
+    headers: Record<string, string>;
+}
+export interface MockRequests extends Middleware {
+    /** every request that reached the mock, in order */
+    readonly calls: RecordedCall[];
+    /** requests waiting for settle() */
+    readonly pending: number;
+    /** answers every waiting request; returns how many */
+    deliver(): Promise<number>;
+    /** errors for unmatched requests; render() rethrows them */
+    readonly errors: Error[];
+}
+/** Request middleware answering `'METHOD /path'` routes. Responses are held until `settle()`. */
+export declare function mockRequests(routes: Record<string, RouteResponse>): MockRequests;
+export interface MockStream {
+    readonly connected: boolean;
+    /** delivers a server event with a JSON payload */
+    emit(name: string, payload?: unknown): void;
+    /** drops the connection, as a network error would */
+    drop(): void;
+    /** @internal */
+    transport(): Transport;
+}
+export declare function mockStream(): MockStream;
+export interface RenderOptions {
+    requests?: MockRequests;
+    streams?: Record<string, MockStream>;
+    /** page URL, for `$url` (default `http://localhost/`) */
+    url?: string;
+    locale?: string;
+    /** start time of sinter's clock */
+    now?: number | Date;
+    /** helper functions, and namespaces as objects of functions */
+    helpers?: Record<string, unknown>;
+    /** partials for `<sn-include>`, by path relative to the page */
+    files?: Record<string, string>;
+    /** localStorage and sessionStorage (default: empty ones); pass the previous page's to test what carries over */
+    storage?: Storage;
+    session?: Storage;
+}
+export interface Rendered {
+    root: HTMLElement;
+    app: App;
+    /** runs the scheduler until no binding is dirty */
+    flush(): Promise<void>;
+    /** flushes until every request, queue and debounce has finished */
+    settle(): Promise<void>;
+    /** moves sinter's clock: debounce, backoff, `$now` */
+    advance(ms: number): Promise<void>;
+    /** URLs sinter tried to navigate to */
+    navigations: string[];
+    /** current page URL (after `$url` writes) */
+    url(): string;
+    /** dispatches pagehide/pageshow/popstate to sinter */
+    window(type: 'pagehide' | 'pageshow' | 'popstate'): Promise<void>;
+}
+export declare function render(html: string, options?: RenderOptions): Promise<Rendered>;
+/** An in-memory `Storage`, e.g. to share `session` between two render() calls. */
+export declare function memoryStorage(): Storage;