@cplieger/actions 1.0.0

package/src/registry.ts

@@ -0,0 +1,225 @@
+// Action registry: in-memory log of all dispatched actions with a
+// subscribe API. Fires per state transition. Bounded to a recent
+// window so memory usage stays flat over a long session.
+//
+// Performance: eviction uses a head-pointer + tombstones instead of
+// splice + O(n) index re-computation. record() is O(1) amortized.
+// ---------------------------------------------------------------------------
+
+import type { ActionInstance, RegistryListener } from "./types.js";
+
+const MAX_LOG_SIZE = 200;
+const MAX_LOG_HARD = MAX_LOG_SIZE * 5;
+
+const log: (ActionInstance | null)[] = [];
+interface LogSlot {
+  instance: ActionInstance;
+  index: number;
+}
+const idMap = new Map<string, LogSlot>();
+const listeners = new Set<RegistryListener>();
+const namedListeners = new Map<string, Set<RegistryListener>>();
+const pendingByName = new Map<string, Set<string>>();
+let _pendingTotal = 0;
+let _liveCount = 0;
+let _head = 0;
+
+function compact(): void {
+  while (_head < log.length && log[_head] === null) {
+    _head++;
+  }
+  if (_head > 256) {
+    log.splice(0, _head);
+    for (const entry of idMap.values()) {
+      entry.index -= _head;
+    }
+    _head = 0;
+  }
+}
+
+/** Record a state transition. Called by define.ts. */
+export function record(instance: ActionInstance): void {
+  const existing = idMap.get(instance.id);
+  if (existing !== undefined) {
+    const prev = existing.instance;
+    if (prev.status === "pending" && instance.status !== "pending") {
+      _pendingTotal--;
+      const s = pendingByName.get(prev.name);
+      if (s !== undefined) {
+        s.delete(instance.id);
+        if (s.size === 0) {
+          pendingByName.delete(prev.name);
+        }
+      }
+    } else if (prev.status !== "pending" && instance.status === "pending") {
+      _pendingTotal++;
+      let s = pendingByName.get(instance.name);
+      if (s === undefined) {
+        s = new Set();
+        pendingByName.set(instance.name, s);
+      }
+      s.add(instance.id);
+    }
+    log[existing.index] = instance;
+    existing.instance = instance;
+    if (instance.status !== "pending" && _liveCount > MAX_LOG_SIZE) {
+      for (let i = _head; i < log.length; i++) {
+        const entry = log[i];
+        if (
+          entry !== null &&
+          entry !== undefined &&
+          entry.status !== "pending" &&
+          entry.id !== instance.id
+        ) {
+          idMap.delete(entry.id);
+          log[i] = null;
+          _liveCount--;
+          if (_liveCount <= MAX_LOG_SIZE) {
+            break;
+          }
+        }
+      }
+      compact();
+    }
+  } else {
+    const idx = log.length;
+    log.push(instance);
+    idMap.set(instance.id, { instance, index: idx });
+    _liveCount++;
+    if (instance.status === "pending") {
+      _pendingTotal++;
+      let s = pendingByName.get(instance.name);
+      if (s === undefined) {
+        s = new Set();
+        pendingByName.set(instance.name, s);
+      }
+      s.add(instance.id);
+    }
+    if (_liveCount > MAX_LOG_SIZE) {
+      for (let i = _head; i < log.length; i++) {
+        const entry = log[i];
+        if (entry !== null && entry !== undefined && entry.status !== "pending") {
+          idMap.delete(entry.id);
+          log[i] = null;
+          _liveCount--;
+          break;
+        }
+      }
+    }
+    if (_liveCount > MAX_LOG_HARD) {
+      for (let i = _head; i < log.length; i++) {
+        const entry = log[i];
+        if (entry !== null && entry !== undefined) {
+          if (entry.status === "pending") {
+            _pendingTotal--;
+            const s = pendingByName.get(entry.name);
+            if (s !== undefined) {
+              s.delete(entry.id);
+              if (s.size === 0) {
+                pendingByName.delete(entry.name);
+              }
+            }
+          }
+          idMap.delete(entry.id);
+          log[i] = null;
+          _liveCount--;
+          break;
+        }
+      }
+    }
+    compact();
+  }
+  if (_pendingTotal < 0) {
+    console.warn("[actions] _pendingTotal went negative — invariant violation; clamping to 0");
+    _pendingTotal = 0;
+  }
+  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);
+    }
+  };
+}
+
+/** @internal Test-only public surface. */
+export function recentLog(): readonly ActionInstance[] {
+  const result: ActionInstance[] = [];
+  for (let i = _head; i < log.length; i++) {
+    const entry = log[i];
+    if (entry != null) {
+      result.push(entry);
+    }
+  }
+  return result;
+}
+
+/** Read the recent action log. Useful for devtools integration and
+ *  debugging panels. Returns a snapshot of all live entries. */
+export const getActionLog = recentLog;
+
+/** O(1) check: true if at least one instance of the named action is pending. */
+export function isPending(name: string): boolean {
+  const s = pendingByName.get(name);
+  return s !== undefined && s.size > 0;
+}
+
+/** Pending count for action(s). */
+export function pendingCount(names?: readonly string[]): number {
+  if (names === undefined) {
+    return _pendingTotal;
+  }
+  let total = 0;
+  for (const name of names) {
+    const s = pendingByName.get(name);
+    if (s !== undefined) {
+      total += s.size;
+    }
+  }
+  return total;
+}
+
+/** Test-only: clear log + listeners. */
+export function _resetForTest(): void {
+  log.length = 0;
+  _head = 0;
+  _liveCount = 0;
+  idMap.clear();
+  pendingByName.clear();
+  listeners.clear();
+  namedListeners.clear();
+  _pendingTotal = 0;
+}

