@tiaforge-ui/sinter 0.3.1 → 0.3.3

package/dist/compiler/compile.js

@@ -749,7 +749,8 @@ class Compiler {
         let event = null;
         if (attrName.startsWith('data-sn-on-'))
             event = attrName.slice('data-sn-on-'.length);
-        else if (o.mode !== 'value' || o.magic?.includes('$event')) {
+        // an <sn-event> handler runs for a server event, not a DOM event
+        else if ((o.mode !== 'value' || o.magic?.includes('$event')) && el.tagName !== 'sn-event') {
             event = attr(el, 'data-sn-trigger') ?? (el.tagName === 'form' ? 'submit' : FORM_CONTROLS.has(el.tagName) ? 'change' : 'click');
         }
         const e = {
@@ -1239,33 +1240,37 @@ class Compiler {
                 this.report(el, a.name, 'SN101', `\`${a.name}\` is not an attribute of \`<sn-event>\`.${didYouMean(a.name, EVENT_ATTRS)}`, 0);
         }
         const name = attr(el, 'name');
-        const resource = attr(el, 'resource');
-        const op = attr(el, 'op');
+        const resource = attr(el, 'resource') ?? null;
+        const op = (attr(el, 'op') ?? null);
         if (!name) {
             this.report(el, null, 'SN401', '`<sn-event>` needs `name`', 0);
             return null;
         }
-        if (!resource || !this.page.resources.has(resource)) {
+        // with `then`, an event may only run its handler
+        const only = resource === null && op === null && attr(el, 'then') != null;
+        if (!only && (!resource || !this.page.resources.has(resource))) {
             this.report(el, 'resource', 'SN301', `resource \`${resource ?? ''}\` is not declared on this page.${didYouMean(resource ?? '', this.page.resources.keys())}`, 0);
             return null;
         }
-        if (!op || !['upsert', 'patch', 'remove', 'refetch'].includes(op)) {
+        if (!only && (!op || !['upsert', 'patch', 'remove', 'refetch'].includes(op))) {
             this.report(el, 'op', 'SN401', '`op` is `upsert`, `patch`, `remove` or `refetch`', 0);
             return null;
         }
         const scope = ctx.scope;
         const typeAttr = attr(el, 'type')?.trim() || null;
         const payloadType = typeAttr && typeAttr !== 'any' ? { kind: 'ts', text: typeAttr, loc: this.locOf(el, 'type') } : null;
-        if (this.check && !typeAttr && ['item', 'set', 'when'].some((n) => attr(el, n) != null)) {
+        if (this.check && !typeAttr && ['item', 'set', 'when', 'then'].some((n) => attr(el, n) != null)) {
             this.report(el, null, 'SN506', `event \`${name}\` has no type: expressions reading its payload are not checked`, 0, 'add `type="…"` with the payload type from the types module, or `type="any"` to leave it unchecked');
         }
+        let writes = [];
         const fnOf = (n, object = false) => {
             if (attr(el, n) == null)
                 return null;
-            const r = this.expr(el, n, scope, { mode: 'value', payload: true, payloadState: true });
+            const r = this.expr(el, n, scope, { mode: n === 'then' ? 'handler' : 'value', payload: true, payloadState: true });
+            writes = r.writes;
             this.typeLast({
                 payload: payloadType,
-                ...(n === 'item' ? { returns: { kind: 'item', resource } } : n === 'set' ? { returns: { kind: 'item', resource, partial: true } } : {}),
+                ...(!resource ? {} : n === 'item' ? { returns: { kind: 'item', resource } } : n === 'set' ? { returns: { kind: 'item', resource, partial: true } } : {}),
             });
             if (object && r.ast && r.ast.type !== 'ObjectExpression')
                 this.report(el, n, 'SN401', `\`${n}\` must be an object literal`, 0);
@@ -1282,7 +1287,12 @@ class Compiler {
         const fallback = attr(el, 'fallback');
         if (fallback != null && fallback !== 'refetch')
             this.report(el, 'fallback', 'SN401', '`fallback` takes `refetch`', 0);
-        return { name, resource, op, item, set, when: fnOf('when'), fallback: fallback === 'refetch' ? 'refetch' : null };
+        const when = fnOf('when');
+        const then = fnOf('then');
+        return {
+            name, resource, op, item, set, when, fallback: fallback === 'refetch' ? 'refetch' : null,
+            ...(then !== null ? { then, ...(writes.length ? { w: writes } : {}) } : {}),
+        };
     }
     injectScript(doc) {
         const html = doc.childNodes.find((n) => isElement(n) && n.tagName === 'html');

package/dist/compiler/expr.js

@@ -149,7 +149,8 @@ export function analyze(src, scope, page, opts) {
                 return { kind: 'resource' };
             }
         }
-        if (STORE_FNS.includes(name) && !opts.payload)
+        // an <sn-event> `then` calls store functions; its value expressions do not
+        if (STORE_FNS.includes(name) && (!opts.payload || mode === 'handler'))
             return { kind: 'store' };
         if (page.namespaces.has(name))
             return { kind: 'ns' };
@@ -613,6 +614,11 @@ export function analyze(src, scope, page, opts) {
             return;
         }
         const first = n.arguments[0];
+        // an <sn-event> handler has no element: no nearest dialog or form, nothing to dispatch from
+        if (opts.payload && (name === 'reset' || name === 'emit' || (name === 'close' && !first))) {
+            report('SN203', `\`${name}()\` needs an element; an \`<sn-event>\` handler has none${name === 'close' ? `: name the dialog, \`close('id')\`` : ''}`, n.start);
+            return;
+        }
         if (name === 'showModal' || (name === 'close' && first)) {
             if (!first || first.type !== 'Literal' || typeof first.value !== 'string') {
                 report('SN309', `\`${name}()\` takes the dialog's \`id\` as a string literal`, n.start);

package/dist/compiler/vocabulary.js

@@ -39,6 +39,6 @@ export const DEBOUNCE_ON_DOC = { name: 'debounce-<event>', value: 'milliseconds'
 export const ELEMENTS = [
     { name: 'sn-resource', attrs: ['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'], doc: 'a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates' },
     { name: 'sn-sync', attrs: ['src'], doc: 'one server event stream' },
-    { name: 'sn-event', attrs: ['name', 'resource', 'op', 'item', 'set', 'when', 'fallback', 'type'], doc: 'maps one server event to a change message; child of <sn-sync>' },
+    { name: 'sn-event', attrs: ['name', 'resource', 'op', 'item', 'set', 'when', 'fallback', 'then', 'type'], doc: 'maps one server event to a change message; child of <sn-sync>. `then` is a handler run after the change (payload fields and the state around the sync in scope), e.g. close(\'detail\'); with `then`, `resource` and `op` may be left out' },
     { name: 'sn-include', attrs: ['src'], doc: 'inlines a partial at build time' },
 ];

package/dist/ir.d.ts

@@ -44,12 +44,16 @@ export interface ResourceDef {
 }
 export interface EventDef {
     name: string;
-    resource: string;
-    op: 'upsert' | 'patch' | 'remove' | 'refetch';
+    /** null for an event that only runs `then` */
+    resource: string | null;
+    op: 'upsert' | 'patch' | 'remove' | 'refetch' | null;
     item: number | null;
     set: number | null;
     when: number | null;
     fallback: 'refetch' | null;
+    /** `then`: handler run after the change is applied; `w`: the state paths it writes */
+    then?: number;
+    w?: string[];
 }
 export interface SyncDef {
     src: UrlTemplate;

package/dist/ir.js

@@ -54,13 +54,24 @@ export function validateIR(ir, fnCount) {
         url(s.src, `syncs[${i}].src`);
         s.events.forEach((e, j) => {
             const at = `syncs[${i}].events[${j}]`;
-            if (!names.has(e.resource))
-                errs.push(`${at}: unknown resource ${e.resource}`);
-            if (!['upsert', 'patch', 'remove', 'refetch'].includes(e.op))
-                errs.push(`${at}: bad op`);
+            // without a resource and op, the event only runs `then`
+            if (e.resource === null && e.op === null) {
+                if (e.then === undefined)
+                    errs.push(`${at}: needs a resource or then`);
+            }
+            else {
+                if (!names.has(e.resource))
+                    errs.push(`${at}: unknown resource ${e.resource}`);
+                if (!['upsert', 'patch', 'remove', 'refetch'].includes(e.op))
+                    errs.push(`${at}: bad op`);
+            }
             fn(e.item, `${at}.item`);
             fn(e.set, `${at}.set`);
             fn(e.when, `${at}.when`);
+            fn(e.then, `${at}.then`);
+            for (const d of e.w ?? [])
+                if (typeof d !== 'string' || !d)
+                    errs.push(`${at}: bad path`);
         });
     });
     const kinds = new Set(['text', 'attr', 'class', 'style', 'show', 'model', 'prop', 'for', 'if', 'else', 'on']);

package/dist/runtime/app.d.ts

@@ -144,6 +144,8 @@ export interface App {
     record(change: () => void): () => void;
     storeFns(el: Element | null): Record<string, (...a: any[]) => unknown>;
     serverEvent(name: string, payload: unknown): void;
+    /** runs handler `f` in `scope` and invalidates the paths it writes */
+    run(f: number, scope: any, writes?: string[]): void;
     addCleanup(fn: () => void): void;
 }
 /** The instance mount() created on `root`; throws if none. */

package/dist/runtime/app.js

@@ -316,6 +316,18 @@ export function mount(root, o) {
                     console.error(e);
                 }
         },
+        run(f, s, writes) {
+            try {
+                fns[f](s);
+            }
+            catch (err) {
+                console.error(err);
+            }
+            for (const w of writes ?? [])
+                app.mark(w, s);
+            if (writes?.some((w) => w.startsWith('$url')))
+                writeUrl();
+        },
         // after destroy(), nothing waits for the next one: run it now
         addCleanup: (fn) => void (destroyed ? fn() : cleanups.push(fn)),
     };
@@ -894,17 +906,7 @@ export function mount(root, o) {
     }
     /** Runs a handler expression and invalidates what it may have changed. */
     function handle(rb, f, e, writes, extra) {
-        const s = child(rb.s, { $el: rb.el, $event: e, $f: app.storeFns(rb.el), ...extra });
-        try {
-            fns[f](s);
-        }
-        catch (err) {
-            console.error(err);
-        }
-        for (const w of writes ?? [])
-            app.mark(w, s);
-        if (writes?.some((w) => w.startsWith('$url')))
-            writeUrl();
+        app.run(f, child(rb.s, { $el: rb.el, $event: e, $f: app.storeFns(rb.el), ...extra }), writes);
     }
     /** A debounced handler: runs once `ms` after the last event, with that event. */
     function later(rb, e) {

package/dist/sse.js

@@ -34,25 +34,21 @@ export function eventSourceTransport() {
         close() { es?.close(); es = null; },
     };
 }
+/** One stream URL's connection, shared by every `<sn-sync>` on the page that resolves to it. */
 class Connection {
     app;
-    def;
+    url;
     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) {
+    /** each mapped event with the scope its expressions are evaluated in: its `<sn-sync>`'s state, or the page */
+    subs = [];
+    constructor(app, url) {
         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))];
+        this.url = url;
     }
     start() {
         const env = this.app.env;
@@ -68,9 +64,6 @@ class Connection {
         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;
@@ -78,6 +71,7 @@ class Connection {
         const t = custom ?? eventSourceTransport();
         this.t = t;
         const reconnect = this.everOpen;
+        const subs = this.subs.map(([e]) => e);
         t.connect(this.url, (name, data) => this.event(name, data), (state) => {
             if (this.t !== t)
                 return;
@@ -88,15 +82,16 @@ class Connection {
                     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();
+                    for (const name of new Set(subs.map((e) => e.resource)))
+                        if (name)
+                            void this.app.resource(name).refetch();
             }
             else {
                 t.close();
                 this.t = null;
                 void this.probe();
             }
-        }, this.names());
+        }, [...new Set(subs.map((e) => e.name))]);
     }
     stop() {
         this.t?.close();
@@ -135,59 +130,66 @@ class Connection {
         this.timer = this.app.env.setTimeout(() => { this.timer = null; fn(); }, delay, 'backoff');
     }
     event(name, payload) {
-        for (const def of this.def.events)
+        for (const [def, base] of this.subs)
             if (def.name === name)
-                this.apply(def, payload);
+                this.apply(def, base, payload);
         this.app.serverEvent(name, payload);
     }
-    apply(def, payload) {
+    apply(def, base, payload) {
         const app = this.app;
-        const scope = Object.create(this.base);
+        const scope = Object.create(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':
+            // `then` runs once the change is applied (a refetch: requested), unless the payload could not be applied
+            if (def.resource && !this.change(def, def.resource, scope, payload))
+                return;
+            if (def.then != null)
+                app.run(def.then, scope, def.w);
+        }
+        catch (e) {
+            app.warn(`event \`${def.name}\` could not be applied: ${e.message}`, payload);
+        }
+    }
+    /** Applies the event's change message; false when the payload lacks what it needs. */
+    change(def, name, scope, payload) {
+        const app = this.app;
+        const r = app.resource(name);
+        const paginated = !!app.ir.resources.find((x) => x.name === name)?.paginate;
+        switch (def.op) {
+            case 'refetch':
+                void r.refetch(scope.$p);
+                break;
+            case 'upsert': {
+                const item = def.item != null ? app.fns[def.item](scope) : payload;
+                if (item == null || typeof item !== 'object') {
+                    if (def.fallback !== 'refetch')
+                        return false;
                     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;
+                else if (paginated && !r.has(item))
+                    void r.refetch();
+                else
+                    r.upsert(clean(item));
+                break;
+            }
+            case 'patch': {
+                if (r.isCollection && !this.hasKey(r.key, scope.$p, def))
+                    return false;
+                const key = r.keyOf(scope.$p);
+                if (!r.isCollection || r.has(key))
                     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;
-                }
+                break;
+            }
+            case 'remove': {
+                if (r.isCollection && !this.hasKey(r.key, scope.$p, def))
+                    return false;
+                r.remove(r.keyOf(scope.$p));
+                break;
             }
         }
-        catch (e) {
-            app.warn(`event \`${def.name}\` could not be applied: ${e.message}`, payload);
-        }
+        return true;
     }
     hasKey(fields, payload, def) {
         const missing = fields.filter((f) => payload[f] === undefined);
@@ -203,9 +205,21 @@ const sse = {
         let alive = true;
         app.addCleanup(() => { alive = false; });
         app.env.queueMicrotask(() => {
-            if (alive)
-                for (const def of app.ir.syncs)
-                    new Connection(app, def).start();
+            if (!alive)
+                return;
+            // one connection per resolved stream URL, however many <sn-sync> elements use it
+            const conns = new Map();
+            for (const def of app.ir.syncs) {
+                const base = app.scopeOf(def.scope ?? -1);
+                const url = app.url(def.src, base);
+                let c = conns.get(url);
+                if (!c)
+                    conns.set(url, c = new Connection(app, url));
+                for (const e of def.events)
+                    c.subs.push([e, base]);
+            }
+            for (const c of conns.values())
+                c.start();
         });
     },
 };

package/html-custom-data.json

@@ -75,7 +75,7 @@
     },
     {
       "name": "sn-event",
-      "description": "maps one server event to a change message; child of <sn-sync>",
+      "description": "maps one server event to a change message; child of <sn-sync>. `then` is a handler run after the change (payload fields and the state around the sync in scope), e.g. close('detail'); with `then`, `resource` and `op` may be left out",
       "attributes": [
         {
           "name": "name"
@@ -98,6 +98,9 @@
         {
           "name": "fallback"
         },
+        {
+          "name": "then"
+        },
         {
           "name": "type"
         }

package/llms.txt

@@ -45,13 +45,14 @@ Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `
 
 - `<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-event>` `name`, `resource`, `op`, `item`, `set`, `when`, `fallback`, `then`, `type`: maps one server event to a change message; child of <sn-sync>. `then` is a handler run after the change (payload fields and the state around the sync in scope), e.g. close('detail'); with `then`, `resource` and `op` may be left out
 - `<sn-include>` `src`: inlines a partial at build time
 
 ## Expressions and scope
 
 - Attribute values are JavaScript expressions, checked at build time. Value expressions (text, attr, class, show, for, if, key, body, state, URL interpolations) cannot assign, use `++`, `delete`, `await` or `import()`.
 - Handlers (`data-sn-on-*`, `then`, `catch`) are statements separated by `;`: assignments to state, `$url.<param>` and `$locale`, and calls. No declarations or loops.
+- `then` on `<sn-event>` is a handler run after the event's change is applied: payload fields are bare names, the state around the `<sn-sync>` is in scope and assignable, store functions work (`close('id')` names its dialog: there is no element). With `then`, `resource` and `op` may be left out.
 - `data-sn-optimistic` may only call `patch`, `upsert`, `remove`.
 - A name resolves innermost first: loop variables, then the nearest `data-sn-state`, then resources, then magic names, helpers and store functions, then JavaScript globals. Browser APIs (`window`, `document`, `fetch`, timers, …) are refused: use an island.
 - Resources are read-only: copy an item with `structuredClone(c)` to edit it, write with `patch()`.
@@ -180,14 +181,21 @@ test('saves the draft and upserts the result', async () => {
 ```html
 <sn-resource name="people" src="/api/people" key="id" order="name"></sn-resource>
 
-<sn-sync src="/api/events">
-  <sn-event name="person_updated" resource="people" op="upsert" item="person" fallback="refetch"></sn-event>
-  <sn-event name="person_removed" resource="people" op="remove"></sn-event>
-</sn-sync>
+<main data-sn-state="{ sel: null }">
+  <sn-sync src="/api/events">
+    <sn-event name="person_updated" resource="people" op="upsert" item="person" fallback="refetch"></sn-event>
+    <!-- after the removal: close the dialog if it shows that person -->
+    <sn-event name="person_removed" resource="people" op="remove"
+              then="sel?.id === id && (sel = null, close('person'))"></sn-event>
+  </sn-sync>
 
-<ul>
-  <template data-sn-for="p in people"><li data-sn-text="p.name"></li></template>
-</ul>
+  <ul>
+    <template data-sn-for="p in people">
+      <li><button data-sn-on-click="sel = p; showModal('person')" data-sn-text="p.name"></button></li>
+    </template>
+  </ul>
+  <dialog id="person"><h2 data-sn-text="sel?.name"></h2></dialog>
+</main>
 ```
 
 ```ts
@@ -207,6 +215,24 @@ test('applies server events to the list', async () => {
   await flush();
   expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['Ada']);
 });
+
+test('a removed person closes the dialog that shows them', async () => {
+  const requests = mockRequests({ 'GET /api/people': [{ id: 1, name: 'Bob' }, { id: 2, name: 'Ada' }] });
+  const stream = mockStream();
+  const { root, flush, settle } = await render(page, { requests, streams: { '/api/events': stream } });
+  await settle();
+  root.querySelector('button')!.click();   // Ada
+  await flush();
+  const dialog = root.querySelector('dialog')!;
+  expect(dialog.open).toBe(true);
+
+  stream.emit('person_removed', { id: 1 });
+  await flush();
+  expect(dialog.open).toBe(true);
+  stream.emit('person_removed', { id: 2 });
+  await flush();
+  expect(dialog.open).toBe(false);
+});
 ```
 
 ### Optimistic toggle
@@ -616,7 +642,7 @@ test('sinter check: arguments are checked against the actions', () => {
 - `sinter({ openapi: 'openapi.yml' })`: resources without `type` are matched to a GET operation by `src` (server prefix stripped, `{…}` matches a path parameter) and typed from its JSON response at `items`. Every build then checks `items`/`total` against the schema (SN308) and query parameter names (SN505).
 - State takes a JSDoc cast where the literal is not enough: `data-sn-state="{ editing: /** @type {Contact|null} */ (null) }"`.
 - Actions matched in the spec: `data-sn-body` is checked against the request schema, `$result` in `then` has the response type.
-- `<sn-event … type="ContactEvent">` types the payload; `item` must fit the resource's item, `set` part of it; `cursor` reads the item. No `type` on an event with payload expressions is warning SN506.
+- `<sn-event … type="ContactEvent">` types the payload; `item` must fit the resource's item, `set` part of it, and `then` is checked against it; `cursor` reads the item. No `type` on an event with payload expressions is warning SN506.
 - Errors are SN208 at the HTML position, with TypeScript's message. Null checks are off. In tests: `checkPage(html, { files, openapi })` from `@tiaforge-ui/sinter/check`.
 
 ## Deploying streams

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiaforge-ui/sinter",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",