@tiaforge-ui/sinter 0.1.0 → 0.2.0

package/dist/testing/index.js

@@ -11,9 +11,10 @@ import cache from '../cache.js';
 import dev from '../dev.js';
 import optimistic from '../optimistic.js';
 import paginate from '../paginate.js';
+import each from '../each.js';
 import persist from '../persist.js';
 import sse from '../sse.js';
-const FEATURES = { dev, sse, optimistic, paginate, persist, cache };
+const FEATURES = { dev, sse, optimistic, paginate, persist, cache, each };
 function isResponseSpec(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;
@@ -172,9 +173,17 @@ export async function render(html, options = {}) {
         else if (v && typeof v === 'object')
             manifest.namespaces[k] = { module: k, members: Object.keys(v) };
     }
+    const actions = options.actions ?? {};
+    const actionManifest = { module: 'actions', names: [], namespaces: {} };
+    for (const [k, v] of Object.entries(actions)) {
+        if (typeof v === 'function')
+            actionManifest.names.push(k);
+        else if (v && typeof v === 'object')
+            actionManifest.namespaces[k] = { module: k, members: Object.keys(v) };
+    }
     const files = options.files ?? {};
     const parts = compileParts(html, {
-        file: PAGE, root: '/test', dev: true, helpers: manifest, moduleSrc: 'about:blank',
+        file: PAGE, root: '/test', dev: true, helpers: manifest, actions: actionManifest, moduleSrc: 'about:blank',
         readFile: (p) => {
             const rel = p.startsWith('/test/') ? p.slice('/test/'.length) : p;
             const hit = files[rel] ?? files[`./${rel}`] ?? files[p];
@@ -203,6 +212,11 @@ export async function render(html, options = {}) {
             values.push(helpers[ns][m]);
         }
     }
+    for (const c of parts.calls) {
+        const [a, b] = c.split('.');
+        names.push(`$a$${c.replace('.', '$')}`);
+        values.push(b === undefined ? actions[a] : actions[a][b]);
+    }
     // eslint-disable-next-line no-new-func -- tests only; pages load a compiled module
     const fns = new Function(...names, `"use strict"; return [\n${parts.fns.join(',\n')}\n];`)(...values);
     // the page

package/dist/vite.js

@@ -51,7 +51,7 @@ export default function sinter(options = {}) {
                 return;
             const { check } = await import('./check/index.js');
             const p = project(root, options);
-            const r = check({ root, units: [...units.values()], helpers: p.helpers, types: p.types, openapi: p.openapi });
+            const r = check({ root, units: [...units.values()], helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi });
             units.clear();
             if (r.diagnostics.length)
                 this.error(`sinter check: ${r.diagnostics.length} type error(s)\n${r.diagnostics.map(formatDiagnostic).join('\n')}`);
@@ -66,7 +66,7 @@ export default function sinter(options = {}) {
                 if (p.diagnostics.length)
                     throw new Error(`sinter: ${p.diagnostics.map(formatDiagnostic).join('\n')}`);
                 const out = compile(html, {
-                    file, root, dev, helpers: p.helpers, moduleSrc, config: p.config, readFile: p.readFile,
+                    file, root, dev, helpers: p.helpers, actions: p.actions, moduleSrc, config: p.config, readFile: p.readFile,
                     check: !!options.typecheck && !dev, openapi: p.openapi,
                 });
                 if (out.check)
@@ -75,6 +75,8 @@ export default function sinter(options = {}) {
                     watch(f);
                 if (p.helpersFile)
                     watch(p.helpersFile);
+                if (p.actionsFile)
+                    watch(p.actionsFile);
                 const errors = out.diagnostics.filter((d) => d.severity === 'error');
                 for (const d of out.diagnostics)
                     if (d.severity === 'warning')

package/docs/diagnostics.md

@@ -148,7 +148,7 @@ Error, for example:
 
 > `$meta.contacts.loadng` is not a status field. Did you mean `loading`?
 
-`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `page`, `pages`, `from`, `to`, `hasPrev`, `hasNext`.
+`$meta.<resource>` has a fixed set of fields: `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate` also `pages`, `from`, `to`, `hasPrev`, `hasNext`; `page` with `paginate="offset"`, or keyset with `offset-param`.
 
 **Fix:** Use the suggested field. A pagination field needs `paginate` on the resource.
 
@@ -156,11 +156,11 @@ Error, for example:
 
 Error, for example:
 
-> keyset pagination cannot jump to a page number. Use `paginate="offset"`
+> keyset pagination cannot jump to a page number. Add `offset-param` if the server also accepts an offset, or use `paginate="offset"`
 
-Keyset (cursor) pagination only knows the next and previous page, so `page('name', 7)` has nothing to jump to.
+Keyset (cursor) pagination only knows the next and previous page, so `page('name', 7)` has nothing to jump to, unless the server can also skip items by offset.
 
-**Fix:** Use `paginate="offset"` if the API supports offsets, or only step with `next`, `prev` and `first`.
+**Fix:** If the API accepts an offset next to its cursor, add `offset-param="offset"`: the jump is sent as an offset and `prev`/`next` continue by cursor. Otherwise use `paginate="offset"`, or only step with `first`, `prev`, `next` and `last`.
 
 ## SN305 include-not-found
 
@@ -202,6 +202,16 @@ The resource matched an operation in the OpenAPI spec, but its `items` or `total
 
 **Fix:** Fix the path in `items` or `total`, or the spec if the API changed.
 
+## SN310 unknown-action
+
+Error, for example:
+
+> `pgp.decrpyt` is not exported by the actions module. Did you mean `pgp.decrypt`?
+
+`data-sn-call` and `<sn-resource call>` name a function the actions module (`src/sinter.actions.js` or `.ts`) exports, directly or through `export * as ns`.
+
+**Fix:** Use the suggested name, or export the function from the actions module.
+
 ## SN401 parse-error
 
 Error, for example:
@@ -250,7 +260,7 @@ Warning, for example:
 
 The type checker has no type for the resource, so expressions that use it are not checked. Reported by `sinter check` only.
 
-**Fix:** Add `type="Contact[]"` with a type from `src/sinter.types.ts`, configure an OpenAPI spec that matches `src`, or write `type="any"` to opt out.
+**Fix:** Add `type="Contact[]"` with a type from `src/sinter.types.ts`, configure an OpenAPI spec that matches `src`, load it with `call` (typed by what the action returns), or write `type="any"` to opt out.
 
 ## SN505 unknown-query-param
 

package/html-custom-data.json

@@ -11,6 +11,12 @@
         {
           "name": "src"
         },
+        {
+          "name": "call"
+        },
+        {
+          "name": "each"
+        },
         {
           "name": "key"
         },
@@ -41,9 +47,15 @@
         {
           "name": "direction-param"
         },
+        {
+          "name": "direction-values"
+        },
         {
           "name": "page-param"
         },
+        {
+          "name": "offset-param"
+        },
         {
           "name": "type"
         },
@@ -174,6 +186,10 @@
       "name": "data-sn-delete",
       "description": "DELETE action (URL template)"
     },
+    {
+      "name": "data-sn-call",
+      "description": "local action: calls a function from the actions module, e.g. pgp.decrypt(msg) (action call)"
+    },
     {
       "name": "data-sn-body",
       "description": "JSON request body; overrides form serialization (value expression)"
@@ -184,7 +200,7 @@
     },
     {
       "name": "data-sn-debounce",
-      "description": "delays the trigger, resets on each event (milliseconds)"
+      "description": "delays the trigger, resets on each event; without a method, delays the element's data-sn-on-* handlers (milliseconds)"
     },
     {
       "name": "data-sn-concurrency",

package/llms.txt

@@ -24,9 +24,10 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 - `data-sn-put` (URL template): PUT action
 - `data-sn-patch` (URL template): PATCH action
 - `data-sn-delete` (URL template): DELETE action
+- `data-sn-call` (action call): local action: calls a function from the actions module, e.g. pgp.decrypt(msg)
 - `data-sn-body` (value expression): JSON request body; overrides form serialization
 - `data-sn-trigger` (DOM event name): overrides the default trigger
-- `data-sn-debounce` (milliseconds): delays the trigger, resets on each event
+- `data-sn-debounce` (milliseconds): delays the trigger, resets on each event; without a method, delays the element's data-sn-on-* handlers
 - `data-sn-concurrency` (block | queue | latest): mutations only; default block for forms, queue otherwise
 - `data-sn-optimistic` (handler expression): patch/upsert/remove calls applied before the request, rolled back on failure
 - `data-sn-then` (handler expression): runs after a 2xx response; $result = parsed body
@@ -37,7 +38,7 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 
 ## Elements
 
-- `<sn-resource>` `name`, `src`, `key`, `items`, `total`, `order`, `when`, `paginate`, `page-size`, `size-param`, `cursor`, `direction-param`, `page-param`, `type`, `cache`: a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates
+- `<sn-resource>` `name`, `src`, `call`, `each`, `key`, `items`, `total`, `order`, `when`, `paginate`, `page-size`, `size-param`, `cursor`, `direction-param`, `direction-values`, `page-param`, `offset-param`, `type`, `cache`: a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates
 - `<sn-sync>` `src`: one server event stream
 - `<sn-event>` `name`, `resource`, `op`, `item`, `set`, `when`, `fallback`, `type`: maps one server event to a change message; child of <sn-sync>
 - `<sn-include>` `src`: inlines a partial at build time
@@ -63,7 +64,7 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 
 ## Diagnostics
 
-`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
+`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN310 unknown-action`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
 
 ## Recipes
 
@@ -502,6 +503,106 @@ test('the next page load shows the cached list while it revalidates', async () =
 });
 ```
 
+### Local actions: hash a file, then upload it
+
+```html
+<section data-sn-state="{ file: null, url: '', error: '' }">
+  <sn-resource name="digest" call="sha256(file)" when="file"></sn-resource>
+
+  <input type="file" data-sn-on-change="file = $el.files[0] ?? null; url = ''">
+  <p data-sn-show="$meta.digest.loading">Hashing…</p>
+  <code data-sn-text="digest"></code>
+
+  <button data-sn-call="upload(file, digest)" data-sn-attr="{disabled: !digest}"
+          data-sn-then="url = $result.url; error = ''" data-sn-catch="error = $error.message">Upload</button>
+  <a data-sn-show="url" data-sn-attr="{href: url}">Uploaded</a>
+  <p role="alert" data-sn-text="error"></p>
+</section>
+```
+
+```js
+// src/sinter.actions.js: functions pages call with data-sn-call and <sn-resource call>.
+// The last argument is sinter's context; with JSDoc types, `sinter check` checks the calls.
+/** @import { CallContext } from '@tiaforge-ui/sinter' */
+
+/**
+ * The file's SHA-256 as hex; choosing another file aborts the running hash through ctx.signal.
+ * @param {File} file
+ * @param {CallContext} ctx
+ * @returns {Promise<string>}
+ */
+export async function sha256(file, ctx) {
+  const bytes = await file.arrayBuffer();
+  ctx.signal.throwIfAborted();
+  const hash = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * ctx.request goes through the app's middleware (headers, 401 handling, allowed origins).
+ * @param {File} file
+ * @param {string} digest
+ * @param {CallContext} ctx
+ * @returns {Promise<{ url: string }>}
+ */
+export async function upload(file, digest, ctx) {
+  const form = new FormData();
+  form.append('file', file);
+  form.append('sha256', digest);
+  return /** @type {Promise<{ url: string }>} */ (ctx.request('/api/uploads', { method: 'POST', body: form }));
+}
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { checkPage } from '@tiaforge-ui/sinter/check';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import * as actions from './local-actions.actions.js';
+import source from './local-actions.actions.js?raw';
+import page from './local-actions.html?raw';
+
+const DIGEST = 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'; // sha256('abc')
+
+function choose(input: HTMLInputElement, file: File) {
+  Object.defineProperty(input, 'files', { value: [file], configurable: true });
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}
+
+test('hashes the chosen file, then uploads it with its digest', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { url: '/files/1' } });
+  const { root, settle } = await render(page, { actions, requests });
+  const button = root.querySelector('button')!;
+  expect(button.disabled).toBe(true);
+
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  expect(root.querySelector('code')!.textContent).toBe(DIGEST);
+  expect(button.disabled).toBe(false);
+
+  button.click();
+  await settle();
+  expect((requests.calls[0]!.body as FormData).get('sha256')).toBe(DIGEST);
+  expect(root.querySelector('a')!.getAttribute('href')).toBe('/files/1');
+});
+
+test('a failed upload shows the server message', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { status: 413, body: { message: 'File too large' } } });
+  const { root, settle } = await render(page, { actions, requests });
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  root.querySelector('button')!.click();
+  await settle();
+  expect(root.querySelector('[role=alert]')!.textContent).toBe('File too large');
+});
+
+test('sinter check: arguments are checked against the actions', () => {
+  const files = { 'src/sinter.actions.js': source };
+  expect(checkPage(page, { files })).toEqual([]);
+  const [d] = checkPage(page.replace('upload(file, digest)', 'upload(file)'), { files });
+  expect([d!.code, d!.message]).toEqual(['SN208', expect.stringContaining("is not assignable to type '[file: File, digest: string]'")]);
+});
+```
+
 ## Type checking
 
 `npx sinter check` type-checks every expression with the project's TypeScript (pages and options come from the Vite config). `sinter({ typecheck: true })` runs it in `vite build`.
@@ -525,7 +626,7 @@ Each open EventSource holds one HTTP connection, and HTTP/1.1 allows 6 per origi
 
 Write a test next to the markup. `@tiaforge-ui/sinter/testing` compiles the page with the real compiler and mounts it:
 
-- `render(html, { requests, streams, url, locale, now, helpers, files, storage, session })` → `{ root, app, flush, settle, advance, navigations, window }`. Pass one `memoryStorage()` as `session` to two renders to test what carries over between page loads (the `cache` attribute).
+- `render(html, { requests, streams, url, locale, now, helpers, actions, files, storage, session })` → `{ root, app, flush, settle, advance, navigations, window }`. Pass one `memoryStorage()` as `session` to two renders to test what carries over between page loads (the `cache` attribute).
 - `mockRequests({ 'GET /api/x': json | {status, body} | (call) => … })`: records `calls`; responses are held until `settle()`; an unmatched request fails the test and lists the routes.
 - `mockStream()`: `emit(name, payload)`, `drop()`, `connected`. A stream URL with no mock uses the transport from `configure({ transport })`, so a custom transport can be tested over a fake connection (see the SignalR recipe).
 - `flush()` runs the scheduler (optimistic changes are visible), `settle()` finishes requests, queues and debounces, `advance(ms)` moves sinter's clock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiaforge-ui/sinter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bind JSON APIs to plain HTML: keyed resources, SSE sync, template bindings and optimistic mutations, compiled at build time.",
   "license": "MIT",
   "author": "Tia Heinrich",
@@ -36,6 +36,7 @@
     "./ws": "./dist/ws.js",
     "./optimistic": "./dist/optimistic.js",
     "./paginate": "./dist/paginate.js",
+    "./each": "./dist/each.js",
     "./persist": "./dist/persist.js",
     "./cache": "./dist/cache.js",
     "./compiler": "./dist/compiler/index.js",
@@ -57,11 +58,13 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "bench": "vitest run --config bench/runtime/vitest.config.ts",
     "size": "npm run build && node scripts/size.mjs",
     "docs": "UPDATE_DOCS=1 vitest run test/docs.test.ts",
     "prepublishOnly": "rm -rf dist && npm run build && npm test"
   },
   "dependencies": {
+    "@sveltejs/acorn-typescript": "^1.0.13",
     "acorn": "^8.19.0",
     "acorn-walk": "^8.3.5",
     "parse5": "^8.1.0",