@cplieger/actions 1.0.0

package/dist/src/define-helpers.js

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// Pure utility helpers extracted from define.ts — independently testable
+// without instantiating the full action framework.
+// ---------------------------------------------------------------------------
+/** Invoke a callback safely — errors are caught and logged without
+ *  disrupting the dispatch lifecycle. */
+export function safeInvoke(actionName, hookName, fn) {
+    try {
+        fn();
+    }
+    catch (e) {
+        console.error(`[actions] ${hookName} callback for ${actionName} threw`, e);
+    }
+}
+/** Monotonic counter for symbol identity in dedupe keys. Symbols with
+ *  the same description are distinct values but String(sym) is identical,
+ *  so we assign each unique symbol a stable numeric ID. */
+let _symbolCounter = 0;
+export const _symbolMap = new Map();
+export function symbolId(sym) {
+    let id = _symbolMap.get(sym);
+    if (id === undefined) {
+        id = ++_symbolCounter;
+        _symbolMap.set(sym, id);
+    }
+    return id;
+}
+/** Reset symbol state — test-only. */
+export function _resetSymbols() {
+    _symbolCounter = 0;
+    _symbolMap.clear();
+}
+/** Defensive JSON.stringify — falls back to String(args) on cycles
+ *  or non-serializable values (DOM elements, functions). Used by
+ *  the default dedupe key computation. */
+export function safeStringify(args) {
+    if (args === undefined) {
+        return "undefined";
+    }
+    if (args === null || typeof args === "number" || typeof args === "boolean") {
+        return String(args);
+    }
+    if (typeof args === "string") {
+        return JSON.stringify(args);
+    }
+    if (typeof args === "bigint") {
+        return `${String(args)}n`;
+    }
+    if (typeof args === "symbol") {
+        return `@@sym${String(symbolId(args))}`;
+    }
+    try {
+        return JSON.stringify(args, (_key, value) => value === undefined ? "__undef__" : value);
+    }
+    catch {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional fallback for cyclic objects
+        return String(args);
+    }
+}
+/** Resolve a NotificationSpec to its message string. Returns null when
+ *  the spec is `false` (suppressed) or undefined and no fallback. */
+export function resolveNotification(spec, args, payload, fallback) {
+    if (spec === false) {
+        return null;
+    }
+    if (spec === undefined) {
+        return fallback ?? null;
+    }
+    if (typeof spec === "string") {
+        return spec;
+    }
+    return spec(args, payload);
+}
+/** @deprecated Use {@link resolveNotification} instead. */
+export const resolveToast = resolveNotification;
+/** Build a default error notification prefix from the action name.
+ *  Converts "chat.delete" -> "Delete failed". */
+export function defaultErrorPrefix(name) {
+    const parts = name.split(".");
+    const tail = parts[parts.length - 1] ?? name;
+    const readable = tail.replace(/[_-]/g, " ");
+    return readable.charAt(0).toUpperCase() + readable.slice(1) + " failed";
+}

package/dist/src/define.d.ts

@@ -0,0 +1,14 @@
+import type { Action, ActionDefinition } from "./types.js";
+/** Header name used by apiAction when an idempotency key is generated. */
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+/**
+ * Create an action from a declarative definition.
+ */
+export declare function defineAction<TArgs, TResult, TOp = unknown>(def: ActionDefinition<TArgs, TResult, TOp>): Action<TArgs, TResult>;
+/** Test-only: reset the instance counter + scope chains + dedupe map. */
+export declare function _resetForTest(): void;
+/** Test-only: expose internal map sizes for leak verification. */
+export declare function _internalsForTest(): {
+    scopeChains: number;
+    activeDedupes: number;
+};