@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/paginate.js

@@ -0,0 +1,184 @@
+class PagerImpl {
+    loader;
+    move;
+    cfg;
+    constructor(loader) {
+        this.loader = loader;
+        this.cfg = loader.def.paginate;
+        this.move = this.first();
+        const m = loader.res.meta;
+        if (this.cfg.mode === 'offset')
+            m.page = 1;
+        Object.assign(m, { pages: null, from: null, to: null, hasPrev: false, hasNext: false });
+    }
+    base(dir, size = this.cfg.size) {
+        const p = { [this.cfg.sizeParam]: String(size) };
+        if (dir)
+            p[this.cfg.directionParam] = dir;
+        return p;
+    }
+    first() {
+        if (this.cfg.mode === 'offset')
+            return { dir: 'page', page: 1, params: { [this.cfg.pageParam]: '1', ...this.base(null) }, from: null, to: null };
+        return { dir: 'first', page: 1, params: this.base('first'), from: null, to: null };
+    }
+    reset() {
+        this.move = this.first();
+    }
+    current() {
+        if (this.cfg.mode === 'append' && this.move.dir !== 'first') {
+            // refetch reloads everything loaded so far in one request
+            const n = Math.max(this.cfg.size, this.loader.res.all().length);
+            return { dir: 'all', page: 1, params: this.base('first', n), from: null, to: null };
+        }
+        return this.move;
+    }
+    params(move) {
+        return move.params;
+    }
+    appends(move) {
+        return this.cfg.mode === 'append' && move.dir === 'next';
+    }
+    go(target) {
+        const meta = this.loader.res.meta;
+        const items = this.loader.res.all();
+        const cursor = (item) => {
+            if (this.cfg.cursor == null || item === undefined)
+                return {};
+            const scope = Object.create(this.loader.app.page);
+            scope.$p = item;
+            const c = this.loader.app.fns[this.cfg.cursor](scope);
+            const out = {};
+            for (const [k, v] of Object.entries(c ?? {}))
+                out[k] = v == null ? '' : String(v);
+            return out;
+        };
+        let move;
+        const from = meta.from ?? null, to = meta.to ?? null;
+        if (this.cfg.mode === 'offset') {
+            const page = meta.page ?? 1;
+            let n;
+            if (typeof target === 'number')
+                n = target;
+            else if (target === 'first')
+                n = 1;
+            else if (target === 'prev')
+                n = page - 1;
+            else if (target === 'next')
+                n = page + 1;
+            else if (target === 'last') {
+                if (meta.pages == null) {
+                    this.loader.app.warn(`page('${this.loader.def.name}', 'last') needs a known total`);
+                    return;
+                }
+                n = meta.pages;
+            }
+            else
+                return;
+            n = Math.max(1, Math.floor(n));
+            move = { dir: 'page', page: n, params: { [this.cfg.pageParam]: String(n), ...this.base(null) }, from, to };
+        }
+        else {
+            if (typeof target === 'number') {
+                this.loader.app.warn('keyset pagination cannot jump to a page number; use paginate="offset"');
+                return;
+            }
+            if (this.cfg.mode === 'append' && target !== 'next')
+                return;
+            const dir = target;
+            const c = dir === 'next' ? cursor(items[items.length - 1]) : dir === 'prev' ? cursor(items[0]) : {};
+            move = { dir, page: 1, params: { ...c, ...this.base(dir) }, from, to };
+        }
+        void this.loader.load(move);
+    }
+    received(items, total, mv) {
+        const move = mv;
+        if (move.dir !== 'all')
+            this.move = move;
+        const meta = this.loader.res.meta;
+        const n = items.length;
+        const size = this.cfg.size;
+        const full = n >= size;
+        const pages = total != null ? Math.max(1, Math.ceil(total / size)) : null;
+        let from = null, to = null, hasPrev = false, hasNext = false;
+        switch (move.dir) {
+            case 'page':
+                from = n ? (move.page - 1) * size + 1 : 0;
+                to = n ? from + n - 1 : 0;
+                hasPrev = move.page > 1;
+                hasNext = pages != null ? move.page < pages : full;
+                meta.page = move.page;
+                break;
+            case 'first':
+                from = n ? 1 : 0;
+                to = n;
+                hasPrev = false;
+                hasNext = full;
+                break;
+            case 'all':
+                from = n ? 1 : 0;
+                to = n;
+                hasPrev = false;
+                hasNext = meta.hasNext ?? full;
+                break;
+            case 'next':
+                if (this.cfg.mode === 'append') {
+                    const all = this.loader.res.all().length;
+                    from = all ? 1 : 0;
+                    to = all;
+                    hasPrev = false;
+                    hasNext = full;
+                    break;
+                }
+                from = move.to != null ? move.to + 1 : null;
+                to = from != null ? from + n - 1 : null;
+                hasPrev = true;
+                hasNext = full;
+                break;
+            case 'prev':
+                hasNext = true;
+                if (!full) {
+                    from = n ? 1 : 0;
+                    to = n;
+                    hasPrev = false;
+                    break;
+                }
+                to = move.from != null ? move.from - 1 : null;
+                from = to != null ? to - n + 1 : null;
+                hasPrev = from == null || from > 1;
+                break;
+            case 'last':
+                hasNext = false;
+                if (total != null) {
+                    to = total;
+                    from = total - n + 1;
+                    hasPrev = from > 1;
+                }
+                else
+                    hasPrev = full;
+                break;
+        }
+        Object.assign(meta, { pages, from, to, hasPrev, hasNext });
+        this.loader.res.onDirty('meta');
+    }
+}
+const paginate = {
+    name: 'paginate',
+    install(app) {
+        const pagers = new Map();
+        app.ext.paginate = {
+            pager(loader) {
+                const p = new PagerImpl(loader);
+                pagers.set(loader.def.name, p);
+                return p;
+            },
+            page(name, target) {
+                const p = pagers.get(name);
+                if (!p)
+                    throw new Error(`sinter: resource \`${name}\` is not paginated`);
+                p.go(target);
+            },
+        };
+    },
+};
+export default paginate;

