@tiaforge-ui/sinter 0.1.0 → 0.2.0

package/README.md

@@ -2,8 +2,9 @@
 
 **Your JSON API, bound to plain HTML.** sinter loads and caches server data, keeps it current from
 server events, renders it through `<template>` bindings and runs mutations with optimistic updates,
-without components, a router or a store library. A build step compiles the HTML, so the browser runs
-no parser and no `eval`.
+without components, a router or a store library. A compiler resolves every name in every expression
+at build time, and type-checks it when you give it your TypeScript types or OpenAPI spec. A typo
+fails the build instead of the page, and the browser runs no parser and no `eval`.
 
 ```html
 <sn-resource name="contacts" src="/api/contacts" items="contacts" key="id" order="name"></sn-resource>
@@ -30,6 +31,26 @@ That page loads the contacts, keeps them sorted, applies updates other users mak
 filters as you type, and removes a contact at once when you click Delete, putting it back if the
 server refuses.
 
+## Mistakes fail the build
+
+The compiler knows every name an expression can use: the state around it, loop variables,
+resources, helpers. Misspell `q` in the filter above and the build stops:
+
+```text
+contacts.html:11:70 error SN201 unknown-identifier: `qq` is not defined here. Did you mean `q`?
+```
+
+The same pass rejects code that would break at runtime: writing to server data
+(`c.name = 'x'` is `SN205`, use `patch('contacts', c, {…})`) and browser APIs inside expressions
+(`localStorage` is `SN202`, use an island). With a `type` on the resource or your OpenAPI spec,
+`sinter check` also type-checks fields, request bodies and event payloads, so `article.titel`
+reports `Property 'titel' does not exist on type 'Article'. Did you mean 'title'?`. Your editor
+shows these errors as you type.
+
+htmx, Datastar and Alpine read their attribute strings in the browser. Nothing checks them against
+your data before they ship, so the same typo shows up only when that code runs: as a console error,
+or as an element that stays empty.
+
 ## Why sinter
 
 - **The server-state plumbing is gone.** You don't write loading flags, stale-response guards,
@@ -37,11 +58,11 @@ server refuses.
   They are attributes.
 - **Optimistic updates that stay correct**, also when requests overlap or a server event arrives
   while a request is in flight.
+- **Checked before it ships.** Every name in every expression is resolved at build time and
+  type-checked against your TypeScript types or your OpenAPI spec. Your editor shows the errors as
+  you type, with hover, completion and go to definition.
 - **Less code.** The [RealWorld](examples/realworld) app takes 735 lines in sinter. The official
-  Angular version takes 2,210. Each page downloads 12–14 KB of JS.
-- **Errors at build time.** Every expression is type-checked against your TypeScript types or your
-  OpenAPI spec. Your editor shows the errors as you type, with hover, completion and go to
-  definition.
+  Angular version takes 2,210. Each page downloads 14–16 KB of JS.
 - **Safe by construction.** Directives are compiled, not read from the live DOM. Pages run under
   `script-src 'self'` with no `unsafe-eval`, and markup injected at runtime stays inert.
 - **Plain, valid HTML.** There is one way to do each thing, and everything is visible on the element.
@@ -57,11 +78,14 @@ page load (the shared code comes from the browser cache).
 
 **htmx, Datastar.** These expect a server that renders HTML for every page and interaction. If you
 have a JSON API, you would have to build and maintain that server. sinter uses the API you already
-have, and its mutations are optimistic where htmx waits for the server's answer. If your backend
-renders HTML anyway and you want no build step, htmx is a good choice.
+have, and its mutations are optimistic where htmx waits for the server's answer. Their attributes
+are read in the browser, so a wrong name surfaces at runtime; sinter's are checked at build time.
+If your backend renders HTML anyway and you want no build step, htmx is a good choice.
 
 **Alpine, petite-vue.** These also render JSON with client-side templates, but they leave fetching,
-caching, live updates and rollback to you.
+caching, live updates and rollback to you. Their expressions are compiled in the browser with
+`new Function`, so they need `unsafe-eval` in the CSP (Alpine has a restricted CSP build), and
+nothing checks the names or fields they use until the code runs.
 
 Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-comparison.md).
 
@@ -72,7 +96,7 @@ Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-compar
   islands, which are plain custom elements.
 - You can't have a build step.
 - Your backend renders HTML, not JSON.
-- You need stability guarantees. sinter is at v0.1.
+- You need stability guarantees. sinter is at v0.2.
 
 ## Setup
 
@@ -113,6 +137,7 @@ Then write `data-sn-*` attributes in your HTML pages. Optional:
 | `@tiaforge-ui/sinter/ws` | WebSocket transport for `<sn-sync>` |
 | `@tiaforge-ui/sinter/optimistic` | optimistic layers |
 | `@tiaforge-ui/sinter/paginate` | keyset, offset, append |
+| `@tiaforge-ui/sinter/each` | fan-out resources (`each="a in accounts"`) |
 | `@tiaforge-ui/sinter/persist` | `data-sn-persist` |
 | `@tiaforge-ui/sinter/compiler` | `compile()` |
 | `@tiaforge-ui/sinter/vite` | Vite plugin |
@@ -125,7 +150,8 @@ Then write `data-sn-*` attributes in your HTML pages. Optional:
 npm test          # vitest (happy-dom)
 npm run typecheck
 npm run build     # dist/
-npm run size      # size budget per module
+npm run size      # size per page and module, with budgets
+npm run bench     # store and flush benchmarks (docs/benchmark.md)
 npm run docs      # regenerate llms.txt, html-custom-data.json (also the VS Code extension's) and docs/diagnostics.md
 ```
 

