@cplieger/ui 0.0.0 → 1.0.0-dev.1

package/src/actions/registry.ts

@@ -0,0 +1,259 @@
+import { signal, batch } from "../signal/signal.js";
+import { SignalMap } from "../signal/signal-map.js";
+
+import type { ActionInstance, RegistryListener } from "./types.js";
+
+const MAX_LOG_SIZE = 200;
+
+/** Only a dispatch that never settles can grow `inflight` past this; the
+ *  oldest is then reclaimed with a console.warn naming it. */
+const MAX_INFLIGHT = 1000;
+
+interface LogEntry {
+  instance: ActionInstance;
+  /** Monotonic stamp assigned at the dispatch id's FIRST record; preserved
+   *  across every transition so the recomposed log keeps first-record order. */
+  readonly seq: number;
+}
+
+// Disjoint lifetimes keep pending accounting from desyncing with log
+// eviction: `inflight` holds pending dispatches (reclaimed only past
+// MAX_INFLIGHT), `settled` terminal snapshots, latest per id, bounded to
+// MAX_LOG_SIZE by evicting the lowest `seq`. `seq`, stamped at an id's first
+// record, orders getActionLog(); pendingByName indexes `inflight`.
+const inflight = new Map<string, LogEntry>();
+const settled = new Map<string, LogEntry>();
+let seqCounter = 0;
+
+const listeners = new Set<RegistryListener>();
+const namedListeners = new Map<string, Set<RegistryListener>>();
+const pendingByName = new Map<string, Set<string>>();
+
+// Reactive mirrors of the pending state. The inflight table + its name index
+// remain the source of truth; these signals expose the derived counts so
+// isPending/pendingCount can be read reactively (e.g. by bindLoadingState's
+// effect).
+const pendingSigs = new SignalMap<number>();
+const pendingTotalSig = signal(0);
+
+/** Add `id` to the name index + refresh the signals. Call AFTER the inflight
+ *  mutation so `inflight.size` is current. */
+function indexPending(name: string, id: string): void {
+  let s = pendingByName.get(name);
+  if (s === undefined) {
+    s = new Set();
+    pendingByName.set(name, s);
+  }
+  s.add(id);
+  const size = s.size;
+  batch(() => {
+    pendingSigs.ensure(name, 0).value = size;
+    pendingTotalSig.value = inflight.size;
+  });
+}
+
+/** Remove `id` from the name index + refresh the signals. Call AFTER the
+ *  inflight mutation. No-op when the id was never indexed. */
+function unindexPending(name: string, id: string): void {
+  const s = pendingByName.get(name);
+  if (!s?.delete(id)) {
+    return;
+  }
+  const size = s.size;
+  if (size === 0) {
+    pendingByName.delete(name);
+  }
+  batch(() => {
+    pendingSigs.ensure(name, 0).value = size;
+    pendingTotalSig.value = inflight.size;
+  });
+}
+
+/** Evicts the lowest-seq (first-record order) entry. Map insertion order
+ *  alone is settle order, not first-record order (a long-pending dispatch
+ *  settles late), hence the linear scan. `protectId` shields the entry being
+ *  recorded right now: a long-lived pending that finally settles can carry
+ *  the lowest seq of the whole log and would otherwise evict itself. */
+function evictOldestSettled(protectId: string): void {
+  while (settled.size > MAX_LOG_SIZE) {
+    let oldestKey: string | undefined;
+    let oldestSeq = Infinity;
+    for (const [key, entry] of settled) {
+      if (key !== protectId && entry.seq < oldestSeq) {
+        oldestSeq = entry.seq;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey === undefined) {
+      return;
+    }
+    settled.delete(oldestKey);
+  }
+}
+
+/** Reclaims the oldest in-flight entry once the table exceeds MAX_INFLIGHT,
+ *  skipping `protectId` (a revived entry keeps its original, possibly-lowest
+ *  seq, and must not reclaim itself). Dropped outright, never moved to
+ *  `settled`: its status is still "pending" and the terminal log must not lie. */
+function reclaimLeakedPending(protectId: string): void {
+  if (inflight.size <= MAX_INFLIGHT) {
+    return;
+  }
+  let oldestKey: string | undefined;
+  let oldestSeq = Infinity;
+  for (const [key, entry] of inflight) {
+    if (key !== protectId && entry.seq < oldestSeq) {
+      oldestSeq = entry.seq;
+      oldestKey = key;
+    }
+  }
+  if (oldestKey === undefined) {
+    return;
+  }
+  const entry = inflight.get(oldestKey);
+  inflight.delete(oldestKey);
+  if (entry !== undefined) {
+    unindexPending(entry.instance.name, oldestKey);
+    console.warn(
+      `[actions] in-flight capacity exceeded (${String(MAX_INFLIGHT)} entries) — reclaiming oldest pending "${entry.instance.name}" (${oldestKey}). Check for dispatches that never settle.`,
+    );
+  }
+}
+
+/** Record a state transition. Each cell completes its map moves before
+ *  publishing signals, so a reentrant record from an effect sees coherent state:
+ *
+ *    status   | in inflight          | in settled             | unknown
+ *    pending  | overwrite (keep seq) | move back, re-index    | insert, index, watchdog
+ *    terminal | move to settled,     | overwrite (keep seq    | insert into settled,
+ *             | unindex              | and position)          | evict */
+export function record(instance: ActionInstance): void {
+  const { id } = instance;
+  if (instance.status === "pending") {
+    const inf = inflight.get(id);
+    if (inf !== undefined) {
+      inf.instance = instance;
+    } else {
+      const done = settled.get(id);
+      if (done !== undefined) {
+        settled.delete(id);
+        done.instance = instance;
+        inflight.set(id, done);
+        indexPending(instance.name, id);
+        reclaimLeakedPending(id);
+      } else {
+        seqCounter += 1;
+        inflight.set(id, { instance, seq: seqCounter });
+        indexPending(instance.name, id);
+        reclaimLeakedPending(id);
+      }
+    }
+  } else {
+    const inf = inflight.get(id);
+    if (inf !== undefined) {
+      // Entry must be fully moved before unindexPending publishes signals:
+      // reactive effects flush synchronously at that batch's end, and a
+      // reentrant same-id record from one must find it in `settled` (the
+      // revive cell) rather than minting a duplicate wrapper.
+      const indexedName = inf.instance.name;
+      inflight.delete(id);
+      inf.instance = instance;
+      settled.set(id, inf);
+      evictOldestSettled(id);
+      unindexPending(indexedName, id);
+    } else {
+      const done = settled.get(id);
+      if (done !== undefined) {
+        done.instance = instance;
+      } else {
+        seqCounter += 1;
+        settled.set(id, { instance, seq: seqCounter });
+        evictOldestSettled(id);
+      }
+    }
+  }
+  for (const fn of listeners) {
+    try {
+      fn(instance);
+    } catch (e) {
+      console.error("[actions] registry listener threw", e);
+    }
+  }
+  const named = namedListeners.get(instance.name);
+  if (named !== undefined) {
+    for (const fn of named) {
+      try {
+        fn(instance);
+      } catch (e) {
+        console.error("[actions] registry listener threw", e);
+      }
+    }
+  }
+}
+
+/** Subscribe to all action lifecycle events. */
+export function subscribe(fn: RegistryListener): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/** Subscribe to lifecycle events for a single action name. */
+export function subscribeByName(name: string, fn: RegistryListener): () => void {
+  let set = namedListeners.get(name);
+  if (set === undefined) {
+    set = new Set();
+    namedListeners.set(name, set);
+  }
+  set.add(fn);
+  const captured = set;
+  return () => {
+    captured.delete(fn);
+    if (captured.size === 0 && namedListeners.get(name) === captured) {
+      namedListeners.delete(name);
+    }
+  };
+}
+
+/** Read the recent action log. Useful for devtools integration and
+ *  debugging panels. Returns a snapshot of all live entries.
+ *
+ *  SECURITY/PRIVACY: each entry retains the dispatch's `args`, `result` and
+ *  `error` (up to MAX_LOG_SIZE settled entries plus every in-flight dispatch,
+ *  watchdog-bounded at MAX_INFLIGHT), and every listener receives them. A
+ *  definition whose args or result carry a secret, token or PII sets
+ *  `sensitive`, whose entries hold none of the three. */
+export function getActionLog(): readonly ActionInstance[] {
+  const entries = [...inflight.values(), ...settled.values()];
+  entries.sort((a, b) => a.seq - b.seq);
+  return entries.map((e) => e.instance);
+}
+
+/** O(1) check: true if at least one instance of the named action is pending.
+ *  Reactive — reading inside an effect tracks the name's pending signal. */
+export function isPending(name: string): boolean {
+  return pendingSigs.ensure(name, 0).value > 0;
+}
+
+/** Pending count for action(s). Reactive — reads track the relevant signals. */
+export function pendingCount(names?: readonly string[]): number {
+  if (names === undefined) {
+    return pendingTotalSig.value;
+  }
+  let total = 0;
+  for (const name of names) {
+    total += pendingSigs.ensure(name, 0).value;
+  }
+  return total;
+}
+
+/** Test-only: clear log + listeners. */
+export function _resetForTest(): void {
+  inflight.clear();
+  settled.clear();
+  seqCounter = 0;
+  pendingByName.clear();
+  listeners.clear();
+  namedListeners.clear();
+  pendingSigs.clearAll();
+  pendingTotalSig.value = 0;
+}

package/src/actions/retry.ts

@@ -0,0 +1,79 @@
+/** Abort-aware sleep. Rejects with AbortError if the signal fires
+ *  before the timeout elapses. Resolves immediately for ms <= 0. */
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.reject(new DOMException("aborted", "AbortError"));
+  }
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve, reject) => {
+    const t = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(t);
+      reject(new DOMException("aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Wait for the browser to come back online, or for the signal to abort.
+ *  Resolves immediately unless the platform positively reports being offline. */
+export function waitForOnline(signal: AbortSignal): Promise<void> {
+  // Node ships a `navigator` with no `onLine`; testing for `false` (not for the
+  // object's presence) avoids reading that absence as "offline".
+  const onLine = (globalThis as { readonly navigator?: Navigator }).navigator?.onLine;
+  if (onLine !== false) {
+    return Promise.resolve();
+  }
+  if (signal.aborted) {
+    return Promise.reject(new DOMException("aborted", "AbortError"));
+  }
+  return new Promise<void>((resolve, reject) => {
+    const onOnline = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onAbort = (): void => {
+      cleanup();
+      reject(new DOMException("aborted", "AbortError"));
+    };
+    function cleanup(): void {
+      if (typeof window !== "undefined") {
+        window.removeEventListener("online", onOnline);
+      }
+      signal.removeEventListener("abort", onAbort);
+    }
+    if (typeof window !== "undefined") {
+      window.addEventListener("online", onOnline, { once: true });
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Attach attempt count to a thrown error (non-enumerable property). */
+export function attachAttempts(e: unknown, attempts: number): void {
+  if (typeof e === "object" && e !== null) {
+    try {
+      Object.defineProperty(e, "_attempts", { value: attempts, configurable: true });
+    } catch {
+      /* frozen/sealed object — skip */
+    }
+  }
+}
+
+/** Read the attempt count attached by runWithRetry, or undefined. */
+export function readAttempts(e: unknown): number | undefined {
+  try {
+    if (typeof e === "object" && e !== null && "_attempts" in e) {
+      const val = (e as { readonly _attempts: unknown })._attempts;
+      return typeof val === "number" ? val : undefined;
+    }
+  } catch {
+    /* Proxy or getter threw — skip */
+  }
+  return undefined;
+}

package/src/actions/testing.ts

@@ -0,0 +1,29 @@
+/**
+ * Test-only resets for the framework's module-global state.
+ *
+ * Published as the `@cplieger/ui/actions/testing` subpath so a suite can return
+ * the notifier, api, transport, define, registry and cleanup slots to their
+ * unconfigured state between cases; without that, one test's `configure*()`
+ * call and its registered actions leak into the next. Import it from test code
+ * only: in an application the slots are set once at boot, and clearing them at
+ * runtime drops the adapters every dispatch depends on.
+ *
+ * @module
+ */
+
+import { _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { _resetApiConfigForTest as resetApi } from "./api.js";
+import { _resetTransportForTest as resetTransport } from "./transport.js";
+import { _resetNotifierForTest as resetNotifier } from "./notifier.js";
+
+/** Reset every framework state slot. Call from `beforeEach()`. */
+export function resetActionFramework(): void {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  resetApi();
+  resetTransport();
+  resetNotifier();
+}

package/src/actions/transport.ts

@@ -0,0 +1,104 @@
+import { defineAction } from "./define.js";
+import { ActionError } from "./error.js";
+import type { Action, ActionContext, ActionDefinition } from "./types.js";
+
+/** Result returned by the transport send function.
+ *  `ok: true` means the command was accepted; `ok: false` triggers the
+ *  action's error branch (rollback + notification). */
+export interface TransportSendResult {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly error?: string;
+  readonly code?: string;
+}
+
+/** A command object sent via the transport layer. Must include a `type`
+ *  discriminator; additional fields carry the command payload. */
+export interface TransportCommand {
+  readonly type: string;
+  [key: string]: unknown;
+}
+
+/** Signature of the consumer-provided send function.
+ *  Receives the command and an options bag with an AbortSignal for cancellation. */
+export type TransportSendFn = (
+  cmd: TransportCommand,
+  opts: { signal: AbortSignal },
+) => Promise<TransportSendResult>;
+
+/** Command field name carrying the per-dispatch idempotency key injected by
+ *  {@link transportAction}. Exported so consumer-authored custom runners can
+ *  share the wire convention instead of hand-copying the literal. */
+export const IDEMPOTENCY_COMMAND_FIELD = "idempotency_key";
+
+let _send: TransportSendFn | undefined;
+
+/** Configure the global transport adapter. Call once at app boot;
+ *  only needed if using `transportAction`. */
+export function configureTransport(fn: TransportSendFn): void {
+  _send = fn;
+}
+
+/** @internal Test-only: reset the transport to unconfigured state. */
+export function _resetTransportForTest(): void {
+  _send = undefined;
+}
+
+/** Caller-facing shape of a transportAction definition. `command`
+ *  replaces `run`. Result is `void` because transport.send does not
+ *  return a payload (the response arrives later via SSE events). */
+interface TransportActionDefinition<TArgs, TOp = unknown> extends Omit<
+  ActionDefinition<TArgs, void, TOp>,
+  "run"
+> {
+  /** Build the command for this dispatch. Re-evaluated per-dispatch. */
+  command: (args: TArgs) => TransportCommand;
+}
+
+/** Build an Action from a transport command descriptor. The generated
+ *  `run()` calls the configured send function and throws {@link ActionError}
+ *  on `!ok`, so the dispatcher's error branch fires consistently. */
+export function transportAction<TArgs, TOp = unknown>(
+  def: TransportActionDefinition<TArgs, TOp>,
+): Action<TArgs, void> {
+  const { command, ...rest } = def;
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- void used as generic type argument
+  return defineAction<TArgs, void, TOp>({
+    ...(rest as Omit<ActionDefinition<TArgs, void, TOp>, "run">),
+    run: async (args: TArgs, signal: AbortSignal, ctx?: ActionContext) => {
+      if (_send === undefined) {
+        throw new ActionError("Transport not configured. Call configureTransport() at boot.", {
+          code: "transport_not_configured",
+        });
+      }
+      const raw = command(args);
+      let cmd: TransportCommand;
+      if (ctx?.idempotencyKey !== undefined) {
+        cmd = { ...raw, [IDEMPOTENCY_COMMAND_FIELD]: ctx.idempotencyKey };
+      } else {
+        cmd = raw;
+      }
+      const r = await _send(cmd, { signal });
+      if (!r.ok) {
+        if (signal.aborted || r.code === "cancelled") {
+          throw new ActionError("cancelled", { code: "cancelled" });
+        }
+        if (r.code === "timeout") {
+          throw new ActionError(r.error ?? "Request timed out", {
+            status: r.status,
+            code: "timeout",
+          });
+        }
+        if (r.code === "network") {
+          throw new ActionError(r.error ?? "network error", { status: r.status, code: "network" });
+        }
+        const errOpts: { status: number; code?: string } = { status: r.status };
+        if (r.code !== undefined) {
+          errOpts.code = r.code;
+        }
+        throw new ActionError(r.error ?? `send failed with status ${String(r.status)}`, errOpts);
+      }
+      return undefined;
+    },
+  });
+}