@tiaforge-ui/sinter 0.0.0-stage → 0.2.0

package/dist/project.js

@@ -0,0 +1,103 @@
+// 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('/');
+    const manifest = (given, base) => {
+        const rel = find(given, base);
+        const file = rel ? resolve(root, rel) : null;
+        if (!rel || !file)
+            return [{ module: null, names: [], namespaces: {} }, null];
+        return [readHelperManifest(readFileSync(file, 'utf8'), {
+                module: url(rel),
+                file,
+                readFile,
+                resolve: (spec, from) => {
+                    if (!spec.startsWith('.'))
+                        return null;
+                    const b = resolve(dirname(from), spec);
+                    for (const q of [b, b.replace(/\.js$/, '.ts'), `${b}.js`, `${b}.ts`])
+                        if (existsSync(q))
+                            return q;
+                    return null;
+                },
+            }), file];
+    };
+    const [helpers, helpersFile] = manifest(options.helpers, 'src/sinter.helpers');
+    const [actions, actionsFile] = manifest(options.actions, 'src/sinter.actions');
+    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, actions, actionsFile, 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,152 @@
+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;
+}
+/** The last argument of an action function (`data-sn-call`, `<sn-resource call>`). */
+export interface CallContext {
+    /** aborts when the page is hidden (pagehide) or, for a resource, when its inputs change */
+    signal: AbortSignal;
+    /** a request through the app's middleware chain (401 handling, origins, timeout) */
+    request(url: string, init?: SendInit): Promise<unknown>;
+    /** the element whose action this is; null for a resource */
+    el: Element | null;
+}
+export interface ResourceLoader {
+    def: ResourceDef;
+    res: Resource;
+    app: App;
+    pager: Pager | null;
+    /** first load (or embedded/cached data) */
+    start(): void;
+    /** `src`, `when` (or an `each` list) may have changed */
+    changed(): void;
+    load(move?: unknown): Promise<void>;
+    refetch(hint?: object): Promise<void>;
+    /** for feature modules: the scope `src` and `when` are evaluated in */
+    scope(): any;
+    /** for feature modules: a shared GET (concurrent loads of one URL share one request) */
+    get(url: string, signal: AbortSignal): Promise<unknown>;
+    /** for feature modules: the collection items of a response body (`items` path, checked, cleaned) */
+    items(body: unknown): any[];
+    /** for feature modules: a failed load: `$meta.error`, then the unhandled-error path */
+    failed(e: unknown): void;
+    loading(on: boolean): 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;
+        };
+        each?: {
+            fanOut(loader: ResourceLoader): 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;
+    /** the scope of root node `i` (its state), or the page scope for -1 */
+    scopeOf(i: number): any;
+    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;