package/dist/persist.d.ts

@@ -0,0 +1,3 @@
+import type { Feature } from './runtime/app.js';
+declare const persist: Feature;
+export default persist;

package/dist/persist.js

@@ -0,0 +1,55 @@
+const PREFIX = 'sn:';
+const persist = {
+    name: 'persist',
+    install(app) {
+        const read = (key) => {
+            try {
+                const v = app.env.storage()?.getItem(PREFIX + key);
+                return v == null ? undefined : JSON.parse(v);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const write = (key, value) => {
+            try {
+                app.env.storage()?.setItem(PREFIX + key, JSON.stringify(value));
+            }
+            catch { /* ignored */ }
+        };
+        app.ext.persist = {
+            model(rb, set) {
+                const key = rb.b.p;
+                const v = read(key);
+                if (v !== undefined)
+                    set(v);
+                const paths = (rb.b.w ?? []).map((w) => w.split('.').map((s) => (s[0] === '{' ? '*' : s)));
+                app.afterFlush.push((dirty) => {
+                    if (!dirty.some((d) => paths.some((p) => overlaps(p, d))))
+                        return;
+                    try {
+                        write(key, app.fns[rb.b.f](rb.s));
+                    }
+                    catch { /* unreadable: skip */ }
+                });
+            },
+            state(key, obj) {
+                const v = read(key);
+                if (!v || typeof v !== 'object')
+                    return;
+                for (const k of Object.keys(obj))
+                    if (Object.hasOwn(v, k))
+                        obj[k] = v[k];
+            },
+            saveState: write,
+        };
+    },
+};
+function overlaps(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i] && a[i] !== '*' && b[i] !== '*')
+            return false;
+    return true;
+}
+export default persist;