package/dist/check/index.d.ts

@@ -9,6 +9,8 @@ export interface CheckOptions {
     /** from `compile(…, { check: true })`, one per page */
     units: CheckUnit[];
     helpers: HelperManifest;
+    /** the actions module (`data-sn-call`), same shape as helpers */
+    actions?: HelperManifest;
     /** absolute path of the types module, or null */
     types: string | null;
     /** the specs the pages were compiled with (`compile(…, { openapi })`) */
@@ -57,12 +59,13 @@ export declare const COMPILER_OPTIONS: {
     target: string;
     module: string;
     moduleResolution: string;
+    allowImportingTsExtensions: boolean;
     lib: string[];
     types: string[];
 };
 /** Where a page's shadow file goes. */
 export declare function shadowPath(support: Support, root: string, page: string): string;
-export declare function shadowOf(unit: CheckUnit, support: Support, root: string, helpers: HelperManifest): Shadow;
+export declare function shadowOf(unit: CheckUnit, support: Support, root: string, helpers: HelperManifest, actions?: HelperManifest): Shadow;
 /** A TypeScript error at a 1-based shadow position, as an SN208 diagnostic at the HTML position. */
 export declare function typeDiagnostic(unit: CheckUnit, regions: Region[], line: number, col: number, code: string, message: string, root: string): Diagnostic;
 export declare function check(o: CheckOptions): CheckResult;

package/dist/check/index.js

@@ -25,14 +25,14 @@ export function writeSupport(o) {
 /** The compiler options shadow files are checked with. */
 export const COMPILER_OPTIONS = {
     allowJs: true, checkJs: true, strict: true, strictNullChecks: false, noImplicitAny: false, noEmit: true, skipLibCheck: true,
-    target: 'es2022', module: 'esnext', moduleResolution: 'bundler', lib: ['es2023', 'dom', 'dom.iterable'], types: [],
+    target: 'es2022', module: 'esnext', moduleResolution: 'bundler', allowImportingTsExtensions: true, lib: ['es2023', 'dom', 'dom.iterable'], types: [],
 };
 /** Where a page's shadow file goes. */
 export function shadowPath(support, root, page) {
     return join(support.outDir, relative(root, page) + '.js');
 }
-export function shadowOf(unit, support, root, helpers) {
-    return shadow({ unit, file: shadowPath(support, root, unit.file), root, declarations: support.declarations, types: support.types, helpers, openapi: support.openapi });
+export function shadowOf(unit, support, root, helpers, actions) {
+    return shadow({ unit, file: shadowPath(support, root, unit.file), root, declarations: support.declarations, types: support.types, helpers, actions, openapi: support.openapi });
 }
 /** A TypeScript error at a 1-based shadow position, as an SN208 diagnostic at the HTML position. */
 export function typeDiagnostic(unit, regions, line, col, code, message, root) {
@@ -56,7 +56,7 @@ export function check(o) {
     const shadows = new Map();
     for (const unit of o.units) {
         const file = shadowPath(support, o.root, unit.file);
-        const s = shadowOf(unit, support, o.root, o.helpers);
+        const s = shadowOf(unit, support, o.root, o.helpers, o.actions);
         mkdirSync(dirname(file), { recursive: true });
         writeFileSync(file, s.text);
         shadows.set(resolve(file), { unit, regions: s.regions, brokenFrom: s.brokenFrom });
@@ -72,7 +72,7 @@ export function check(o) {
         throw run.error;
     const diagnostics = parseTsc(run.stdout, outDir, o.root, shadows);
     const resources = o.units.reduce((n, u) => n + u.resources.length, 0);
-    const typed = o.units.reduce((n, u) => n + u.resources.filter((r) => r.type || r.openapi).length, 0);
+    const typed = o.units.reduce((n, u) => n + u.resources.filter((r) => r.type || r.openapi || r.call).length, 0);
     const viaOpenapi = o.units.reduce((n, u) => n + u.resources.filter((r) => !r.type && r.openapi).length, 0);
     return { diagnostics, resources, typed, openapi: viaOpenapi };
 }
@@ -91,8 +91,8 @@ export function checkPage(html, o = {}) {
         const file = join(root, 'index.html');
         writeFileSync(file, html);
         const p = project(root, o);
-        const out = compile(html, { file, root, dev: false, helpers: p.helpers, readFile: p.readFile, check: true, openapi: p.openapi });
-        const r = check({ root, units: out.check ? [out.check] : [], helpers: p.helpers, types: p.types, openapi: p.openapi, tsc: findTsc(process.cwd()) });
+        const out = compile(html, { file, root, dev: false, helpers: p.helpers, actions: p.actions, readFile: p.readFile, check: true, openapi: p.openapi });
+        const r = check({ root, units: out.check ? [out.check] : [], helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi, tsc: findTsc(process.cwd()) });
         return [...p.diagnostics, ...out.diagnostics, ...r.diagnostics].map((d) => ({ ...d, file: relative(root, d.file) }));
     }
     finally {

package/dist/check/shadow.d.ts

@@ -14,6 +14,8 @@ export interface ShadowOptions {
         names: string[];
     } | null;
     helpers: HelperManifest;
+    /** the actions module, for `data-sn-call` arguments and results */
+    actions?: HelperManifest;
     /** absolute paths of the declarations generated per OpenAPI spec, by spec index */
     openapi?: string[];
 }
@@ -36,7 +38,7 @@ export declare function shadow(o: ShadowOptions): Shadow;
 /** Maps a 1-based shadow position to the HTML, or null for generated lines. */
 export declare function mapPosition(regions: Region[], line: number, col: number): CheckLoc | null;
 /** `sinter.d.ts`: the types the shadow files refer to. */
-export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number; body: any; message: string }\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  close(): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
+export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number | null;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number | null; body: any; message: string }\nexport interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }\n/** an action's parameters without its trailing context */\nexport type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  close(): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
 /**
  * Maps a 1-based position in an HTML file to the shadow, or null when it is not inside an
  * expression. `lines` are the shadow's lines.

package/dist/check/shadow.js

@@ -51,7 +51,12 @@ export function shadow(o) {
         if (!taken.has(ns))
             line(`import * as ${ns} from '${moduleSpec(module)}';`);
     }
+    if (o.actions?.module && (unit.resources.some((r) => r.call) || unit.exprs.some((e) => e.returns?.kind === 'call' || e.resultType?.kind === 'call'))) {
+        line(`import * as $A from '${moduleSpec(o.actions.module)}';`);
+    }
     line('const $any = /** @type {any} */ (null);');
+    /** what a resource fed by `call` holds: the awaited result, at its `items` path */
+    const callResult = (c) => `Awaited<ReturnType<typeof $A.${c.name}>>${(c.items ? c.items.split('.') : []).map((k) => `[${JSON.stringify(k)}]`).join('')}`;
     const types = [];
     for (const r of unit.resources) {
         const t = r.type ?? 'any';
@@ -64,6 +69,11 @@ export function shadow(o) {
             line(' * }');
             line(' */');
         }
+        else if (r.call) {
+            const t = callResult(r.call);
+            types[types.length - 1] = `${JSON.stringify(r.name)}: ${t}`;
+            line(`/** @type {${t}} */`);
+        }
         else if (r.openapi) {
             const t = schemaToTs(r.openapi.schema, (n) => `$O${r.openapi.spec}.${typeName(n)}`);
             types[types.length - 1] = `${JSON.stringify(r.name)}: ${t}`;
@@ -74,6 +84,14 @@ export function shadow(o) {
             line('/** @type {any} */');
         regions.push({ start: out.length + 1, lines: 1, loc: r.nameLoc ?? r.loc, fixed: true });
         line(`const ${r.name} = $any;`);
+        // with `type`, what the action returns (at `items`) must fit it; reported on `type`
+        if (r.call && r.type) {
+            // own line: TypeScript drops a JSDoc tag that follows `{` on the same line
+            line('{');
+            regions.push({ start: out.length + 1, lines: 1, loc: r.loc, fixed: true });
+            line(`/** @type {${r.type.replace(/\s+/g, ' ')}} */ const $fits = /** @type {${callResult(r.call)}} */ ($any); void $fits;`);
+            line('}');
+        }
     }
     const names = unit.resources.map((r) => JSON.stringify(r.name)).join(' | ') || 'never';
     line(`/** @type {Record<${names}, ${decl('Meta')}>} */`);
@@ -99,7 +117,9 @@ export function shadow(o) {
         }
         const text = t.kind === 'openapi'
             ? schemaToTs(t.schema, (n) => `$O${t.spec}.${typeName(n)}`)
-            : `${t.partial ? 'Partial<' : ''}${decl('Item')}<typeof ${t.resource}>${t.partial ? '>' : ''}`;
+            : t.kind === 'call'
+                ? (t.args ? `${decl('CallArgs')}<typeof $A.${t.name}>` : `Awaited<ReturnType<typeof $A.${t.name}>>`)
+                : `${t.partial ? 'Partial<' : ''}${decl('Item')}<typeof ${t.resource}>${t.partial ? '>' : ''}`;
         line(`/** @${tag} {${text}} */${after}`);
     };
     /** declarations for the frames of an expression; returns the number of blocks opened */
@@ -148,8 +168,19 @@ export function shadow(o) {
                 regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
                 line(`const ${n} = $p.${n};`);
             }
+            // a state name shadows a payload field of the same name: an error when the payload type has it
+            if (e.payload.type) {
+                for (const n of e.payload.states ?? []) {
+                    const msg = `state \`${n}\` shadows the payload field \`${n}\`: rename the state`;
+                    regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
+                    line(`/** @type {${JSON.stringify(n)} extends keyof typeof $p ? ${JSON.stringify(msg)} : true} */ const $shadows_${n} = true; void $shadows_${n};`);
+                }
+            }
         }
         if (e.mode === 'value') {
+            // action arguments and bodies are taken when the trigger fires
+            if (e.event !== null)
+                line(`/** @type {${decl(`Ev<${JSON.stringify(e.event)}>`)}} */ const $event = $any;`);
             // a value of the wrong type as a whole is reported on `return`
             regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
             line('return (');
@@ -195,14 +226,17 @@ export interface Meta {
   loadedAt: number | null;
   pending: number;
   total: number | null;
-  page?: number;
+  page?: number | null;
   pages?: number | null;
   from?: number | null;
   to?: number | null;
   hasPrev?: boolean;
   hasNext?: boolean;
 }
-export interface Err { status: number; body: any; message: string }
+export interface Err { status: number | null; body: any; message: string }
+export interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }
+/** an action's parameters without its trailing context */
+export type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;
 export type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;
 export type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;
 export type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;

package/dist/cli.js

@@ -36,12 +36,12 @@ async function main(argv) {
     const diagnostics = [...p.diagnostics];
     const units = [];
     for (const file of files) {
-        const out = compile(readFileSync(file, 'utf8'), { file, root, dev: false, helpers: p.helpers, config: p.config, readFile: p.readFile, check: true, openapi: p.openapi });
+        const out = compile(readFileSync(file, 'utf8'), { file, root, dev: false, helpers: p.helpers, actions: p.actions, config: p.config, readFile: p.readFile, check: true, openapi: p.openapi });
         diagnostics.push(...out.diagnostics);
         if (out.check)
             units.push(out.check);
     }
-    const r = check({ root, units, helpers: p.helpers, types: p.types, openapi: p.openapi });
+    const r = check({ root, units, helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi });
     diagnostics.push(...r.diagnostics);
     for (const d of diagnostics)
         console.log(formatDiagnostic({ ...d, file: relative(process.cwd(), d.file) || d.file }) + '\n');

package/dist/compiler/check-unit.d.ts

@@ -47,6 +47,12 @@ export type TypeRef =
     kind: 'item';
     resource: string;
     partial?: boolean;
+}
+/** an action (`archive`, `pgp.decrypt`): its arguments (`args`) or its awaited result */
+ | {
+    kind: 'call';
+    name: string;
+    args?: boolean;
 };
 export interface CheckExpr {
     src: string;
@@ -70,6 +76,7 @@ export interface CheckExpr {
     payload?: {
         names: string[];
         type: TypeRef | null;
+        states?: string[];
     };
     /** the compiler reported an error in it (it may not even parse); kept for editor completion, never type-checked */
     broken?: boolean;
@@ -88,6 +95,11 @@ export interface CheckResource {
         label: string;
         schema: unknown;
     };
+    /** `call`: the action and the `items` path into its result; with `type`, the result must fit it */
+    call?: {
+        name: string;
+        items: string | null;
+    };
 }
 export interface CheckUnit {
     file: string;

package/dist/compiler/compile.d.ts

@@ -25,6 +25,8 @@ export interface CompileOptions {
     check?: boolean;
     /** parsed OpenAPI specs: resources without `type` are matched against them */
     openapi?: OpenApiSpec[];
+    /** the actions module (`data-sn-call`, `<sn-resource call>`), same shape as helpers */
+    actions?: HelperManifest;
 }
 export interface CompileResult {
     html: string;
@@ -45,6 +47,8 @@ export interface CompiledParts {
         builtin: string[];
     };
     namespaces: Record<string, string[]>;
+    /** action functions called, as written: `archive`, `pgp.decrypt` */
+    calls: string[];
     diagnostics: Diagnostic[];
     files: string[];
     /** with `check: true` */