@cplieger/actions 1.0.0

package/dist/src/define.js

@@ -0,0 +1,627 @@
+// defineAction: the lifecycle runner. Takes an ActionDefinition,
+// returns an Action whose dispatch() executes the full lifecycle.
+// ---------------------------------------------------------------------------
+import { notifyError, notifySuccess } from "./notifier.js";
+import { toActionError } from "./error.js";
+import { record } from "./registry.js";
+import { sleep, waitForOnline, attachAttempts, readAttempts } from "./retry.js";
+import { _registerAction } from "./cleanup.js";
+import { safeInvoke, safeStringify, _resetSymbols, resolveNotification, defaultErrorPrefix, } from "./define-helpers.js";
+let instanceCounter = 0;
+const NO_OPTS = Object.freeze({});
+const NOOP = () => {
+    /* noop */
+};
+/** Create the appropriate DOMException for an aborted signal, preserving
+ *  TimeoutError when the signal was aborted by AbortSignal.timeout(). */
+function signalAbortError(signal) {
+    if (signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") {
+        return signal.reason;
+    }
+    return new DOMException("aborted", "AbortError");
+}
+function nextInstanceID(name) {
+    instanceCounter += 1;
+    return `${name}#${String(instanceCounter)}`;
+}
+/** Header name used by apiAction when an idempotency key is generated. */
+export const IDEMPOTENCY_HEADER = "Idempotency-Key";
+function generateIdempotencyKey() {
+    const ts = Date.now().toString(36);
+    const rnd = Math.random().toString(36).slice(2, 16).padEnd(14, "0");
+    return `${ts}-${rnd}`;
+}
+const scopeChains = new Map();
+/** Create a DispatchHandle: a Promise augmented with abort(). */
+function makeHandle(promise, abortFn) {
+    const handle = promise;
+    handle.abort = abortFn;
+    return handle;
+}
+const activeDedupes = new Map();
+/**
+ * Create an action from a declarative definition.
+ */
+export function defineAction(def) {
+    const inFlight = new Map();
+    const started = new Set();
+    const scopeSkipResolvers = new Map();
+    const scopePrevs = new Map();
+    const scopeCancelResolvers = new Map();
+    const activeDedupeKeys = new Set();
+    function fireDefSuccess(result, args) {
+        if (def.onSuccess) {
+            const cb = def.onSuccess;
+            safeInvoke(def.name, "def.onSuccess", () => {
+                cb(result, args);
+            });
+        }
+    }
+    function fireDefError(err, args) {
+        if (def.onError) {
+            const cb = def.onError;
+            safeInvoke(def.name, "def.onError", () => {
+                cb(err, args);
+            });
+        }
+    }
+    function fireDefSettled(args) {
+        if (def.onSettled) {
+            const cb = def.onSettled;
+            safeInvoke(def.name, "def.onSettled", () => {
+                cb(args);
+            });
+        }
+    }
+    function dispatch(args, opts = NO_OPTS) {
+        const dedupeKey = dedupeKeyFor(args);
+        if (dedupeKey !== null) {
+            const entry = activeDedupes.get(dedupeKey);
+            if (entry !== undefined) {
+                const shared = entry.promise;
+                if (shared === undefined) {
+                    const onSettledCb = opts.onSettled;
+                    if (onSettledCb) {
+                        safeInvoke(def.name, "onSettled", () => {
+                            onSettledCb(args);
+                        });
+                    }
+                    return makeHandle(Promise.resolve(null), NOOP);
+                }
+                const joined = shared.then((v) => {
+                    if (v !== null) {
+                        const onSuccessCb = opts.onSuccess;
+                        if (onSuccessCb) {
+                            safeInvoke(def.name, "onSuccess", () => {
+                                onSuccessCb(v, args);
+                            });
+                        }
+                    }
+                    else if (entry.error !== undefined) {
+                        const capturedErr = entry.error;
+                        const onErrorCb = opts.onError;
+                        if (onErrorCb) {
+                            safeInvoke(def.name, "onError", () => {
+                                onErrorCb(capturedErr, args);
+                            });
+                        }
+                    }
+                    else if (entry.cancelled !== true) {
+                        const onErrorCb = opts.onError;
+                        if (onErrorCb) {
+                            safeInvoke(def.name, "onError", () => {
+                                onErrorCb({ message: "deduped dispatch did not succeed", code: "dedupe" }, args);
+                            });
+                        }
+                    }
+                    const onSettledCb = opts.onSettled;
+                    if (onSettledCb) {
+                        safeInvoke(def.name, "onSettled", () => {
+                            onSettledCb(args);
+                        });
+                    }
+                    return v;
+                }, () => {
+                    const onSettledCb = opts.onSettled;
+                    if (onSettledCb) {
+                        safeInvoke(def.name, "onSettled", () => {
+                            onSettledCb(args);
+                        });
+                    }
+                    return null;
+                });
+                return makeHandle(joined, NOOP);
+            }
+        }
+        const scopeKey = typeof def.scope === "function"
+            ? def.scope(args)
+            : typeof def.scope === "string"
+                ? def.scope
+                : null;
+        const ac = new AbortController();
+        const id = nextInstanceID(def.name);
+        inFlight.set(id, ac);
+        const dispatchedAt = Date.now();
+        const dedupeEntry = dedupeKey !== null ? { promise: undefined } : null;
+        let result;
+        if (scopeKey === null) {
+            result = runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt);
+        }
+        else {
+            const prev = scopeChains.get(scopeKey) ?? Promise.resolve();
+            const next = prev.then(() => runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt));
+            let tailResolve;
+            const tail = new Promise((r) => {
+                tailResolve = r;
+            });
+            scopeSkipResolvers.set(id, tailResolve);
+            scopePrevs.set(id, prev);
+            void next.then(tailResolve, tailResolve);
+            scopeChains.set(scopeKey, tail);
+            void next
+                .finally(() => {
+                scopeSkipResolvers.delete(id);
+                scopeCancelResolvers.delete(id);
+                scopePrevs.delete(id);
+                if (scopeChains.get(scopeKey) === tail) {
+                    scopeChains.delete(scopeKey);
+                }
+            })
+                .catch(NOOP);
+            let earlyCancelResolve;
+            const earlyCancel = new Promise((r) => {
+                earlyCancelResolve = r;
+            });
+            scopeCancelResolvers.set(id, () => {
+                try {
+                    const now = Date.now();
+                    if (dedupeEntry !== null) {
+                        dedupeEntry.cancelled = true;
+                    }
+                    evictDedupeSlot(dedupeKey, dedupeEntry);
+                    record({
+                        id,
+                        name: def.name,
+                        status: "cancelled",
+                        args,
+                        dispatchedAt,
+                        startedAt: now,
+                        completedAt: now,
+                    });
+                }
+                finally {
+                    fireDefSettled(args);
+                    const onSettledCb = opts.onSettled;
+                    if (onSettledCb) {
+                        safeInvoke(def.name, "onSettled", () => {
+                            onSettledCb(args);
+                        });
+                    }
+                    earlyCancelResolve(null);
+                }
+            });
+            result = Promise.race([next, earlyCancel]);
+        }
+        if (dedupeKey !== null && dedupeEntry !== null) {
+            dedupeEntry.promise = result;
+            activeDedupes.set(dedupeKey, dedupeEntry);
+            activeDedupeKeys.add(dedupeKey);
+            void result.finally(() => {
+                if (activeDedupes.get(dedupeKey) === dedupeEntry) {
+                    activeDedupes.delete(dedupeKey);
+                    activeDedupeKeys.delete(dedupeKey);
+                }
+            });
+        }
+        return makeHandle(result, () => {
+            ac.abort();
+        });
+    }
+    function dedupeKeyFor(args) {
+        const cfg = def.dedupe;
+        if (cfg === undefined || cfg === false) {
+            return null;
+        }
+        const argKey = typeof cfg === "function" ? cfg(args) : safeStringify(args);
+        return `${def.name}::${argKey}`;
+    }
+    function evictDedupeSlot(dk, entry) {
+        if (dk !== null && entry !== null && activeDedupes.get(dk) === entry) {
+            activeDedupes.delete(dk);
+            activeDedupeKeys.delete(dk);
+        }
+    }
+    async function runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt) {
+        started.add(id);
+        if (!inFlight.has(id) && ac.signal.aborted) {
+            started.delete(id);
+            return null;
+        }
+        const settle = () => {
+            inFlight.delete(id);
+            started.delete(id);
+            const onSettledCb = opts.onSettled;
+            if (onSettledCb) {
+                safeInvoke(def.name, "onSettled", () => {
+                    onSettledCb(args);
+                });
+            }
+        };
+        if (ac.signal.aborted) {
+            const now = Date.now();
+            if (dedupeEntry !== null) {
+                dedupeEntry.cancelled = true;
+            }
+            evictDedupeSlot(dedupeKey, dedupeEntry);
+            record({
+                id,
+                name: def.name,
+                status: "cancelled",
+                args,
+                dispatchedAt,
+                startedAt: now,
+                completedAt: now,
+            });
+            fireDefSettled(args);
+            settle();
+            return null;
+        }
+        const startedAt = Date.now();
+        const idemKey = typeof def.idempotencyKey === "function"
+            ? def.idempotencyKey(args)
+            : def.idempotencyKey === true
+                ? generateIdempotencyKey()
+                : null;
+        const ctx = idemKey !== null ? { instanceID: id, idempotencyKey: idemKey } : { instanceID: id };
+        // Compose timeout signal if configured
+        const runSignal = def.timeout !== undefined
+            ? AbortSignal.any([ac.signal, AbortSignal.timeout(def.timeout)])
+            : ac.signal;
+        let optOp;
+        if (def.optimistic !== undefined) {
+            try {
+                optOp = def.optimistic(args);
+            }
+            catch (e) {
+                const raw = toActionError(e);
+                const err = raw.code !== undefined ? raw : { ...raw, code: "optimistic_failed" };
+                if (dedupeEntry !== null) {
+                    dedupeEntry.error = err;
+                }
+                evictDedupeSlot(dedupeKey, dedupeEntry);
+                record({
+                    id,
+                    name: def.name,
+                    status: "error",
+                    args,
+                    dispatchedAt,
+                    startedAt,
+                    completedAt: Date.now(),
+                    error: err,
+                });
+                emitErrorToast(args, err);
+                fireDefError(err, args);
+                const onErrorCb = opts.onError;
+                if (onErrorCb) {
+                    safeInvoke(def.name, "onError", () => {
+                        onErrorCb(err, args);
+                    });
+                }
+                fireDefSettled(args);
+                settle();
+                return null;
+            }
+        }
+        record({
+            id,
+            name: def.name,
+            status: "pending",
+            args,
+            dispatchedAt,
+            startedAt,
+        });
+        try {
+            const { result, attempts } = await runWithRetry(args, runSignal, ctx);
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- signal state changes during async
+            if (ac.signal.aborted) {
+                if (dedupeEntry !== null) {
+                    dedupeEntry.cancelled = true;
+                }
+                evictDedupeSlot(dedupeKey, dedupeEntry);
+                record({
+                    id,
+                    name: def.name,
+                    status: "cancelled",
+                    args,
+                    dispatchedAt,
+                    startedAt,
+                    completedAt: Date.now(),
+                    attempts,
+                });
+                if (def.rollback !== undefined) {
+                    try {
+                        def.rollback(args, optOp, { message: "cancelled", code: "cancelled" });
+                    }
+                    catch (e) {
+                        console.error(`[actions] rollback (cancellation) for ${def.name} threw`, e);
+                    }
+                }
+                fireDefSettled(args);
+                return null;
+            }
+            record({
+                id,
+                name: def.name,
+                status: "success",
+                args,
+                dispatchedAt,
+                startedAt,
+                completedAt: Date.now(),
+                result,
+                attempts,
+            });
+            evictDedupeSlot(dedupeKey, dedupeEntry);
+            emitSuccessToast(args, result, opts);
+            fireDefSuccess(result, args);
+            const onSuccessCb = opts.onSuccess;
+            if (onSuccessCb) {
+                safeInvoke(def.name, "onSuccess", () => {
+                    onSuccessCb(result, args);
+                });
+            }
+            fireDefSettled(args);
+            return result;
+        }
+        catch (e) {
+            const err = toActionError(e);
+            const attempts = readAttempts(e);
+            const cancelled = ac.signal.aborted;
+            const status = cancelled ? "cancelled" : "error";
+            if (dedupeEntry !== null) {
+                if (cancelled) {
+                    dedupeEntry.cancelled = true;
+                }
+                else {
+                    dedupeEntry.error = err;
+                }
+            }
+            evictDedupeSlot(dedupeKey, dedupeEntry);
+            record({
+                id,
+                name: def.name,
+                status,
+                args,
+                dispatchedAt,
+                startedAt,
+                completedAt: Date.now(),
+                ...(!cancelled && { error: err }),
+                ...(attempts !== undefined && { attempts }),
+            });
+            if (def.rollback !== undefined) {
+                try {
+                    const rbError = cancelled ? { message: "cancelled", code: "cancelled" } : err;
+                    def.rollback(args, optOp, rbError);
+                }
+                catch (rbCaught) {
+                    console.error(`[actions] rollback for ${def.name} threw`, rbCaught);
+                }
+            }
+            if (!cancelled) {
+                emitErrorToast(args, err);
+                fireDefError(err, args);
+                const onErrorCb = opts.onError;
+                if (onErrorCb) {
+                    safeInvoke(def.name, "onError", () => {
+                        onErrorCb(err, args);
+                    });
+                }
+            }
+            fireDefSettled(args);
+            return null;
+        }
+        finally {
+            settle();
+        }
+    }
+    async function runWithRetry(args, signal, ctx) {
+        const cfg = def.retry;
+        const maxAttempts = (cfg?.count ?? 0) + 1;
+        const baseDelay = cfg?.delay;
+        const factor = cfg?.factor ?? 2;
+        const networkMode = def.networkMode ?? "online";
+        let attempt = 0;
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop with throw exits
+        while (true) {
+            if (signal.aborted) {
+                const abortErr = signalAbortError(signal);
+                attachAttempts(abortErr, attempt);
+                throw abortErr;
+            }
+            try {
+                attempt++;
+                const result = await def.run(args, signal, ctx);
+                return { result, attempts: attempt };
+            }
+            catch (e) {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- signal state changes during async
+                if (signal.aborted) {
+                    attachAttempts(e, attempt);
+                    throw e;
+                }
+                if (attempt >= maxAttempts) {
+                    attachAttempts(e, attempt);
+                    throw e;
+                }
+                const err = toActionError(e);
+                if (!shouldRetry(err)) {
+                    attachAttempts(e, attempt);
+                    throw e;
+                }
+                if (networkMode === "online") {
+                    try {
+                        await waitForOnline(signal);
+                    }
+                    catch {
+                        const abortErr = signalAbortError(signal);
+                        attachAttempts(abortErr, attempt);
+                        throw abortErr;
+                    }
+                }
+                let delayMs;
+                if (typeof baseDelay === "function") {
+                    try {
+                        delayMs = baseDelay(attempt, err);
+                    }
+                    catch {
+                        delayMs = 0;
+                    }
+                }
+                else if (typeof baseDelay === "number") {
+                    delayMs = Math.min(baseDelay * Math.pow(factor, attempt - 1), 5000);
+                }
+                else {
+                    delayMs = 0;
+                }
+                try {
+                    await sleep(delayMs, signal);
+                }
+                catch {
+                    const abortErr = signalAbortError(signal);
+                    attachAttempts(abortErr, attempt);
+                    throw abortErr;
+                }
+            }
+        }
+    }
+    function shouldRetry(err) {
+        if (def.retryable === undefined) {
+            return false;
+        }
+        try {
+            return def.retryable(err);
+        }
+        catch {
+            return false;
+        }
+    }
+    function emitSuccessToast(args, result, opts) {
+        if (opts.silent === true) {
+            return;
+        }
+        try {
+            const msg = resolveNotification(def.success, args, result);
+            if (msg !== null) {
+                notifySuccess(msg);
+            }
+        }
+        catch (e) {
+            console.error(`[actions] emitSuccessToast for ${def.name} threw`, e);
+        }
+    }
+    function emitErrorToast(args, err) {
+        const spec = def.error;
+        if (spec === false) {
+            return;
+        }
+        const fallbackMsg = `${defaultErrorPrefix(def.name)}: ${err.message}`;
+        const retry = buildRetryButton(args, err);
+        try {
+            let msg;
+            if (typeof spec === "string") {
+                msg = `${spec}: ${err.message}`;
+            }
+            else if (typeof spec === "function") {
+                msg = spec(args, err);
+            }
+            else {
+                msg = fallbackMsg;
+            }
+            notifyError(msg, retry);
+        }
+        catch (e) {
+            console.error(`[actions] emitErrorToast for ${def.name} threw`, e);
+            notifyError(fallbackMsg, retry);
+        }
+    }
+    function buildRetryButton(args, err) {
+        if (!shouldRetry(err)) {
+            return undefined;
+        }
+        let frozenArgs;
+        try {
+            frozenArgs = structuredClone(args);
+        }
+        catch {
+            if (args === null || args === undefined || typeof args !== "object") {
+                frozenArgs = args;
+            }
+            else {
+                try {
+                    frozenArgs = (Array.isArray(args) ? [...args] : { ...args });
+                }
+                catch {
+                    frozenArgs = args;
+                }
+            }
+        }
+        return {
+            onClick: () => {
+                void dispatch(frozenArgs);
+            },
+        };
+    }
+    function cancel() {
+        if (inFlight.size === 0) {
+            return;
+        }
+        for (const dk of activeDedupeKeys) {
+            const entry = activeDedupes.get(dk);
+            if (entry !== undefined) {
+                entry.cancelled = true;
+            }
+            activeDedupes.delete(dk);
+        }
+        activeDedupeKeys.clear();
+        for (const [id, controller] of [...inFlight.entries()]) {
+            controller.abort();
+            if (!started.has(id)) {
+                inFlight.delete(id);
+                const skip = scopeSkipResolvers.get(id);
+                if (skip !== undefined) {
+                    const prev = scopePrevs.get(id);
+                    scopeSkipResolvers.delete(id);
+                    scopePrevs.delete(id);
+                    if (prev !== undefined) {
+                        void prev.then(skip, skip);
+                    }
+                    else {
+                        skip();
+                    }
+                }
+                const earlyCancel = scopeCancelResolvers.get(id);
+                if (earlyCancel !== undefined) {
+                    scopeCancelResolvers.delete(id);
+                    earlyCancel();
+                }
+            }
+        }
+    }
+    const action = {
+        name: def.name,
+        dispatch,
+        cancel,
+    };
+    _registerAction(action);
+    return action;
+}
+/** Test-only: reset the instance counter + scope chains + dedupe map. */
+export function _resetForTest() {
+    instanceCounter = 0;
+    _resetSymbols();
+    scopeChains.clear();
+    activeDedupes.clear();
+}
+/** Test-only: expose internal map sizes for leak verification. */
+export function _internalsForTest() {
+    return { scopeChains: scopeChains.size, activeDedupes: activeDedupes.size };
+}

package/dist/src/error.d.ts

@@ -0,0 +1,42 @@
+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 declare class ActionError extends Error implements ActionErrorLike {
+    readonly status?: number;
+    readonly code?: string;
+    readonly cause?: unknown;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** Type predicate: true when `v` is a non-null object with a string `error` property. */
+export declare function hasErrorString(v: unknown): v is {
+    error: string;
+};
+/** Coerce any thrown value into an ActionErrorLike snapshot. Internal. */
+export declare function toActionError(e: unknown): ActionErrorLike;
+/**
+ * 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 declare function classifyFetchError(e: unknown, signal: AbortSignal): ActionError;
+/**
+ * Retry classifier preset: matches network/timeout failures and transient
+ * HTTP statuses (408, 429, 502, 503, 504). Always excludes cancellation.
+ */
+export declare function retryNetwork(err: ActionErrorLike): boolean;