package/dist/project.d.ts

@@ -0,0 +1,36 @@
+import { type Diagnostic, type HelperManifest } from './compiler/index.js';
+import type { OpenApiSpec } from './compiler/openapi.js';
+export interface ProjectOptions {
+    /** helpers module, relative to the root (default `src/sinter.helpers.js`, or `.ts`) */
+    helpers?: string;
+    /** app configuration module imported before mount (default `src/sinter.config.js`, or `.ts`) */
+    config?: string;
+    /** module whose exported types `type="…"` on `<sn-resource>` may name (default `src/sinter.types.ts`, `.d.ts` or `.js`) */
+    types?: string;
+    /** OpenAPI specs (JSON or YAML, inside the root) that resources without `type` are matched against */
+    openapi?: string | string[];
+}
+export interface Project {
+    root: string;
+    helpers: HelperManifest;
+    /** absolute path of the helpers module, or null */
+    helpersFile: string | null;
+    /** root-relative URL of the config module (`/src/sinter.config.js`), or null */
+    config: string | null;
+    /** absolute path of the types module, or null */
+    types: string | null;
+    /** reads a file only if it resolves inside the root, symlinks included */
+    readFile: (path: string) => string;
+    openapi: OpenApiSpec[];
+    /** problems loading the specs (SN307) */
+    diagnostics: Diagnostic[];
+}
+export declare function project(root: string, options?: ProjectOptions): Project;
+/**
+ * The pages (HTML entries) and sinter plugin options from the root's Vite config. Without
+ * Vite or entries, `index.html` if it exists.
+ */
+export declare function viteProject(root: string): Promise<{
+    pages: string[];
+    options: ProjectOptions;
+}>;

package/dist/project.js

