@cplieger/actions 1.0.0 → 1.0.1

package/dist/src/registry.js

@@ -1,210 +0,0 @@
-// 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.
-// ---------------------------------------------------------------------------
-const MAX_LOG_SIZE = 200;
-const MAX_LOG_HARD = MAX_LOG_SIZE * 5;
-const log = [];
-const idMap = new Map();
-const listeners = new Set();
-const namedListeners = new Map();
-const pendingByName = new Map();
-let _pendingTotal = 0;
-let _liveCount = 0;
-let _head = 0;
-function compact() {
-    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) {
-    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) {
-    listeners.add(fn);
-    return () => listeners.delete(fn);
-}
-/** Subscribe to lifecycle events for a single action name. */
-export function subscribeByName(name, fn) {
-    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() {
-    const result = [];
-    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) {
-    const s = pendingByName.get(name);
-    return s !== undefined && s.size > 0;
-}
-/** Pending count for action(s). */
-export function pendingCount(names) {
-    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() {
-    log.length = 0;
-    _head = 0;
-    _liveCount = 0;
-    idMap.clear();
-    pendingByName.clear();
-    listeners.clear();
-    namedListeners.clear();
-    _pendingTotal = 0;
-}

package/dist/src/retry.d.ts

@@ -1,9 +0,0 @@
-/** Abort-aware sleep. Rejects with AbortError if the signal fires
- *  before the timeout elapses. Resolves immediately for ms <= 0. */
-export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
-/** Wait for the browser to come back online, or for the signal to abort. */
-export declare function waitForOnline(signal: AbortSignal): Promise<void>;
-/** Attach attempt count to a thrown error (non-enumerable property). */
-export declare function attachAttempts(e: unknown, attempts: number): void;
-/** Read the attempt count attached by runWithRetry, or undefined. */
-export declare function readAttempts(e: unknown): number | undefined;

package/dist/src/retry.js

@@ -1,78 +0,0 @@
-// 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, signal) {
-    if (signal.aborted) {
-        return Promise.reject(new DOMException("aborted", "AbortError"));
-    }
-    if (ms <= 0) {
-        return Promise.resolve();
-    }
-    return new Promise((resolve, reject) => {
-        const t = setTimeout(() => {
-            signal.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            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) {
-    if (typeof navigator === "undefined" || navigator.onLine) {
-        return Promise.resolve();
-    }
-    if (signal.aborted) {
-        return Promise.reject(new DOMException("aborted", "AbortError"));
-    }
-    return new Promise((resolve, reject) => {
-        const onOnline = () => {
-            cleanup();
-            resolve();
-        };
-        const onAbort = () => {
-            cleanup();
-            reject(new DOMException("aborted", "AbortError"));
-        };
-        function cleanup() {
-            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, attempts) {
-    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) {
-    try {
-        if (typeof e === "object" && e !== null && "_attempts" in e) {
-            const val = e._attempts;
-            return typeof val === "number" ? val : undefined;
-        }
-    }
-    catch {
-        /* Proxy or getter threw — skip */
-    }
-    return undefined;
-}

package/dist/src/transport.d.ts

@@ -1,46 +0,0 @@
-import type { Action, 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>;
-/**
- * Configure the global transport adapter. Call once at app boot.
- * Only needed if using `transportAction`.
- */
-export declare function configureTransport(fn: TransportSendFn): void;
-/** @internal Test-only: reset the transport to unconfigured state. */
-export declare function _resetTransportForTest(): void;
-/** 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 declare function transportAction<TArgs, TOp = unknown>(def: TransportActionDefinition<TArgs, TOp>): Action<TArgs, void>;
-export {};

package/dist/src/transport.js

@@ -1,70 +0,0 @@
-// 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";
-let _send;
-/**
- * Configure the global transport adapter. Call once at app boot.
- * Only needed if using `transportAction`.
- */
-export function configureTransport(fn) {
-    _send = fn;
-}
-/** @internal Test-only: reset the transport to unconfigured state. */
-export function _resetTransportForTest() {
-    _send = undefined;
-}
-/**
- * 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(def) {
-    const { command, ...rest } = def;
-    // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- void used as generic type argument
-    return defineAction({
-        ...rest,
-        run: async (args, signal, ctx) => {
-            if (_send === undefined) {
-                throw new ActionError("Transport not configured — call configureTransport() at boot", {
-                    code: "transport_not_configured",
-                });
-            }
-            const raw = command(args);
-            let cmd;
-            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: r.status };
-                if (r.code !== undefined) {
-                    errOpts.code = r.code;
-                }
-                throw new ActionError(r.error ?? `send failed (${String(r.status)})`, errOpts);
-            }
-            return undefined;
-        },
-    });
-}

package/dist/src/types.d.ts

@@ -1,157 +0,0 @@
-/** 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 declare const RETRY_STANDARD: RetryConfig;
-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;

package/dist/src/types.js

@@ -1,7 +0,0 @@
-// 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.
-// ---------------------------------------------------------------------------
-/** Standard retry config: 2 retries, 300ms initial delay. */
-export const RETRY_STANDARD = { count: 2, delay: 300 };