@tiaforge-ui/sinter 0.0.0-stage → 0.2.0

package/dist/runtime/store.js

@@ -0,0 +1,255 @@
+// 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;
+}
+/** One collator per locale: constructing one is costly in some engines. */
+const collators = new Map();
+const collator = (l = '') => collators.get(l) ?? (collators.set(l, new Intl.Collator(l || undefined, { numeric: true })), collators.get(l));
+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);
+    /** base items in arrival order, and each key's arrival number (ties in `order` keep arrival order) */
+    let base = new Map(), seq = new Map(), next = 0;
+    let single = null, total = null;
+    let layers = [], lastLayer = 0;
+    /**
+     * The base in display order, the locale it was sorted for, and the keys written since, with
+     * their value before the first write. Reads patch it instead of sorting
+     * again. Arrays handed out are never changed afterwards.
+     */
+    let sorted = null, sortedFor, touched = new Map();
+    /** Optimistic layers applied over the base: changed keys (null: removed), keys they add (arrival numbers), removals counted for `total`. */
+    let over = null;
+    /** what readers see; rebuilt on the first read after a change */
+    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 the base. */
+    const apply = (op) => {
+        if (!coll)
+            return void (single = merge(single, op));
+        const k = op.op == 'upsert' ? keyOf(op.item) : op.key, cur = base.get(k), v = merge(cur, op);
+        if (sorted && !touched.has(k))
+            touched.set(k, cur);
+        if (v) {
+            if (!cur)
+                seq.set(k, next++);
+            base.set(k, v);
+        }
+        else if (cur) {
+            base.delete(k);
+            seq.delete(k);
+        }
+    };
+    /** By `order` (none: all equal, so arrival order decides). */
+    const compare = (a, b) => {
+        if (!field)
+            return 0;
+        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' ? collator(sortedFor).compare(x, y) : +(x > y) - +(x < y));
+    };
+    /** A sorted copy of `list` without the `drop` items and with the `add` items (each with its arrival number). */
+    function patch(list, drop, add, arrival) {
+        const out = list.slice();
+        /** the first index whose item does not sort before `v` (with arrival number `n`, after its ties) */
+        const find = (v, n) => {
+            let lo = 0, hi = out.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1, c = compare(out[mid], v) || (n == null ? 0 : arrival(keyOf(out[mid])) - n);
+                c < 0 ? (lo = mid + 1) : (hi = mid);
+            }
+            return lo;
+        };
+        for (const v of drop) {
+            // among its ties, by identity; an item whose order field was changed in place is found by a scan
+            let i = find(v);
+            while (out[i] !== v && i < out.length && !compare(out[i], v))
+                i++;
+            out.splice(out[i] === v ? i : out.indexOf(v), 1);
+        }
+        for (const [v, n] of add)
+            out.splice(find(v, n), 0, v);
+        return out;
+    }
+    /** The base in display order. */
+    function baseList() {
+        const locale = o.locale?.();
+        if (sorted && locale === sortedFor && touched.size <= 64) {
+            if (touched.size) {
+                const drop = [], add = [];
+                for (const [k, old] of touched) {
+                    if (old)
+                        drop.push(old);
+                    const v = base.get(k);
+                    if (v)
+                        add.push([v, seq.get(k)]);
+                }
+                sorted = patch(sorted, drop, add, (k) => seq.get(k));
+            }
+        }
+        else {
+            sortedFor = locale;
+            // a stable sort of the Map's arrival order
+            sorted = [...base.values()].sort(compare);
+        }
+        touched = new Map();
+        return sorted;
+    }
+    /** Recomputes the layers' effect and `meta.total` after any change; marks `meta` if the total changed. */
+    function sync() {
+        over = null;
+        if (layers.length) {
+            const m = new Map(), add = new Map();
+            let removed = 0, n = next, s = single;
+            for (const l of layers)
+                for (const op of l.ops) {
+                    if (!coll) {
+                        s = merge(s, op);
+                        continue;
+                    }
+                    const k = op.op == 'upsert' ? keyOf(op.item) : op.key, cur = m.has(k) ? m.get(k) : base.get(k), v = merge(cur, op);
+                    if (v) {
+                        if (!cur)
+                            add.set(k, n++);
+                        m.set(k, v);
+                    }
+                    else {
+                        if (cur)
+                            removed++;
+                        m.set(k, null);
+                        add.delete(k);
+                    }
+                }
+            over = { m, add, removed, s };
+        }
+        const t = total == null ? null : Math.max(0, total - (over?.removed ?? 0));
+        if (meta.total !== t) {
+            meta.total = t;
+            r.onDirty('meta');
+        }
+    }
+    /** A data change: readers rebuild their view; `meta` too when the pending count changed. */
+    const changed = (pending) => {
+        view = null;
+        sync();
+        r.onDirty('data');
+        if (pending) {
+            meta.pending = layers.length;
+            r.onDirty('meta');
+        }
+    };
+    function visible() {
+        if (view)
+            return view;
+        if (!coll)
+            return (view = { l: [], get: () => undefined, s: over ? over.s : single });
+        let l = baseList(), get = (k) => base.get(k);
+        if (over) {
+            const { m, add } = over, drop = [], put = [], at = (k) => add.get(k) ?? seq.get(k);
+            for (const [k, v] of m) {
+                const b = base.get(k);
+                if (b)
+                    drop.push(b);
+                if (v)
+                    put.push([v, at(k)]);
+            }
+            l = patch(l, drop, put, at);
+            get = (k) => (m.has(k) ? m.get(k) ?? undefined : base.get(k));
+        }
+        // dev builds freeze what expressions see; the compiler refuses writes to resources (SN205)
+        return (view = { l: o.freeze ? Object.freeze(l.slice()) : l, get, s: null });
+    }
+    function write(op) {
+        if (r.recording)
+            return void r.recording.push(op);
+        journal?.push(op);
+        apply(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().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();
+                seq = new Map();
+                sorted = null;
+                touched = 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));
+                    seq.set(k, next++);
+                }
+            }
+            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: (hint) => r.loader?.refetch(hint) ?? 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)
+                apply(op);
+            changed();
+        },
+        addLayer(ops) {
+            layers.push({ id: ++lastLayer, ops });
+            changed(true);
+            return lastLayer;
+        },
+        dropLayer(id) {
+            const n = layers.length;
+            layers = layers.filter((l) => l.id != id);
+            if (n != layers.length)
+                changed(true);
+        },
+        /** the total changes `meta` only: bindings that read the items do not re-run */
+        setTotal(t) { total = t; sync(); },
+        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,209 @@
+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;
+    /** where `src` and the events' expressions are evaluated: the enclosing state's scope, or the page */
+    base;
+    constructor(app, def) {
+        this.app = app;
+        this.def = def;
+        this.base = app.scopeOf(def.scope ?? -1);
+        this.url = app.url(def.src, this.base);
+        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 : 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(this.base);
+        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(scope.$p);
+                    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(scope.$p);
+                        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,73 @@
+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>;
+    /** action functions for `data-sn-call` and `<sn-resource call>`, and namespaces as objects of functions */
+    actions?: 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;