@@ -0,0 +1,100 @@
+// The app's conventional files (helpers, config and types modules), found the same
+// way by the Vite plugin and by `sinter check`.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve, sep } from 'node:path';
+import { readHelperManifest } from './compiler/index.js';
+export function project(root, options = {}) {
+    const find = (given, base, exts = ['.js', '.ts']) => {
+        const candidates = given ? [given] : exts.map((e) => base + e);
+        for (const c of candidates)
+            if (existsSync(resolve(root, c)))
+                return c;
+        return null;
+    };
+    const readFile = (path) => {
+        const real = realpathSync(path);
+        const realRoot = realpathSync(root);
+        if (real !== realRoot && !real.startsWith(realRoot + sep))
+            throw new Error(`outside the project root: ${path}`);
+        return readFileSync(real, 'utf8');
+    };
+    const url = (rel) => '/' + rel.split(sep).join('/');
+    let helpers = { module: null, names: [], namespaces: {} };
+    const helpersRel = find(options.helpers, 'src/sinter.helpers');
+    const helpersFile = helpersRel ? resolve(root, helpersRel) : null;
+    if (helpersRel && helpersFile) {
+        helpers = readHelperManifest(readFileSync(helpersFile, 'utf8'), {
+            module: url(helpersRel),
+            file: helpersFile,
+            readFile,
+            resolve: (spec, from) => {
+                if (!spec.startsWith('.'))
+                    return null;
+                const base = resolve(dirname(from), spec);
+                for (const p of [base, base.replace(/\.js$/, '.ts'), `${base}.js`, `${base}.ts`])
+                    if (existsSync(p))
+                        return p;
+                return null;
+            },
+        });
+    }
+    const configRel = find(options.config, 'src/sinter.config');
+    const typesRel = find(options.types, 'src/sinter.types', ['.ts', '.d.ts', '.js']);
+    const openapi = [];
+    const diagnostics = [];
+    for (const rel of options.openapi == null ? [] : Array.isArray(options.openapi) ? options.openapi : [options.openapi]) {
+        const file = resolve(root, rel);
+        const fail = (why) => diagnostics.push({ severity: 'error', code: 'SN307', message: `OpenAPI spec \`${rel}\` ${why}`, file, line: 1, col: 1 });
+        let text;
+        try {
+            text = readFile(file);
+        }
+        catch (e) {
+            fail(`cannot be read: ${e.message}`);
+            continue;
+        }
+        let doc;
+        try {
+            doc = /\.json$/i.test(file) ? JSON.parse(text) : createRequire(import.meta.url)('yaml').parse(text);
+        }
+        catch (e) {
+            fail(`is not valid ${/\.json$/i.test(file) ? 'JSON' : 'YAML'}: ${e.message.split('\n')[0]}`);
+            continue;
+        }
+        const d = doc;
+        if (!d || typeof d.openapi !== 'string' || !/^3\./.test(d.openapi) || typeof d.paths !== 'object') {
+            fail('is not an OpenAPI 3 document (needs `openapi: 3.x` and `paths`)');
+            continue;
+        }
+        openapi.push({ file, doc });
+    }
+    return {
+        root, helpers, helpersFile, readFile, openapi, diagnostics,
+        config: configRel ? url(configRel) : null,
+        types: typesRel ? resolve(root, typesRel) : null,
+    };
+}
+/**
+ * The pages (HTML entries) and sinter plugin options from the root's Vite config. Without
+ * Vite or entries, `index.html` if it exists.
+ */
+export async function viteProject(root) {
+    const fallback = () => (existsSync(resolve(root, 'index.html')) ? [resolve(root, 'index.html')] : []);
+    let vite;
+    try {
+        vite = await import('vite');
+    }
+    catch {
+        return { pages: fallback(), options: {} };
+    }
+    const config = await vite.resolveConfig({ root, logLevel: 'silent' }, 'build', 'production');
+    const plugin = config.plugins.find((x) => x.name === 'sinter');
+    const build = config.build;
+    const input = build.rolldownOptions?.input ?? build.rollupOptions?.input;
+    const list = typeof input === 'string' ? [input] : Array.isArray(input) ? input : input && typeof input === 'object' ? Object.values(input) : [];
+    let pages = list.filter((f) => typeof f === 'string' && f.endsWith('.html')).map((f) => resolve(config.root, f));
+    if (!pages.length)
+        pages = fallback();
+    return { pages, options: plugin?.api?.options ?? {} };
+}

package/dist/runtime/app.d.ts

