sygnal 5.4.0 → 6.0.0

package/src/extra/persist.ts

@@ -0,0 +1,133 @@
+import {warn} from './diagnostics/legacy';
+
+/*
+ * PLAN-4 GS-5 (D114): state persistence for the root component, as a helper value:
+ *
+ *   TodoApp.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'], version: 2, migrate })
+ *
+ * The core has no persistence code: a root component calls `persist.setup(this)` once, in its
+ * root setup (src/core/runtime.ts rootShim); an app that never imports persist() pays 0 B.
+ *
+ * - Stored as JSON `{ version, state }` under `key`; `state` has the picked top-level keys
+ *   (`pick`), or all but `omit` and the calculated fields. A `uses` key whose behavior is marked
+ *   `persist: false` (sortable: drag state) is left out of both the save and the restore (the root's own
+ *   `uses` only: a sub-component's or Collection item's behavior slice is part of its data, 3-L G-476). `format: 'plain'` (4-G1, D143) stores
+ *   that object itself, with no envelope; `version` / `migrate` then don't apply (a type error;
+ *   ignored here), and a stored value that isn't an object is ignored.
+ * - Restore: a synchronous read before INITIALIZE, merged into initialState, so the restore is
+ *   part of the initial-state action. A stored `version` other than `version` (default 1) goes
+ *   through `migrate(old, fromVersion)`; without migrate, or when it returns nothing, the entry
+ *   is ignored. Hydrating server HTML, the restore is a RESTORE action after the first state
+ *   instead, so the first render matches the server's. Hydrating: the `hydrate` option when given,
+ *   else the integration's `__hydrate` source (Astro: a server-rendered island; Vike: a hydration),
+ *   else whether run()'s mount point (its `__m` source) starts with renderToString's markup (the
+ *   root element carries `data-sygnal-ssr`; 3-R).
+ * - Writes: debounced (`debounceMs`, default 100), skipped when the stored text is the same,
+ *   flushed on `pagehide` and on dispose.
+ * - `PERSIST: { clear: true }` in any model entry's object form (a value or a function of
+ *   (state, data)) removes the stored copy; the state that same action produces isn't written
+ *   (later changes are). The entry's PERSIST sink is turned into an EFFECT here, so it needs no
+ *   driver. An 'ACTION | PERSIST' key (non-canonical) isn't handled (3-B2).
+ * - `sync: true`: another tab's write is applied through RESTORE (the `storage` event, or an
+ *   adapter's `subscribe(fn)`).
+ * - `storage`: 'local' (default), 'session', or a synchronous { getItem, setItem, removeItem }
+ *   adapter (optionally with subscribe). renderComponent passes its fake stores as the
+ *   `__storage` source ({ local, session, f: flush functions t.settle() calls }).
+ * - Failures (unreadable entry, migrate throws, quota) are SYG642 (warn, printed in production
+ *   too), once per kind (restore / save / clear; a save that works again re-arms it); the app
+ *   continues on initialState / unsaved, and a failed save is retried at the next change.
+ */
+const g: any = globalThis;
+
+export const setupPersist = (c: any, o: any): void => {
+  const {key, pick, omit, version = 1, migrate, sync, debounceMs = 100} = o, plain = o.format == 'plain', src = c.sources, m = src.__m;
+  const env = src.__storage, calc = c.calculated || {};
+  // hydrating: the option, else the integration's signal (__hydrate: Astro, Vike), else whether
+  // run()'s mount point starts with renderToString's markup (its root element is marked; a
+  // client-only app's loading placeholder isn't server markup)
+  const hydrate = o.hydrate ?? src.__hydrate ?? !!(typeof m == 'string' ? g.document?.querySelector(m) : m)?.firstElementChild?.hasAttribute('data-sygnal-ssr');
+  let S: any, t: any, last: any, raw: any, skip: any, off: any;
+  // (the docs link the message ends with explains the causes and fixes). Once per kind (restore,
+  // save, clear): a storage that throws on every write must not warn on every change; a save that
+  // works again re-arms the save report
+  const bad: any = {};
+  const fail = (what: string, e?: any) => bad[what] || (bad[what] = 1, warn('SYG642', c, `persist '${key}': ${what} failed`, undefined, e));
+  // a behavior's slice marked `persist: false` (UI state: sortable's drag) is never saved or restored (3-H G-452)
+  const uses = c.view?.uses || {};
+  const only = (s: any) => {
+    const out: any = {};
+    for (const k in s) if ((pick ? pick.includes(k) : !omit?.includes(k)) && !(k in calc) && uses[k]?.persist !== false) out[k] = s[k];
+    return out;
+  };
+  const read = (r: any) => {
+    try {
+      if (r == null) return;
+      const j = JSON.parse(r);
+      if (plain) return j && typeof j == 'object' && !Array.isArray(j) ? only(j) : undefined;
+      const {version: v = 1, state} = j, s = v === version ? state : migrate && migrate(state, v);
+      return s && only(s);
+    } catch (e) { fail('restore', e); }
+  };
+  const write = () => {
+    clearTimeout(t); t = 0;
+    const r = JSON.stringify(plain ? only(last) : {version, state: only(last)}), p = raw;
+    // a failed save is retried at the next change (raw stays the stored text)
+    if (r != raw) try { raw = r; S.setItem(key, r); bad.save = 0; } catch (e) { raw = p; fail('save', e); }
+  };
+  const clear = () => {
+    clearTimeout(t); t = 0; skip = 1; raw = null;
+    setTimeout(() => skip = 0);
+    try { S?.removeItem(key); } catch (e) { fail('clear', e); }
+  };
+  const send = (d: any) => d && c.action$.shamefullySendNext({type: 'RESTORE', data: d});
+  // PERSIST sinks become EFFECTs (no driver); a model RESTORE entry replaces the built-in one
+  const wrap = (p: any, e?: any) => (...a: any[]) => { const r = e?.(...a), v = typeof p == 'function' ? p(...a) : p; v?.clear && clear(); return r; };
+  const model: any = {RESTORE: (s: any, d: any) => ({...s, ...d})};
+  for (const k in c.model) {
+    let v = c.model[k];
+    if (v && typeof v == 'object' && 'PERSIST' in v) { const {PERSIST, ...rest} = v; v = {...rest, EFFECT: wrap(PERSIST, rest.EFFECT)}; }
+    model[k] = v;
+  }
+  c.model = model;
+  try { S = typeof o.storage == 'object' ? o.storage : (env || g)[(o.storage || 'local') + (env ? '' : 'Storage')]; } catch (_) {}
+  if (!S) return;
+  try {
+    raw = S.getItem(key);
+    if (!hydrate) { const r = read(raw); if (r) c.initialState = {...c.initialState, ...r}; }
+  } catch (e) { fail('restore', e); }
+  const state$ = c.sources[c.stateSourceName].stream;
+  let first = 1;
+  const L = {next: (s: any) => {
+    last = s;
+    // the initial state (restored or not) isn't written back. hydrate: it is the server's; restore
+    // once it has rendered (the DOM driver patches before this listener hears the vtree)
+    if (first) {
+      first = 0;
+      let once = hydrate;
+      const v$ = c.vdom$, l = {next: () => once && setTimeout(() => (v$.removeListener(l), send(read(raw))), once = 0)};
+      return hydrate && v$.addListener(l);
+    }
+    if (!skip) clearTimeout(t), t = setTimeout(write, debounceMs);
+  }};
+  state$.addListener(L);
+  const flush = () => t && write();
+  const onSync = (k: any, v: any) => { if (k == key && v != raw) send(read(raw = v)); };
+  const onStorage = (e: any) => (!e.storageArea || e.storageArea == S) && onSync(e.key, e.newValue);
+  if (sync) off = S.subscribe ? S.subscribe(onSync) : (g.addEventListener?.('storage', onStorage), () => g.removeEventListener?.('storage', onStorage));
+  g.addEventListener?.('pagehide', flush);
+  env?.f.add(flush);
+  c._dispose$.addListener({next: () => {
+    flush();
+    state$.removeListener(L);
+    off?.();
+    g.removeEventListener?.('pagehide', flush);
+    env?.f.delete(flush);
+  }});
+};
+
+/**
+ * `App.persist = persist({ key, pick | omit, version, migrate, format, storage, sync, hydrate, debounceMs })`:
+ * the root component's state, saved to localStorage (or sessionStorage, or an adapter) and
+ * restored at startup. Only an app that imports it pays for it.
+ */
+export const persist = (o: any) => ({options: o, setup: (c: any) => setupPersist(c, o)});