package/src/retry.ts

@@ -0,0 +1,80 @@
+// retry.ts — extracted retry/backoff primitives from define.ts.
+// These are pure utility functions with no dependency on the action
+// framework, making them independently testable.
+// ---------------------------------------------------------------------------
+
+/** 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. */
+export function waitForOnline(signal: AbortSignal): Promise<void> {
+  if (typeof navigator === "undefined" || navigator.onLine) {
+    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/transport.ts

@@ -0,0 +1,112 @@
+// Transport injection seam: consumer-provided adapter for streaming/SSE
+// command dispatch. Mirrors the notifier.ts pattern — call
+// configureTransport() at boot to wire up the send function.
+// ---------------------------------------------------------------------------
+
+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>;
+
+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 transport send function and throws
+ * {@link ActionError} on `!ok`, so the dispatcher's error branch
+ * (notification + rollback) fires consistently.
+ *
+ * @param def - Transport action definition where `command` replaces `run`.
+ * @returns An {@link Action} backed by the configured transport adapter.
+ */
+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_key: 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 (${String(r.status)})`, errOpts);
+      }
+      return undefined;
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,198 @@
+// Action framework types: defines the contract between callers, the
+// dispatcher, and observers. Pure types — no imports, no runtime
+// behavior — so any module in the codebase can depend on this without
+// pulling in transport / notification / store.
+// ---------------------------------------------------------------------------
+
+/** Lifecycle status of a single dispatched action instance.
+ *
+ *  - `"pending"` — optimistic ran (if any), run() in flight
+ *  - `"success"` — run() resolved
+ *  - `"error"` — run() threw; rollback ran
+ *  - `"cancelled"` — action.cancel() called or signal aborted externally */
+export type ActionLifecycleStatus = "pending" | "success" | "error" | "cancelled";
+
+/** Errors thrown by an action's run() function. ActionError subclass
+ *  in error.ts attaches HTTP status + server error code metadata. */
+export interface ActionErrorLike {
+  readonly message: string;
+  /** HTTP status if applicable. */
+  readonly status?: number;
+  /** Server-side error code. */
+  readonly code?: string;
+  readonly cause?: unknown;
+}
+
+/** Snapshot of a single in-flight or historical action invocation.
+ *  Stored in the registry log for observability. */
+export interface ActionInstance<TArgs = unknown, TResult = unknown> {
+  /** Unique per dispatch. */
+  readonly id: string;
+  /** Matches ActionDefinition.name. */
+  readonly name: string;
+  readonly status: ActionLifecycleStatus;
+  readonly args: TArgs;
+  /** Date.now() when dispatch() was called. */
+  readonly dispatchedAt: number;
+  /** Date.now() when run() begins (after scope queue). */
+  readonly startedAt: number;
+  /** Date.now() at terminal state. */
+  readonly completedAt?: number;
+  /** Present iff status === "success". */
+  readonly result?: TResult;
+  /** Present iff status === "error". */
+  readonly error?: ActionErrorLike;
+  /** Total run() invocations (1 = no retry; >1 = retries fired). */
+  readonly attempts?: number;
+}
+
+/** Notification wiring: either a literal string (used as-is), or a function
+ *  computed from action args + result/error at call time. Pass false
+ *  to opt out of the default notification for that branch. */
+export type NotificationSpec<TArgs, TPayload> =
+  | string
+  | ((args: TArgs, payload: TPayload) => string)
+  | false;
+
+/** @deprecated Use {@link NotificationSpec} instead. */
+export type ToastSpec<TArgs, TPayload> = NotificationSpec<TArgs, TPayload>;
+
+/** Per-dispatch context passed to run() as the 3rd argument. Mostly
+ *  populated by the framework so adapters (apiAction, transportAction)
+ *  can read out values like the idempotency key without the caller
+ *  having to plumb them. */
+export interface ActionContext {
+  /** Stable identifier for this dispatch (matches the registry's
+   *  ActionInstance.id). */
+  readonly instanceID: string;
+  /** Set when ActionDefinition.idempotencyKey is configured. The
+   *  framework generates this once per dispatch (not per retry). */
+  readonly idempotencyKey?: string;
+}
+
+/** Configuration for automatic retry of transient failures. */
+export interface RetryConfig {
+  /** Additional attempts beyond the first (e.g. 2 = up to 3 total). */
+  readonly count: number;
+  /** Milliseconds before each retry. Number form: exponential backoff via
+   *  `delay × factor^(attempt-1)`, capped at 5s. Function form: full
+   *  control — receives the attempt number and the triggering error. */
+  readonly delay: number | ((attempt: number, err: ActionErrorLike) => number);
+  /** Backoff multiplier per retry. Default 2. Ignored when `delay` is a function. */
+  readonly factor?: number;
+}
+
+/** Standard retry config: 2 retries, 300ms initial delay. */
+export const RETRY_STANDARD: RetryConfig = { count: 2, delay: 300 } as const;
+
+export interface ActionDefinition<TArgs, TResult, TOp = unknown> {
+  /** Stable identifier, e.g. "chat.delete", "files.create".
+   *  Used in the registry log + as a default notification prefix. */
+  readonly name: string;
+
+  /** The work the action performs. Must throw ActionError on failure
+   *  (or any Error — wrappers will normalise). */
+  run: (args: TArgs, signal: AbortSignal, ctx?: ActionContext) => Promise<TResult>;
+
+  /** Optional optimistic mutation. Runs synchronously before run(). */
+  optimistic?: (args: TArgs) => TOp | undefined;
+
+  /** Undo the optimistic mutation. Called only if run() throws. */
+  rollback?: (args: TArgs, op: TOp | undefined, err: ActionErrorLike) => void;
+
+  /** Notification on success. Default: no notification. */
+  success?: NotificationSpec<TArgs, TResult>;
+
+  /** Notification on error. Default: action name humanised + error message. */
+  error?: NotificationSpec<TArgs, ActionErrorLike>;
+
+  /** Definition-level success callback. Fires on every successful dispatch.
+   *  Mirrors TanStack Query's mutation-level onSuccess. */
+  onSuccess?: (result: TResult, args: TArgs) => void;
+
+  /** Definition-level error callback. Fires on every failed dispatch.
+   *  Mirrors TanStack Query's mutation-level onError. */
+  onError?: (err: ActionErrorLike, args: TArgs) => void;
+
+  /** Definition-level settled callback. Fires after every dispatch
+   *  (success, error, or cancellation). Mirrors TanStack Query's onSettled. */
+  onSettled?: (args: TArgs) => void;
+
+  /** Classify whether an error qualifies for retry. */
+  retryable?: (err: ActionErrorLike) => boolean;
+
+  /** Auto-retry transient failures before surfacing the error notification. */
+  retry?: RetryConfig;
+
+  /** Auto-retry behavior when offline. Default `"online"`. */
+  networkMode?: "online" | "always";
+
+  /** Timeout in milliseconds for the run() function. Uses AbortSignal.timeout()
+   *  composed with the cancellation signal. If run() exceeds this duration,
+   *  the signal aborts with a TimeoutError. */
+  timeout?: number;
+
+  /** Serialize concurrent dispatches sharing the same scope key. */
+  scope?: string | ((args: TArgs) => string);
+
+  /** Generate an idempotency key per dispatch. */
+  idempotencyKey?: boolean | ((args: TArgs) => string);
+
+  /** Collapse concurrent dispatches with matching key into one in-flight promise. */
+  dedupe?: boolean | ((args: TArgs) => string);
+}
+
+/** A registered action, returned by defineAction(). Can be dispatched
+ *  many times; each dispatch is a separate instance with its own
+ *  cancellation token. */
+export interface Action<TArgs, TResult> {
+  readonly name: string;
+
+  /** Run the action. Returns a DispatchHandle with the result promise
+   *  and a per-dispatch abort() method (RTK pattern). */
+  dispatch(args: TArgs, opts?: DispatchOptions<TArgs, TResult>): DispatchHandle<TResult>;
+
+  /** Cancel all in-flight instances. Each instance moves to status
+   *  "cancelled" and run()'s signal aborts. */
+  cancel(): void;
+}
+
+/** Handle returned by dispatch(). An augmented Promise with an abort()
+ *  method for per-dispatch cancellation (mirrors RTK createAsyncThunk).
+ *  Can be awaited directly as a Promise. */
+export interface DispatchHandle<TResult> extends Promise<TResult | null> {
+  /** Abort this specific dispatch. Other in-flight dispatches of the
+   *  same action are unaffected. Mirrors RTK's promise.abort(). */
+  abort(): void;
+}
+
+/** Per-dispatch overrides. */
+export interface DispatchOptions<TArgs = unknown, TResult = unknown> {
+  /** Suppress the success notification for this call. Errors still notify. */
+  readonly silent?: boolean;
+  /** Per-call success callback. Fires after the action-level notification. */
+  readonly onSuccess?: (result: TResult, args: TArgs) => void;
+  /** Per-call error callback. Fires after the action-level error notification. */
+  readonly onError?: (err: ActionErrorLike, args: TArgs) => void;
+  /** Per-call settled callback. Fires for success, error, AND cancellation. */
+  readonly onSettled?: (args: TArgs) => void;
+}
+
+/** HTTP request descriptor used by apiAction(). GET is included for
+ *  read actions that want notification/cancellation semantics. */
+export type RequestSpec =
+  | {
+      readonly method: "GET";
+      readonly path: string;
+      readonly headers?: Readonly<Record<string, string>>;
+    }
+  | {
+      readonly method: "POST" | "PUT" | "PATCH" | "DELETE";
+      readonly path: string;
+      readonly body?: unknown;
+      readonly headers?: Readonly<Record<string, string>>;
+    };
+
+/** Subscriber callback for the registry. Fires once per state
+ *  transition (pending -> success/error/cancelled). */
+export type RegistryListener = (instance: ActionInstance) => void;