@@ -0,0 +1,125 @@
+import type { Binding, Fn, IR, ResourceDef, UrlTemplate } from '../ir.js';
+import { type Middleware } from './config.js';
+import type { Env } from './env.js';
+import { type RequestLayer, type SendInit } from './request.js';
+import { type Resource } from './store.js';
+export interface Feature {
+    name: string;
+    install(app: App): void;
+}
+export interface MountOptions {
+    ir: IR;
+    fns: Fn[];
+    features?: Feature[];
+    /** overrides for the testing module */
+    env?: Env;
+    request?: Middleware[];
+    /** stream transports by URL (testing); then `configure({ transport })`; default: EventSource */
+    transport?: (url: string) => Transport | undefined;
+}
+/**
+ * A server event transport (EventSource, WebSocket, SignalR, …). It delivers named events with
+ * their parsed payload and reports `open` once connected and `error` when the connection is lost;
+ * reconnecting (session probe, backoff, refetch) is the caller's job, so a transport never
+ * reconnects by itself. `names` are the event names the page maps; deliver at least those.
+ */
+export interface Transport {
+    connect(url: string, onEvent: (name: string, payload: unknown) => void, onState: (state: 'open' | 'error') => void, names: string[]): void;
+    /** start delivering another event name (islands subscribing later) */
+    listen?(name: string): void;
+    close(): void;
+}
+export interface StateHandle<T = any> {
+    get(): T;
+    update(fn: (state: T) => void): void;
+}
+/** A binding attached to one element in one scope. */
+export interface BoundBinding {
+    b: Binding;
+    el: Element;
+    s: any;
+}
+/** Pagination state of one resource; a "move" is one page request, repeated exactly by refetch. */
+export interface Pager {
+    reset(): void;
+    current(): unknown;
+    params(move: unknown): Record<string, string> | null;
+    appends(move: unknown): boolean;
+    received(items: unknown[], total: number | null, move: unknown): void;
+}
+export interface ResourceLoader {
+    def: ResourceDef;
+    res: Resource;
+    app: App;
+    pager: Pager | null;
+    load(move?: unknown): Promise<void>;
+    refetch(): Promise<void>;
+}
+export interface App {
+    readonly ir: IR;
+    readonly fns: Fn[];
+    readonly env: Env;
+    readonly req: RequestLayer;
+    /** the base scope: resources, status, magic names */
+    readonly page: any;
+    readonly transport: (url: string) => Transport | undefined;
+    readonly ext: {
+        optimistic?: {
+            begin(fn: number, scope: any): () => void;
+        };
+        paginate?: {
+            pager(loader: ResourceLoader): Pager;
+            page(name: string, target: string | number): void;
+        };
+        persist?: {
+            model(rb: BoundBinding, set: (v: unknown) => void): void;
+            state(key: string, obj: Record<string, unknown>): void;
+            saveState(key: string, obj: Record<string, unknown>): void;
+        };
+        cache?: {
+            /** the cached data for a request, if any and not older than the resource allows */
+            read(def: ResourceDef, url: string): {
+                t: number;
+                items: unknown;
+                total: number | null;
+            } | null;
+            /** a load (or embedded data) stored `items`: cache them, and the resource's later changes */
+            loaded(def: ResourceDef, r: Resource, url: string, items: unknown, total: number | null, appended: boolean): void;
+        };
+    };
+    readonly beforeFlush: Array<(dirty: string[][]) => void>;
+    readonly afterFlush: Array<(dirty: string[][]) => void>;
+    readonly onListen: Array<(event: string) => void>;
+    /** root state scopes: [sid, state object] */
+    readonly states: Array<[number, any]>;
+    /** pending debounce timers and waiting actions, for the testing module */
+    busy: number;
+    readonly isDirty: boolean;
+    /** dev hooks: dev-only checks on, warnings by code (or text), and item preparation (freezing) */
+    dev: boolean;
+    warn(code: number | string, ...args: unknown[]): void;
+    prep?: <T>(item: T) => T;
+    /** dev: an EventSource stream opened (its connection counts against HTTP/1.1's 6 per origin) */
+    streamOpened?: (url: string) => void;
+    resource<T extends object = any>(name: string): Resource<T>;
+    request(url: string, init?: SendInit): Promise<unknown>;
+    optimistic<T>(change: () => void, run: () => Promise<T>): Promise<T>;
+    on(event: string, fn: (payload: any) => void): () => void;
+    state<T = any>(el: Element): StateHandle<T>;
+    destroy(): void;
+    url(tpl: UrlTemplate, scope: any): string;
+    mark(path: string, scope?: any): void;
+    flush(): void;
+    record(change: () => void): () => void;
+    storeFns(el: Element | null): Record<string, (...a: any[]) => unknown>;
+    serverEvent(name: string, payload: unknown): void;
+    addCleanup(fn: () => void): void;
+}
+/** The instance mount() created on `root`; throws if none. */
+export declare function instance(root: Document | Element): App;
+export declare function mount(root: Document | Element, o: MountOptions): App;
+export declare function withParams(url: string, params: Record<string, string> | null): string;
+/** Indexes (into `seq`) of a longest increasing subsequence, ignoring -1 entries. */
+export declare function lis(seq: number[]): Set<number>;
+/** Serializes a form's named controls to nested JSON, or FormData if it has a file input. */
+export declare function serialize(form: HTMLFormElement): unknown;