@cplieger/actions 1.0.0

package/dist/src/error.js

@@ -0,0 +1,174 @@
+// 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)
+// ---------------------------------------------------------------------------
+/**
+ * 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 {
+    status;
+    code;
+    cause;
+    constructor(message, opts) {
+        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) {
+    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) {
+    if (e instanceof ActionError) {
+        const r = {
+            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 = 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.status : undefined;
+        const status = typeof rawStatus === "number" ? rawStatus : undefined;
+        const rawCode = "code" in e ? e.code : undefined;
+        const code = typeof rawCode === "string" ? rawCode : undefined;
+        const r = {
+            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;
+        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,
+            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, signal) {
+    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) {
+    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/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+export { configure } from "./notifier.js";
+export type { Notifier, NotifierRetry } from "./notifier.js";
+export { configureTransport, transportAction } from "./transport.js";
+export type { TransportSendResult, TransportCommand, TransportSendFn } from "./transport.js";
+export { defineAction } from "./define.js";
+export { apiAction, configureApi, API_TIMEOUT_MS, withTimeout } from "./api.js";
+export type { ApiConfig, ApiActionDefinition } from "./api.js";
+export { ActionError, hasErrorString, classifyFetchError, retryNetwork } from "./error.js";
+export { subscribe as subscribeToActions, subscribeByName, getActionLog, pendingCount, isPending, } from "./registry.js";
+export { bindLoadingState } from "./loading.js";
+export { registerCleanup } from "./cleanup.js";
+export { debouncedDispatch } from "./debounce.js";
+export type { DebouncedDispatch } from "./debounce.js";
+export { pollAction } from "./poll.js";
+export type { PollOptions } from "./poll.js";
+export type { Action, ActionContext, ActionDefinition, ActionErrorLike, ActionInstance, ActionLifecycleStatus, DispatchHandle, DispatchOptions, NotificationSpec, RegistryListener, RequestSpec, RetryConfig, ToastSpec, } from "./types.js";
+export { RETRY_STANDARD } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,22 @@
+// Public surface of the @cplieger/actions framework.
+// ---------------------------------------------------------------------------
+// Configuration
+export { configure } from "./notifier.js";
+// Transport injection
+export { configureTransport, transportAction } from "./transport.js";
+// Action factories
+export { defineAction } from "./define.js";
+export { apiAction, configureApi, API_TIMEOUT_MS, withTimeout } 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";
+// Polling helper
+export { pollAction } from "./poll.js";
+export { RETRY_STANDARD } from "./types.js";

package/dist/src/loading.d.ts

@@ -0,0 +1,15 @@
+/** 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 declare function bindLoadingState(actionName: string | readonly string[], el: DisableableElement, opts?: BindLoadingOptions): () => void;
+export {};

package/dist/src/loading.js

@@ -0,0 +1,114 @@
+// 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";
+/**
+ * Bind a button/input element's disabled / aria-busy state to one or
+ * more named actions.
+ */
+export function bindLoadingState(actionName, el, opts = {}) {
+    const names = 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 = () => {
+        if (disabledFn !== undefined) {
+            try {
+                return disabledFn();
+            }
+            catch {
+                return false;
+            }
+        }
+        return preserveDisabled ? baseDisabled : false;
+    };
+    const setIdle = () => {
+        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 = () => 
+    // 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;
+    const apply = () => {
+        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 = () => {
+        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/dist/src/notifier.d.ts

@@ -0,0 +1,21 @@
+/** 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;
+}
+/** Configure the global notifier adapter. Call once at app boot. */
+export declare function configure(notifier: Notifier): void;
+/** @internal Emit a success notification. */
+export declare function notifySuccess(message: string): void;
+/** @internal Emit an error notification. */
+export declare function notifyError(message: string, retry?: NotifierRetry): void;
+/** @internal Test-only: reset the notifier to the default no-op. */
+export declare function _resetNotifierForTest(): void;

package/dist/src/notifier.js

@@ -0,0 +1,21 @@
+// 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).
+// ---------------------------------------------------------------------------
+let _notifier = {};
+/** Configure the global notifier adapter. Call once at app boot. */
+export function configure(notifier) {
+    _notifier = notifier;
+}
+/** @internal Emit a success notification. */
+export function notifySuccess(message) {
+    _notifier.success?.(message);
+}
+/** @internal Emit an error notification. */
+export function notifyError(message, retry) {
+    _notifier.error?.(message, retry);
+}
+/** @internal Test-only: reset the notifier to the default no-op. */
+export function _resetNotifierForTest() {
+    _notifier = {};
+}

package/dist/src/poll.d.ts

@@ -0,0 +1,23 @@
+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 declare function pollAction<TArgs, TResult>(action: Action<TArgs, TResult>, args: TArgs, opts: PollOptions<TResult>): () => void;

package/dist/src/poll.js

@@ -0,0 +1,120 @@
+// 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";
+/**
+ * Repeatedly dispatch `action(args)` at the given interval.
+ * Returns a `stop()` function.
+ */
+export function pollAction(action, args, opts) {
+    const pauseWhenHidden = opts.pauseWhenHidden !== false;
+    const refreshOnFocus = opts.refreshOnFocus !== false;
+    const baseInterval = opts.interval;
+    const backoff = opts.backoffOnError;
+    const onSuccess = opts.onSuccess;
+    let timer;
+    let stopped = false;
+    let paused = false;
+    let inFlight = false;
+    let failures = 0;
+    function nextDelay() {
+        if (backoff === undefined || failures === 0) {
+            return baseInterval;
+        }
+        return Math.min(baseInterval * Math.pow(backoff.factor, failures), backoff.max);
+    }
+    function schedule() {
+        if (stopped || paused) {
+            return;
+        }
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => {
+            void tick();
+        }, nextDelay());
+    }
+    async function tick() {
+        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 = () => {
+        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 = () => {
+        if (stopped || paused || inFlight) {
+            return;
+        }
+        void tick();
+    };
+    function stop() {
+        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;
+}

package/dist/src/registry.d.ts

@@ -0,0 +1,18 @@
+import type { ActionInstance, RegistryListener } from "./types.js";
+/** Record a state transition. Called by define.ts. */
+export declare function record(instance: ActionInstance): void;
+/** Subscribe to all action lifecycle events. */
+export declare function subscribe(fn: RegistryListener): () => void;
+/** Subscribe to lifecycle events for a single action name. */
+export declare function subscribeByName(name: string, fn: RegistryListener): () => void;
+/** @internal Test-only public surface. */
+export declare function recentLog(): readonly ActionInstance[];
+/** Read the recent action log. Useful for devtools integration and
+ *  debugging panels. Returns a snapshot of all live entries. */
+export declare const getActionLog: typeof recentLog;
+/** O(1) check: true if at least one instance of the named action is pending. */
+export declare function isPending(name: string): boolean;
+/** Pending count for action(s). */
+export declare function pendingCount(names?: readonly string[]): number;
+/** Test-only: clear log + listeners. */
+export declare function _resetForTest(): void;