package/src/extra/pwa.ts

@@ -118,7 +118,7 @@ export function makeServiceWorkerDriver(
 
 let _onlineCleanup: (() => void) | undefined;
 
-export const onlineStatus$: Stream<boolean> = xs.create<boolean>({
+export const onlineStatus$: Stream<boolean> = /*#__PURE__*/ xs.create<boolean>({
   start(listener: Listener<boolean>) {
     if (typeof window === 'undefined') {
       listener.next(true);

package/src/extra/queryCache.ts

@@ -0,0 +1,107 @@
+import {onBrowserSignals} from './browserSignals';
+import {withQuery, hit} from './fetchDriver';
+
+/*
+ * queryCache(options?) (PLAN-3 D88, 5-5): the opt-in query cache of makeFetchDriver, in its own
+ * export so apps that only make requests don't pay for it:
+ *
+ *   makeFetchDriver({ cache: queryCache({ staleTime, gcTime, refetchOnFocus, refetchOnReconnect, initial }) })
+ *
+ * It owns the entries (key → { k, q (the request), v (data), at (fetched at), s (marked stale),
+ * n (resources using it), g (gc timer) }), gc, freshness (the stale-while-revalidate decision),
+ * the fetches identical requests share (de-duplication, `f`), entry invalidation, the focus /
+ * reconnect trigger and SSR seeding. The driver calls its hooks (key, fresh, get, put, use,
+ * inval, on, list) and keeps resources, polling, retries and validation.
+ *
+ * - Keys: method + URL as written (the driver's baseUrl left out, query sorted) + body + parse.
+ *   Cacheable: a resource's GET/HEAD request, and any request with `cache: true` or `staleTime`
+ *   (`cache: false` opts out; a `parse` function / 'response' or a non-string body never is).
+ * - SSR seeding (H-7): `dehydrate()` returns a JSON-safe snapshot `[{ key, data, updatedAt, tags }]`
+ *   of the entries with data; `hydrate(snapshot)` / `queryCache({ initial })` write it back (an
+ *   entry newer than the snapshot's is kept). `set(request, data)` writes one entry (a loader on
+ *   the server). Entries keep their `updatedAt`, so a seeded entry is fresh for `staleTime`.
+ * - `prefetch(request)`: the attached driver (the last makeFetchDriver given this cache) fetches
+ *   the request into the cache without a reply, like the `{ prefetch }` sink command.
+ */
+
+const IDEMPOTENT = /^(GET|HEAD)$/i;
+
+export function queryCache(o: any = {}): any {
+  const map = new Map<string, any>();
+  const now = () => Date.now();
+  const gc = (E: any) => {
+    clearTimeout(E.g);
+    const ms = o.gcTime ?? 3e5;
+    // unref: a server's seeded cache never keeps Node alive
+    if (ms < 1 / 0) (E.g = setTimeout(() => E.n || map.delete(E.k), ms) as any).unref?.();
+  };
+  const entry = (k: string, q: any) => {
+    let E = map.get(k);
+    if (!E) map.set(k, (E = {k, q, n: 0}));
+    return E;
+  };
+  // the key of a cacheable request (else undefined); `res`: a resource's
+  const key = (q: any, res?: any) => {
+    if (typeof q == 'string') q = {url: q};
+    const {method, json, body, parse, query} = q;
+    const m = (method || (json !== undefined || body !== undefined ? 'POST' : 'GET')).toUpperCase();
+    const b = json !== undefined ? JSON.stringify(json) : body ?? '';
+    if (q.cache === false || typeof b != 'string' || typeof parse == 'function' || parse == 'response' ||
+      !(q.cache || q.staleTime != null || (res && IDEMPOTENT.test(m)))) return;
+    return [m, withQuery(q.url ?? '', query, 1), b, parse].join(' ').trim();
+  };
+  const fresh = (k: any, q: any) => {
+    const E = map.get(k);
+    return E?.at > 0 && !E.s && now() - E.at < (q?.staleTime ?? o.staleTime ?? 0);
+  };
+  const put = (k: string, q: any, v: any, at = now()) => {
+    const E = entry(k, q);
+    E.v = v;
+    E.at = at;
+    E.s = 0;
+    E.q = q;
+    E.n || gc(E);
+  };
+  const C: any = {
+    key,
+    fresh,
+    put,
+    get: (k: any) => map.get(k),
+    // the fetches identical cacheable requests share (the driver's flight records), key → flight
+    f: new Map(),
+    // resource R now uses key k (or none): the entries' subscriber counts, gc when unused
+    use: (R: any, k?: string) => {
+      if (R.k === k) return;
+      const O = map.get(R.k);
+      if (O && !--O.n) gc(O);
+      if ((R.k = k) !== undefined) {
+        const E = entry(k as string, R.q);
+        E.n++;
+        clearTimeout(E.g);
+      }
+    },
+    // D80: marks the matching entries stale (`dry`: only counts them)
+    inval: (x: any, dry?: any) => {
+      let n = 0;
+      map.forEach(E => { if (hit(x, E.q)) { n++; dry || (E.s = 1); } });
+      return n;
+    },
+    // focus / reconnect call `fn` (the driver refetches its stale mounted resources); `on`: the
+    // test fake's signal source
+    on: (on: any, fn: () => void) => (on || onBrowserSignals)((sig: string) => {
+      o[sig == 'focus' ? 'refetchOnFocus' : 'refetchOnReconnect'] === false || fn();
+    }),
+    list: () => [...map.values()].map(E => ({key: E.k, age: E.at && now() - E.at, stale: !fresh(E.k, E.q), subscribers: E.n, data: E.v, tags: E.q?.tags})),
+    dehydrate: () => [...map.values()].filter(E => E.at > 0).map(E => ({key: E.k, data: E.v, updatedAt: E.at, tags: E.q?.tags})),
+    hydrate: (snap: any) => snap?.forEach?.((e: any) => {
+      if (!(map.get(e.key)?.at >= e.updatedAt)) put(e.key, {url: e.key.split(' ')[1], tags: e.tags}, e.data, e.updatedAt);
+    }),
+    set: (q: any, data: any) => {
+      const k = key(q, 1);
+      if (k !== undefined) put(k, typeof q == 'string' ? {url: q} : q, data);
+    },
+    prefetch: (q: any) => C.d?.({prefetch: q}),
+  };
+  C.hydrate(o.initial);
+  return C;
+}

package/src/extra/reducers.ts

@@ -17,7 +17,7 @@
  *   set((state, title) => ({ title }))
  */
 export function set<S = any>(
-  partial: Partial<S> | ((state: S, data: any, next: Function, props: any) => Partial<S>)
+  partial: (Partial<S> & object) | ((state: S, data: any, next: Function, props: any) => Partial<S>)
 ): (state: S, data: any, next: Function, props: any) => S {
   if (typeof partial === 'function') {
     return (state, data, next, props) => ({

package/src/extra/reduxDevtools.ts

@@ -0,0 +1,92 @@
+/**
+ * PLAN-4 3-E (GS-10 stretch): a dev-only bridge to the Redux DevTools extension
+ * (window.__REDUX_DEVTOOLS_EXTENSION__), in 'sygnal/devtools'. Sends each recorded action
+ * (./devtoolsActions; built-in ones left out) with the root's state after it, as
+ * `{ type: '<Component>/<ACTION>', payload, cause, instance }`. Jump to state / action in the
+ * extension replaces the root's state (the Sygnal DevTools time-travel path). sygnal/vite calls it
+ * in dev with sygnal({ devtools: { redux: true } }).
+ */
+import {recordActions, onAction, resolveInstance, preview} from './devtoolsActions'
+import type {DevtoolsAction} from './devtoolsActions'
+
+export interface ReduxDevtoolsOptions {
+  /** the instance name in the extension (default 'Sygnal') */
+  name?: string
+  /** which actions to send (default: all but 'built-in' ones) */
+  filter?: (action: DevtoolsAction) => boolean
+}
+
+const clone = (s: any) => preview(s)
+
+let shared: (() => void) | undefined
+
+/**
+ * Connect the app's root (run()'s result, a component, an instance id; default: the newest root)
+ * to the Redux DevTools extension. Returns a disconnect function; does nothing without the
+ * extension.
+ */
+export function connectReduxDevtools(target?: any, options?: ReduxDevtoolsOptions): () => void {
+  // the default connection (sygnal/vite may inject the call in several files) is made once
+  if (target === undefined && options === undefined) {
+    if (!shared) {
+      const off = connect(undefined, {})
+      shared = () => { off(); shared = undefined }
+    }
+    return shared
+  }
+  return connect(target, options || {})
+}
+
+function connect(target: any, options: ReduxDevtoolsOptions): () => void {
+  const ext = typeof window != 'undefined' && (window as any).__REDUX_DEVTOOLS_EXTENSION__
+  if (!ext || typeof ext.connect != 'function') return () => {}
+  recordActions()
+  const conn = ext.connect({name: options.name || 'Sygnal', features: {jump: true, pause: true, export: true}})
+  const keep = options.filter || ((a: DevtoolsAction) => a.cause != 'built-in')
+  let root: any, started = false, timer: any = null
+  const queue: DevtoolsAction[] = []
+
+  const rootOf = () => {
+    if (!root || root.disposed || !root.c) root = resolveInstance(target)
+    return root
+  }
+  const flush = () => {
+    timer = null
+    const r = start()
+    if (!r) return
+    for (const a of queue.splice(0)) {
+      const state = a.instance === r.id && 'after' in a ? a.after : r.c.currentState
+      conn.send({type: `${a.component}/${a.type}`, payload: preview(a.data), cause: a.cause, instance: a.instance}, clone(state))
+    }
+  }
+  const start = () => {
+    const r = rootOf()
+    if (r && !started) { started = true; conn.init(clone(r.c.currentState)) }
+    return r
+  }
+  start()
+  const off = onAction((a, kind) => {
+    if (kind == 'reset') { queue.length = 0; started = false; start(); return }
+    if (kind != 'add') return
+    // connected before run() (sygnal/vite): the root's first action, its state still the initial one
+    if (!started) start()
+    if (!keep(a!)) return
+    queue.push(a!)
+    if (timer === null) timer = setTimeout(flush, 0)
+  })
+  const unsubscribe = conn.subscribe((msg: any) => {
+    if (msg?.type !== 'DISPATCH' || !msg.state) return
+    const t = msg.payload?.type
+    if (t !== 'JUMP_TO_STATE' && t !== 'JUMP_TO_ACTION') return
+    const r = rootOf()
+    const dt = (window as any).__SYGNAL_DEVTOOLS__
+    if (!r || !dt || typeof dt._timeTravel != 'function') return
+    try { dt._timeTravel({componentId: Number(r.id), componentName: r.name, state: JSON.parse(msg.state)}) } catch (_) { /* a bad state from the extension */ }
+  })
+  return () => {
+    off()
+    if (timer !== null) clearTimeout(timer)
+    if (typeof unsubscribe == 'function') unsubscribe()
+    try { ext.disconnect?.() } catch (_) { /* ignore */ }
+  }
+}

package/src/extra/replies.ts

@@ -0,0 +1,54 @@
+import xs from 'xstream';
+import {error as logError} from './diagnostics/legacy';
+
+/*
+ * PLAN-3 reply actions: the shared part of every driver that answers a request
+ * with the sender's own actions (makeFetchDriver, driverFromAsync, the socket driver).
+ *
+ * - The core stamps each object a component sends to a source marked
+ *   `__sygnalReplies: true` with the sending instance (`__emitterId`, the same
+ *   non-enumerable stamp EVENTS gets), and merges `source.replies(instance)` into
+ *   that instance's actions.
+ * - A request that names `ok` / `error` actions from a stamped sender gets reply actions:
+ *   the driver answers it with `reply(sender, type, data)`, which reaches exactly
+ *   that instance (never select()/errors()).
+ * - When the instance stops listening (disposed), `onStop(sender)` lets the
+ *   driver abort what it still has in flight for it.
+ */
+
+const SENDER = '__emitterId';
+
+/** the instance that sent a request (undefined when it wasn't sent by a component) */
+export const senderOf = (req: any) => req[SENDER];
+
+/** `to` (a copy of `from`) with `from`'s sender stamp (a spread drops non-enumerables) */
+export const keepSender = (from: any, to: any) => {
+  if (from[SENDER] !== undefined) Object.defineProperty(to, SENDER, {value: from[SENDER]});
+  return to;
+};
+
+/**
+ * D57: a request object with a `then` / `catch` key is a thenable (it breaks `await`), so
+ * reply-action drivers refuse it (SYG610). True when the request may be sent.
+ */
+export const allowed = (req: any, driver: string) =>
+  !('then' in req || 'catch' in req) ||
+  logError('SYG610', req.__emitterName, `${driver}: request not sent: it has a 'then'/'catch' key`, "Use ok: 'ACTION' / error: 'ACTION'", req);
+
+/** the reply-action half of a driver's source */
+export const makeReplies = (onStop?: (sender: any) => void) => {
+  const to = new Map<any, any>();
+  return {
+    replies: {
+      __sygnalReplies: true,
+      replies: (sender: any) => xs.create<any>({
+        start: l => { to.set(sender, l); },
+        stop: () => { to.delete(sender); onStop?.(sender); },
+      }),
+    },
+    /** deliver `{ type, data }` to the sender's actions (dropped when it's gone) */
+    reply: (sender: any, type: any, data: any) => { to.get(sender)?.next({type, data}); },
+    /** whether the sender listens to its replies now (a reply to it would not be dropped) */
+    listening: (sender: any) => to.has(sender),
+  };
+};