@cplieger/actions 1.0.0

package/src/error.ts

@@ -0,0 +1,184 @@
+// ActionError: thrown by an action's run() function to signal a typed
+// failure. Carries optional HTTP status, server-side error code, and
+// cause chain for diagnostics.
+//
+// Public surface:
+//   - ActionError       : structured error class
+//   - hasErrorString    : narrows parsed JSON bodies with `{ error: "..." }`
+//   - classifyFetchError: normalize fetch catch-block errors
+//   - retryNetwork      : preset classifier — network/timeout/transient HTTP
+//
+// Internal:
+//   - toActionError: coerce thrown values into ActionErrorLike (used by define.ts)
+// ---------------------------------------------------------------------------
+
+import type { ActionErrorLike } from "./types.js";
+
+/**
+ * Structured error thrown from an action's `run()` to signal a typed failure.
+ * Carries optional HTTP status and server-side error code for downstream
+ * classification (retry eligibility, notification formatting, telemetry).
+ *
+ * @example
+ * ```ts
+ * throw new ActionError("Server rejected", { status: 409, code: "conflict" });
+ * ```
+ */
+export class ActionError extends Error implements ActionErrorLike {
+  readonly status?: number;
+  readonly code?: string;
+  override readonly cause?: unknown;
+
+  constructor(message: string, opts?: { status?: number; code?: string; cause?: unknown }) {
+    super(message);
+    this.name = "ActionError";
+    if (opts?.status !== undefined) {
+      this.status = opts.status;
+    }
+    if (opts?.code !== undefined) {
+      this.code = opts.code;
+    }
+    if (opts?.cause !== undefined) {
+      this.cause = opts.cause;
+    }
+  }
+}
+
+/** Type predicate: true when `v` is a non-null object with a string `error` property. */
+export function hasErrorString(v: unknown): v is { error: string } {
+  if (typeof v !== "object" || v === null || !("error" in v)) {
+    return false;
+  }
+  return typeof v.error === "string";
+}
+
+/** Coerce any thrown value into an ActionErrorLike snapshot. Internal. */
+export function toActionError(e: unknown): ActionErrorLike {
+  if (e instanceof ActionError) {
+    const r: { message: string; status?: number; code?: string; cause?: unknown } = {
+      message: e.message,
+    };
+    if (e.status !== undefined) {
+      r.status = e.status;
+    }
+    if (e.code !== undefined) {
+      r.code = e.code;
+    }
+    if (e.cause !== undefined) {
+      r.cause = e.cause;
+    }
+    return r;
+  }
+  if (e instanceof DOMException) {
+    const code =
+      e.name === "TimeoutError"
+        ? "timeout"
+        : e.name === "AbortError"
+          ? "cancelled"
+          : e.name === "NetworkError"
+            ? "network"
+            : e.name.toLowerCase();
+    const isNetLayer = code === "network" || code === "timeout";
+    return { message: e.message, code, ...(isNetLayer && { status: 0 }), cause: e };
+  }
+  if (e instanceof AggregateError) {
+    const first: unknown = e.errors[0];
+    const inner = first instanceof Error ? first.message : e.message;
+    return { message: inner || e.message, code: "aggregate", cause: e };
+  }
+  if (e instanceof Error) {
+    const rawStatus = "status" in e ? (e as { status: unknown }).status : undefined;
+    const status = typeof rawStatus === "number" ? rawStatus : undefined;
+    const rawCode = "code" in e ? (e as { code: unknown }).code : undefined;
+    const code = typeof rawCode === "string" ? rawCode : undefined;
+    const r: { message: string; status?: number; code?: string; cause: unknown } = {
+      message: e.message,
+      cause: e,
+    };
+    if (status !== undefined) {
+      r.status = status;
+    }
+    if (code !== undefined) {
+      r.code = code;
+    }
+    return r;
+  }
+  if (typeof e === "object" && e !== null && "message" in e) {
+    const obj = e as { message: unknown; status?: unknown; code?: unknown };
+    const message = typeof obj.message === "string" ? obj.message : String(obj.message);
+    const status = typeof obj.status === "number" ? obj.status : undefined;
+    const code = typeof obj.code === "string" ? obj.code : undefined;
+    const r: { message: string; status?: number; code?: string; cause: unknown } = {
+      message,
+      cause: e,
+    };
+    if (status !== undefined) {
+      r.status = status;
+    }
+    if (code !== undefined) {
+      r.code = code;
+    }
+    return r;
+  }
+  if (e === null) {
+    return { message: "Unknown error (null thrown)", code: "unknown" };
+  }
+  if (e === undefined) {
+    return { message: "Unknown error (undefined thrown)", code: "unknown" };
+  }
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional coercion of unknown thrown value
+  const msg = String(e);
+  return {
+    message: msg !== "" ? msg : "Unknown error (empty value thrown)",
+    code: "unknown",
+    cause: e,
+  };
+}
+
+/**
+ * Classify a caught fetch error into an ActionError with a canonical code.
+ *
+ * Classification priority:
+ *  1. Signal already aborted → "cancelled"
+ *  2. DOMException TimeoutError / AbortError with live signal → "timeout"
+ *  3. TypeError → "network" (browsers throw TypeError for network failures)
+ *  4. Everything else → "network"
+ */
+export function classifyFetchError(e: unknown, signal: AbortSignal): ActionError {
+  if (signal.aborted) {
+    return new ActionError("Request cancelled", { code: "cancelled", cause: e });
+  }
+  if (e instanceof DOMException) {
+    if (e.name === "TimeoutError" || e.name === "AbortError") {
+      return new ActionError("Request timed out", { status: 0, code: "timeout", cause: e });
+    }
+  }
+  if (e instanceof TypeError) {
+    return new ActionError(e.message, { status: 0, code: "network", cause: e });
+  }
+  const msg = e instanceof Error ? e.message : "network error";
+  return new ActionError(msg, { status: 0, code: "network", cause: e });
+}
+
+/** HTTP statuses that represent transient server-side conditions. */
+const TRANSIENT_STATUSES = new Set([408, 429, 502, 503, 504]);
+
+/**
+ * Retry classifier preset: matches network/timeout failures and transient
+ * HTTP statuses (408, 429, 502, 503, 504). Always excludes cancellation.
+ */
+export function retryNetwork(err: ActionErrorLike): boolean {
+  if (err.code === "cancelled") {
+    return false;
+  }
+  if (err.code === "network" || err.code === "timeout") {
+    return true;
+  }
+  if (err.status === 0) {
+    return true;
+  }
+  if (err.status !== undefined && TRANSIENT_STATUSES.has(err.status)) {
+    return true;
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+// Public surface of the @cplieger/actions framework.
+// ---------------------------------------------------------------------------
+
+// Configuration
+export { configure } from "./notifier.js";
+export type { Notifier, NotifierRetry } from "./notifier.js";
+
+// Transport injection
+export { configureTransport, transportAction } from "./transport.js";
+export type { TransportSendResult, TransportCommand, TransportSendFn } from "./transport.js";
+
+// Action factories
+export { defineAction } from "./define.js";
+export { apiAction, configureApi, API_TIMEOUT_MS, withTimeout } from "./api.js";
+export type { ApiConfig, ApiActionDefinition } from "./api.js";
+
+// Error class + utilities
+export { ActionError, hasErrorString, classifyFetchError, retryNetwork } from "./error.js";
+
+// Registry
+export {
+  subscribe as subscribeToActions,
+  subscribeByName,
+  getActionLog,
+  pendingCount,
+  isPending,
+} from "./registry.js";
+
+// Loading-state helper
+export { bindLoadingState } from "./loading.js";
+
+// Cleanup hooks
+export { registerCleanup } from "./cleanup.js";
+
+// Debounce helper
+export { debouncedDispatch } from "./debounce.js";
+export type { DebouncedDispatch } from "./debounce.js";
+
+// Polling helper
+export { pollAction } from "./poll.js";
+export type { PollOptions } from "./poll.js";
+
+// Types
+export type {
+  Action,
+  ActionContext,
+  ActionDefinition,
+  ActionErrorLike,
+  ActionInstance,
+  ActionLifecycleStatus,
+  DispatchHandle,
+  DispatchOptions,
+  NotificationSpec,
+  RegistryListener,
+  RequestSpec,
+  RetryConfig,
+  // eslint-disable-next-line @typescript-eslint/no-deprecated -- backward-compat alias
+  ToastSpec,
+} from "./types.js";
+export { RETRY_STANDARD } from "./types.js";

package/src/loading.ts

@@ -0,0 +1,149 @@
+// bindLoadingState: bind a button or input element's disabled / aria-busy
+// state to one or more named actions' pending count.
+//
+// While ANY of the named actions is pending, the element gets:
+//   - disabled = true
+//   - aria-busy = "true"  (omit by passing { ariaBusy: false })
+//   - optionally an extra CSS class via { pendingClass: "btn-loading" }
+//
+// Returns an unsubscribe function. Call it from the view's teardown
+// hook to stop receiving updates and avoid leaking listeners.
+// ---------------------------------------------------------------------------
+
+import { subscribeByName, isPending, pendingCount } from "./registry.js";
+
+/** Element types that have a `.disabled` writable boolean. */
+type DisableableElement =
+  | HTMLButtonElement
+  | HTMLInputElement
+  | HTMLSelectElement
+  | HTMLTextAreaElement;
+
+interface BindLoadingOptions {
+  ariaBusy?: boolean;
+  preserveAriaBusy?: boolean;
+  pendingClass?: string;
+  preserveDisabled?: boolean;
+  disabledFn?: () => boolean;
+}
+
+/**
+ * Bind a button/input element's disabled / aria-busy state to one or
+ * more named actions.
+ */
+export function bindLoadingState(
+  actionName: string | readonly string[],
+  el: DisableableElement,
+  opts: BindLoadingOptions = {},
+): () => void {
+  const names: readonly string[] = typeof actionName === "string" ? [actionName] : actionName;
+  if (names.length === 0) {
+    return () => {
+      /* noop */
+    };
+  }
+
+  const {
+    ariaBusy = true,
+    preserveAriaBusy = false,
+    pendingClass,
+    preserveDisabled = false,
+    disabledFn,
+  } = opts;
+  const manageAriaBusy = ariaBusy && !preserveAriaBusy;
+  let wasPending = false;
+  let baseDisabled = el.disabled;
+  let hadFocus = false;
+  let disposed = false;
+  let wasConnected = el.isConnected;
+
+  const resolveBase = (): boolean => {
+    if (disabledFn !== undefined) {
+      try {
+        return disabledFn();
+      } catch {
+        return false;
+      }
+    }
+    return preserveDisabled ? baseDisabled : false;
+  };
+
+  const setIdle = (): void => {
+    el.disabled = resolveBase();
+    if (manageAriaBusy) {
+      el.removeAttribute("aria-busy");
+    }
+    if (pendingClass) {
+      el.classList.remove(pendingClass);
+    }
+    if (hadFocus && el.isConnected && !el.disabled) {
+      const active = document.activeElement;
+      if (active === null || active === document.body) {
+        el.focus();
+      }
+    }
+    hadFocus = false;
+  };
+
+  const readPending = (): boolean =>
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length checked above
+    names.length === 1 ? isPending(names[0]!) : pendingCount(names) > 0;
+
+  // eslint-disable-next-line prefer-const -- assigned after apply() closure is defined
+  let _unsubs: (() => void)[] | undefined;
+
+  const apply = (): void => {
+    if (disposed) {
+      return;
+    }
+    if (wasConnected && !el.isConnected) {
+      disposed = true;
+      if (_unsubs) {
+        for (const u of _unsubs) {
+          u();
+        }
+      }
+      return;
+    }
+    if (el.isConnected) {
+      wasConnected = true;
+    }
+    const pending = readPending();
+    if (pending && !wasPending) {
+      baseDisabled = el.disabled;
+      hadFocus = document.activeElement === el;
+    }
+    if (pending) {
+      el.disabled = true;
+      if (manageAriaBusy) {
+        el.setAttribute("aria-busy", "true");
+      }
+      if (pendingClass) {
+        el.classList.add(pendingClass);
+      }
+    } else if (wasPending) {
+      setIdle();
+    }
+    wasPending = pending;
+  };
+
+  const restore = (): void => {
+    if (wasPending) {
+      setIdle();
+      wasPending = false;
+    }
+  };
+
+  apply();
+
+  const unsubs = names.map((name) => subscribeByName(name, apply));
+  _unsubs = unsubs;
+
+  return () => {
+    disposed = true;
+    restore();
+    for (const u of unsubs) {
+      u();
+    }
+  };
+}

package/src/notifier.ts

@@ -0,0 +1,41 @@
+// Notifier interface: consumer-injected adapter for toast/notification
+// display. Replaces the app-specific toast.ts import. The framework
+// calls these during the action lifecycle (success/error toasts).
+// ---------------------------------------------------------------------------
+
+/** Retry button descriptor passed to error notifications. */
+export interface NotifierRetry {
+  readonly onClick: () => void;
+}
+
+/** Consumer-provided notification adapter. Implement this interface
+ *  and pass it to `configure()` to wire up toast/notification display.
+ *
+ *  All methods are optional — when not provided, the framework silently
+ *  drops the notification (useful for headless/test environments). */
+export interface Notifier {
+  success?(message: string): void;
+  error?(message: string, retry?: NotifierRetry): void;
+}
+
+let _notifier: Notifier = {};
+
+/** Configure the global notifier adapter. Call once at app boot. */
+export function configure(notifier: Notifier): void {
+  _notifier = notifier;
+}
+
+/** @internal Emit a success notification. */
+export function notifySuccess(message: string): void {
+  _notifier.success?.(message);
+}
+
+/** @internal Emit an error notification. */
+export function notifyError(message: string, retry?: NotifierRetry): void {
+  _notifier.error?.(message, retry);
+}
+
+/** @internal Test-only: reset the notifier to the default no-op. */
+export function _resetNotifierForTest(): void {
+  _notifier = {};
+}

package/src/poll.ts

@@ -0,0 +1,150 @@
+// pollAction: repeat-an-action-on-interval primitive that integrates with
+// the framework lifecycle. Adds pause-when-hidden, refresh-on-focus,
+// exponential backoff on consecutive failures, and auto cleanup.
+// ---------------------------------------------------------------------------
+
+import { registerCleanup } from "./cleanup.js";
+import type { Action } from "./types.js";
+
+/** Configuration for {@link pollAction}. Controls interval timing,
+ *  visibility-pause behavior, focus-refresh, and error backoff. */
+export interface PollOptions<TResult = unknown> {
+  /** Quiet window between polls in ms. */
+  readonly interval: number;
+  /** When true (default), polls pause while document.hidden === true. */
+  readonly pauseWhenHidden?: boolean;
+  /** When true (default), fire an immediate poll on window focus. */
+  readonly refreshOnFocus?: boolean;
+  /** Exponential backoff on consecutive failures. */
+  readonly backoffOnError?: { readonly factor: number; readonly max: number };
+  /** Per-poll success callback. */
+  readonly onSuccess?: (result: TResult) => void;
+}
+
+/**
+ * Repeatedly dispatch `action(args)` at the given interval.
+ * Returns a `stop()` function.
+ */
+export function pollAction<TArgs, TResult>(
+  action: Action<TArgs, TResult>,
+  args: TArgs,
+  opts: PollOptions<TResult>,
+): () => void {
+  const pauseWhenHidden = opts.pauseWhenHidden !== false;
+  const refreshOnFocus = opts.refreshOnFocus !== false;
+  const baseInterval = opts.interval;
+  const backoff = opts.backoffOnError;
+  const onSuccess = opts.onSuccess;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+  let paused = false;
+  let inFlight = false;
+  let failures = 0;
+
+  function nextDelay(): number {
+    if (backoff === undefined || failures === 0) {
+      return baseInterval;
+    }
+    return Math.min(baseInterval * Math.pow(backoff.factor, failures), backoff.max);
+  }
+
+  function schedule(): void {
+    if (stopped || paused) {
+      return;
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      void tick();
+    }, nextDelay());
+  }
+
+  async function tick(): Promise<void> {
+    if (stopped || paused) {
+      return;
+    }
+    if (inFlight) {
+      return;
+    }
+    inFlight = true;
+    try {
+      const result = await action.dispatch(args);
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- state changes during async
+      if (stopped) {
+        return;
+      }
+      if (result === null) {
+        failures += 1;
+      } else {
+        failures = 0;
+        if (onSuccess !== undefined) {
+          try {
+            onSuccess(result);
+          } catch (e) {
+            console.error("[pollAction] onSuccess threw", e);
+          }
+        }
+      }
+    } finally {
+      inFlight = false;
+    }
+    schedule();
+  }
+
+  const onVisibility = (): void => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    if (document.hidden) {
+      paused = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    } else if (paused) {
+      paused = false;
+      void tick();
+    }
+  };
+
+  const onFocus = (): void => {
+    if (stopped || paused || inFlight) {
+      return;
+    }
+    void tick();
+  };
+
+  function stop(): void {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    listenerCtrl.abort();
+  }
+
+  const listenerCtrl = new AbortController();
+
+  if (pauseWhenHidden && typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", onVisibility, { signal: listenerCtrl.signal });
+    if (document.hidden) {
+      paused = true;
+    }
+  }
+  if (refreshOnFocus && typeof window !== "undefined") {
+    window.addEventListener("focus", onFocus, { signal: listenerCtrl.signal });
+  }
+
+  registerCleanup(stop);
+
+  if (!paused) {
+    void tick();
+  }
+
+  return stop;
+}