sygnal 5.3.7 → 6.0.0

package/src/extra/driverFactories.ts

@@ -1,4 +1,5 @@
 import xs, {Stream} from 'xstream';
+import {senderOf, allowed, makeReplies} from './replies';
 
 interface DriverFromAsyncOptions {
   selector?: string;
@@ -8,10 +9,46 @@ interface DriverFromAsyncOptions {
   post?: (val: any, incoming?: any) => any;
 }
 
+/**
+ * Create a driver from a promise-returning function.
+ *
+ * Each value the app sends to the driver calls the function (arguments picked
+ * by `args`, after `pre`). The resolved value, after `post`, is delivered as
+ * `{ [return]: value, [selector]: request[selector] }` (defaults:
+ * `{ value, category }`) and read with `source.select(category)`. A promise
+ * that resolves to `null`/`undefined` is delivered the same way. Replies that
+ * resolve before any `select()` listener exists (a BOOTSTRAP request, say) are
+ * held and delivered once the first one subscribes.
+ *
+ * Errors: if the function's promise (or a promise returned by `post`)
+ * rejects, or `post` throws, the error is delivered on `source.errors()`,
+ * never on `select()`:
+ *
+ * ```js
+ * // payload: { error, category: request.category, request }
+ * intent: ({ QUOTE }) => ({
+ *   GOT_QUOTE:   QUOTE.select('quote'),
+ *   QUOTE_ERROR: QUOTE.errors('quote'),   // or .errors() / .errors(e => ...)
+ * })
+ * ```
+ *
+ * `errors(selector?)` filters like `select()`: no argument = all errors, a
+ * string matches the request's selector property, a function is a predicate on
+ * the error payload. An error no errors() listener matches is logged with
+ * console.error. Errors that occur before the first errors() listener
+ * subscribes (a BOOTSTRAP request) are held like early replies.
+ *
+ * Reply actions (PLAN-3): a request object a component sends with `ok` /
+ * `error` action names gets its outcome as that action, on exactly the sending
+ * instance (never on select()/errors()): `ok` data is the resolved value (after
+ * `post`), `error` data `{ error, request }`. A request naming only one of them
+ * sends the other outcome down select()/errors(). A reply for a disposed
+ * instance is dropped. Requests with a `then` / `catch` key are refused (SYG610).
+ */
 function driverFromAsync(
   promiseReturningFunction: (...args: any[]) => Promise<any>,
   opts: DriverFromAsyncOptions = {}
-): (fromApp$: Stream<any>) => {select: (selector?: any) => Stream<any>} {
+): (fromApp$: Stream<any>) => {select: (selector?: any) => Stream<any>; errors: (selector?: any) => Stream<any>; [k: string]: any} {
   const {
     selector: selectorProperty = 'category',
     args: functionArgs = 'value',
@@ -39,17 +76,88 @@ function driverFromAsync(
   }
 
   return (fromApp$: Stream<any>) => {
+    // G-069: a reply can resolve before anything has subscribed to select() (e.g. a
+    // BOOTSTRAP request to an instantly-resolving promise under run()). Such replies are
+    // buffered (at most EARLY_REPLY_LIMIT, oldest dropped) until the first select()
+    // listener subscribes, then delivered in order on a microtask, so every select()
+    // wired in the same pass sees them. After that, a reply that arrives while no one
+    // listens is dropped, as with any xstream source.
+    const EARLY_REPLY_LIMIT = 100;
     let sendFn: ((val: any) => void) | null = null;
+    let started = false;
+    let pending: any[] = [];
+    const flush = () => {
+      const queued = pending;
+      pending = [];
+      queued.forEach(reply => sendFn?.(reply));
+    };
+    const deliver = (reply: any) => {
+      if (!started || pending.length > 0) {
+        pending.push(reply);
+        if (pending.length > EARLY_REPLY_LIMIT) pending.shift();
+        return;
+      }
+      sendFn?.(reply);
+    };
 
     const toApp$ = xs.create<any>({
       start: (listener) => {
         sendFn = listener.next.bind(listener);
+        if (!started) {
+          started = true;
+          if (pending.length > 0) queueMicrotask(flush);
+        }
+      },
+      stop: () => {
+        sendFn = null;
       },
-      stop: () => {},
     });
 
+    // Active errors(selector) streams (1H-6): an error goes to the ones it matches, and is
+    // logged when none matches.
+    const errorSubs = new Set<{listener: any; selector: any}>();
+    const matches = (selector: any, val: any) =>
+      selector === undefined ||
+      (typeof selector === 'function' ? selector(val) : val?.[selectorProperty] === selector);
+    const filterBy = (stream: Stream<any>, selector?: any) =>
+      selector === undefined ? stream : stream.filter((val: any) => matches(selector, val));
+    const errMsg = `Error in driver created using driverFromAsync(${functionName})`;
+    const dispatchError = (val: any) => {
+      let handled = false;
+      errorSubs.forEach(sub => {
+        let hit = false;
+        try { hit = matches(sub.selector, val); } catch (_) {}
+        if (hit) {
+          handled = true;
+          sub.listener.next(val);
+        }
+      });
+      if (!handled) console.error(`${errMsg}: ${val.error}`);
+    };
+    // G-092: like early replies, errors that occur before the first errors() listener
+    // subscribes are held (same limit) and dispatched on a microtask once it does. If
+    // nothing has subscribed by the next macrotask, they are dispatched (i.e. logged) then.
+    let errStarted = false;
+    let pendingErrors: any[] = [];
+    const flushErrors = () => {
+      errStarted = true;
+      const queued = pendingErrors;
+      pendingErrors = [];
+      queued.forEach(dispatchError);
+    };
+
+    // 3E/R11: set by the source's dispose(), which Cycle's engine calls on teardown just
+    // before it completes the sink proxies; that completion is expected, not worth a warning.
+    let disposing = false;
+    const {replies, reply} = makeReplies();
+
     fromApp$.addListener({
       next: (incoming: any) => {
+        const isObject = typeof incoming === 'object' && incoming !== null;
+        if (isObject && !allowed(incoming, `driverFromAsync(${functionName})`)) return;
+        const sender = isObject ? senderOf(incoming) : undefined;
+        const ok = sender !== undefined && incoming.ok;
+        const error = sender !== undefined && incoming.error;
         const preProcessed = preFunction(incoming);
         let argArr: any[] = [];
         if (typeof preProcessed === 'object' && preProcessed !== null) {
@@ -64,62 +172,53 @@ function driverFromAsync(
             argArr = functionArgs.map((arg: string) => preProcessed[arg]);
           }
         }
-        const errMsg = `Error in driver created using driverFromAsync(${functionName})`;
-        promiseReturningFunction(...argArr)
-          .then((innerVal: any) => {
-            const constructReply = (rawVal: any) => {
-              let outgoing: any;
-              if (returnProperty === undefined) {
-                outgoing = rawVal;
-                if (typeof outgoing === 'object' && outgoing !== null) {
-                  outgoing[selectorProperty] = incoming[selectorProperty];
-                } else {
-                  console.warn(
-                    `The 'return' option for driverFromAsync(${functionName}) was not set, but the promise returned an non-object.  The result will be returned as-is, but the '${selectorProperty}' property will not be set, so will not be filtered by the 'select' method of the driver.`
-                  );
-                }
-              } else if (typeof returnProperty === 'string') {
-                outgoing = {
-                  [returnProperty]: rawVal,
-                  [selectorProperty]: incoming[selectorProperty],
-                };
-              } else {
-                throw new Error(
-                  `The 'return' option for driverFromAsync(${functionName}) must be a string.  Received ${typeof returnProperty}`
-                );
-              }
-              return outgoing;
-            };
-
-            if (typeof innerVal.then === 'function') {
-              innerVal
-                .then((innerOutgoing: any) => {
-                  const processedOutgoing = postFunction(innerOutgoing, incoming);
-                  if (typeof processedOutgoing.then === 'function') {
-                    processedOutgoing
-                      .then((innerProcessedOutgoing: any) => {
-                        sendFn!(constructReply(innerProcessedOutgoing));
-                      })
-                      .catch((err: any) => console.error(`${errMsg}: ${err}`));
-                  } else {
-                    sendFn!(constructReply(processedOutgoing));
-                  }
-                })
-                .catch((err: any) => console.error(`${errMsg}: ${err}`));
+        const constructReply = (rawVal: any) => {
+          let outgoing: any;
+          if (returnProperty === undefined) {
+            outgoing = rawVal;
+            if (typeof outgoing === 'object' && outgoing !== null) {
+              outgoing[selectorProperty] = incoming[selectorProperty];
             } else {
-              const processedOutgoing = postFunction(innerVal, incoming);
-              if (typeof processedOutgoing.then === 'function') {
-                processedOutgoing
-                  .then((innerProcessedOutgoing: any) => {
-                    sendFn!(constructReply(innerProcessedOutgoing));
-                  })
-                  .catch((err: any) => console.error(`${errMsg}: ${err}`));
-              } else {
-                sendFn!(constructReply(processedOutgoing));
-              }
+              console.warn(
+                `The 'return' option for driverFromAsync(${functionName}) was not set, but the promise returned an non-object.  The result will be returned as-is, but the '${selectorProperty}' property will not be set, so will not be filtered by the 'select' method of the driver.`
+              );
+            }
+          } else if (typeof returnProperty === 'string') {
+            outgoing = {
+              [returnProperty]: rawVal,
+              [selectorProperty]: incoming[selectorProperty],
+            };
+          } else {
+            throw new Error(
+              `The 'return' option for driverFromAsync(${functionName}) must be a string.  Received ${typeof returnProperty}`
+            );
+          }
+          return outgoing;
+        };
+        // Rejections (of the function, a thenable it resolves to, or post()) go to errors();
+        // an error no active errors() selector matches is logged, as before.
+        const reportError = (err: any) => {
+          if (error) return reply(sender, error, {error: err, request: incoming});
+          const val = {error: err, [selectorProperty]: incoming?.[selectorProperty], request: incoming};
+          if (errStarted) return dispatchError(val);
+          if (pendingErrors.push(val) === 1) setTimeout(flushErrors);
+          if (pendingErrors.length > EARLY_REPLY_LIMIT) pendingErrors.shift();
+        };
+        const isThenable = (val: any) => val != null && typeof val.then === 'function';
+        promiseReturningFunction(...argArr)
+          .then((innerVal: any) =>
+            isThenable(innerVal)
+              ? innerVal.then((innerOutgoing: any) => postFunction(innerOutgoing, incoming))
+              : postFunction(innerVal, incoming)
+          )
+          .then((val: any) => (ok ? val : constructReply(val)))
+          .then((outgoing: any) => {
+            try {
+              ok ? reply(sender, ok, outgoing) : deliver(outgoing);
+            } catch (err) {
+              console.error(`${errMsg}: ${err}`);
             }
-          })
-          .catch((err: any) => console.error(`${errMsg}: ${err}`));
+          }, reportError);
       },
       error: (err: any) => {
         console.error(
@@ -128,6 +227,7 @@ function driverFromAsync(
         );
       },
       complete: () => {
+        if (disposing) return;
         console.warn(
           `Unexpected completion of sink stream to driver created using driverFromAsync(${functionName})`
         );
@@ -135,10 +235,22 @@ function driverFromAsync(
     });
 
     return {
-      select: (selector?: any) => {
-        if (selector === undefined) return toApp$;
-        if (typeof selector === 'function') return toApp$.filter(selector);
-        return toApp$.filter((val: any) => val?.[selectorProperty] === selector);
+      dispose: () => {
+        disposing = true;
+      },
+      select: (selector?: any) => filterBy(toApp$, selector),
+      ...replies,
+      errors: (selector?: any) => {
+        let sub: any;
+        return xs.create<any>({
+          start: (listener) => {
+            errorSubs.add((sub = {listener, selector}));
+            if (!errStarted) queueMicrotask(flushErrors);
+          },
+          stop: () => {
+            errorSubs.delete(sub);
+          },
+        });
       },
     };
   };

package/src/extra/elementCommands.ts

@@ -0,0 +1,53 @@
+/*
+ * PLAN-4 GS-2: element commands, the built-in ELEMENT sink.
+ *
+ *   SUBMIT:    { STATE: validate, ELEMENT: (s) => (s.errors.email ? { focus: Email } : ABORT) },
+ *   OPEN_HELP: { ELEMENT: { showModal: HelpDialog } },
+ *
+ * A command is `{ <method>: target, ...options }`: the FIRST key is the method, the other keys
+ * are its options (D118); an array sends several, in order. The target (a control or a
+ * selector) is resolved in the SENDING instance's own DOM source, so isolation applies (a
+ * Collection item reaches only its own elements; a parent doesn't reach its children's).
+ *
+ * The method: D102 first, a control whose spec object declares `commands` runs
+ * `commands[method](element, options)` (it overrides a native method of the same name; only the
+ * control itself carries a spec, a template-string selector doesn't). A widget host
+ * (src/extra/widget.ts) carries its widget's commands, which win the same way for a selector
+ * target (PLAN-5 D196: `{ focus: '.editor' }` runs the widget's `focus`). Then the element's own
+ * method: `close` gets `returnValue` as its argument (D118), `togglePopover` its `force` (a
+ * boolean, or no argument: a browser that only takes a boolean treats an object as true), every
+ * other method the options object (focus { preventScroll }, scrollIntoView { block, inline,
+ * behavior }, blur, select, click, showModal, show, showPopover, hidePopover; also play, pause, showPicker,
+ * requestSubmit, reset...). The core runs any method the element has (no list: it
+ * would cost ~60 B); the dev entry reports the ones that change the DOM Sygnal renders (SYG641).
+ *
+ * Timing: a command runs once the render it may depend on is on the page. The instance's DOM
+ * source emits after every DOM mutation of the app (a patch), so the command runs in a microtask
+ * after the next patch at which its target exists. When no patch comes (the action changed
+ * nothing that renders), it runs at the first 16 ms check instead; the checks repeat every 16 ms
+ * while the target is missing, about 1 s, then it is given up (SYG640 in dev). A disposed
+ * instance's pending commands are dropped. Without a DOM source nothing runs (SSR renders views
+ * without instances); a null command is skipped (ABORT is the way to send nothing).
+ *
+ * Failures (no match: SYG640; neither a spec command nor an element method: SYG641) go to the
+ * 'sygnal/diagnostics' dev entry through the core bridge (`elementCommand`), which words them;
+ * the core carries no message text. In production a failed command does nothing.
+ */
+export function runElementCommands(c: any, cmds: any): void {
+  const dom = c.sources[c.DOMSourceName];
+  if (dom) for (const cmd of ([] as any[]).concat(cmds)) if (cmd) {
+    const m = Object.keys(cmd)[0], {[m]: t, ...o} = cmd, s = dom.select('' + t).elements();
+    let els: any, n = 0, k = 0, l: any;
+    const run = (last?: any) => {
+      const e = !c._disposed && els?.[0], f = t?.spec?.commands?.[m] || e?.__sw?.w.commands[m];
+      if (!l || !e && !last) return;
+      s.removeListener(l);
+      clearInterval(i);
+      l = 0;
+      e && (f || e[m]) ? f ? f(e, o) : e[m](m == 'close' ? o.returnValue : m == 'togglePopover' ? o.force : o)
+        : (globalThis as any).__SYGNAL_DIAGNOSTICS__?.elementCommand?.(c, cmd, e);
+    }, i = setInterval(() => run(++k > 62), 16);
+    // the first value (the DOM as it is now) is skipped; the next ones follow a patch
+    s.addListener(l = {next: (x: any) => { els = x; n++ && queueMicrotask(run); }});
+  }
+}

package/src/extra/eventDriver.ts

@@ -1,5 +1,7 @@
 import xs, {Stream} from 'xstream';
 import {adapt} from '../cycle/run/adapt';
+// [diagnostics hook] no-op when diagnostics are off
+import {onBusEmit, onBusSelect} from './diagnostics/index';
 
 export interface EventBusSource {
   select(type?: string | string[]): any;
@@ -15,6 +17,7 @@ export default function eventBusDriver(out$: Stream<BusEvent>): EventBusSource {
 
   out$.subscribe({
     next: (event: BusEvent) => {
+      onBusEmit(event && event.type, (event as any)?.__emitterName);
       events.dispatchEvent(new CustomEvent('data', {detail: event}));
       if (typeof window !== 'undefined' && (window as any).__SYGNAL_DEVTOOLS__?.connected) {
         (window as any).__SYGNAL_DEVTOOLS__.onBusEvent(event);
@@ -26,6 +29,7 @@ export default function eventBusDriver(out$: Stream<BusEvent>): EventBusSource {
 
   return {
     select: (type?: string | string[]) => {
+      onBusSelect(type);
       const all = !type;
       const _type = Array.isArray(type) ? type : [type];
       let cb: ((e: Event) => void) | undefined;