atomirx 0.0.1 → 0.0.4

package/src/core/select.ts

@@ -1,6 +1,16 @@
 import { isPromiseLike } from "./isPromiseLike";
-import { getAtomState, trackPromise } from "./promiseCache";
-import { Atom, AtomValue, SettledResult } from "./types";
+import { getAtomState } from "./getAtomState";
+import { createCombinedPromise } from "./promiseCache";
+import { isAtom } from "./isAtom";
+import {
+  Atom,
+  AtomValue,
+  KeyedResult,
+  Pipeable,
+  SelectStateResult,
+  SettledResult,
+} from "./types";
+import { withUse } from "./withUse";
 
 // AggregateError polyfill for environments that don't support it
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -33,11 +43,19 @@ export interface SelectResult<T> {
   dependencies: Set<Atom<unknown>>;
 }
 
+/**
+ * Result type for safe() - error-first tuple.
+ * Either [undefined, T] for success or [unknown, undefined] for error.
+ */
+export type SafeResult<T> =
+  | [error: undefined, result: T]
+  | [error: unknown, result: undefined];
+
 /**
  * Context object passed to selector functions.
  * Provides utilities for reading atoms and handling async operations.
  */
-export interface SelectContext {
+export interface SelectContext extends Pipeable {
   /**
    * Read the current value of an atom.
    * Tracks the atom as a dependency.
@@ -50,79 +68,192 @@ export interface SelectContext {
    * @param atom - The atom to read
    * @returns The atom's current value (Awaited<T>)
    */
-  get<T>(atom: Atom<T>): Awaited<T>;
+  read<T>(atom: Atom<T>): Awaited<T>;
 
   /**
    * Wait for all atoms to resolve (like Promise.all).
-   * Variadic form - pass atoms as arguments.
+   * Array-based - pass atoms as an array.
    *
    * - If all atoms are ready → returns array of values
    * - If any atom has error → throws that error
    * - If any atom is loading (no fallback) → throws Promise
    * - If loading with fallback → uses staleValue
    *
-   * @param atoms - Atoms to wait for (variadic)
+   * @param atoms - Array of atoms to wait for
    * @returns Array of resolved values (same order as input)
    *
    * @example
    * ```ts
-   * const [user, posts] = all(user$, posts$);
+   * const [user, posts] = all([user$, posts$]);
    * ```
    */
-  all<A extends Atom<unknown>[]>(
-    ...atoms: A
-  ): { [K in keyof A]: AtomValue<A[K]> };
+  all<A extends Atom<unknown>[]>(atoms: A): { [K in keyof A]: AtomValue<A[K]> };
 
   /**
    * Return the first settled value (like Promise.race).
-   * Variadic form - pass atoms as arguments.
+   * Object-based - pass atoms as a record with keys.
    *
-   * - If any atom is ready → returns first ready value
+   * - If any atom is ready → returns `{ key, value }` for first ready
    * - If any atom has error → throws first error
    * - If all atoms are loading → throws first Promise
    *
+   * The `key` in the result identifies which atom won the race.
+   *
    * Note: race() does NOT use fallback - it's meant for first "real" settled value.
    *
-   * @param atoms - Atoms to race (variadic)
-   * @returns First settled value
+   * @param atoms - Record of atoms to race
+   * @returns KeyedResult with winning key and value
+   *
+   * @example
+   * ```ts
+   * const result = race({ cache: cache$, api: api$ });
+   * console.log(result.key);   // "cache" or "api"
+   * console.log(result.value); // The winning value
+   * ```
    */
-  race<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+  race<T extends Record<string, Atom<unknown>>>(
+    atoms: T
+  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
 
   /**
    * Return the first ready value (like Promise.any).
-   * Variadic form - pass atoms as arguments.
+   * Object-based - pass atoms as a record with keys.
    *
-   * - If any atom is ready → returns first ready value
+   * - If any atom is ready → returns `{ key, value }` for first ready
    * - If all atoms have errors → throws AggregateError
    * - If any loading (not all errored) → throws Promise
    *
+   * The `key` in the result identifies which atom resolved first.
+   *
    * Note: any() does NOT use fallback - it waits for a real ready value.
    *
-   * @param atoms - Atoms to check (variadic)
-   * @returns First ready value
+   * @param atoms - Record of atoms to check
+   * @returns KeyedResult with winning key and value
+   *
+   * @example
+   * ```ts
+   * const result = any({ primary: primaryApi$, fallback: fallbackApi$ });
+   * console.log(result.key);   // "primary" or "fallback"
+   * console.log(result.value); // The winning value
+   * ```
    */
-  any<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+  any<T extends Record<string, Atom<unknown>>>(
+    atoms: T
+  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
 
   /**
    * Get all atom statuses when all are settled (like Promise.allSettled).
-   * Variadic form - pass atoms as arguments.
+   * Array-based - pass atoms as an array.
    *
    * - If all atoms are settled → returns array of statuses
    * - If any atom is loading (no fallback) → throws Promise
    * - If loading with fallback → { status: "ready", value: staleValue }
    *
-   * @param atoms - Atoms to check (variadic)
+   * @param atoms - Array of atoms to check
    * @returns Array of settled results
+   *
+   * @example
+   * ```ts
+   * const [userResult, postsResult] = settled([user$, posts$]);
+   * ```
    */
   settled<A extends Atom<unknown>[]>(
-    ...atoms: A
+    atoms: A
   ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
+
+  /**
+   * Safely execute a function, catching errors but preserving Suspense.
+   *
+   * - If function succeeds → returns [undefined, result]
+   * - If function throws Error → returns [error, undefined]
+   * - If function throws Promise → re-throws (preserves Suspense)
+   *
+   * Use this when you need error handling inside selectors without
+   * accidentally catching Suspense promises.
+   *
+   * @param fn - Function to execute safely
+   * @returns Error-first tuple: [error, result]
+   *
+   * @example
+   * ```ts
+   * const data$ = derived(({ get, safe }) => {
+   *   const [err, data] = safe(() => {
+   *     const raw = get(raw$);
+   *     return JSON.parse(raw); // Can throw SyntaxError
+   *   });
+   *
+   *   if (err) {
+   *     return { error: err.message };
+   *   }
+   *   return { data };
+   * });
+   * ```
+   */
+  safe<T>(fn: () => T): SafeResult<T>;
+
+  /**
+   * Get the async state of an atom or selector without throwing.
+   *
+   * Unlike `read()` which throws promises/errors (Suspense pattern),
+   * `state()` always returns a `SelectStateResult<T>` object that you can
+   * inspect and handle inline.
+   *
+   * All properties (`status`, `value`, `error`) are always present,
+   * enabling easy destructuring:
+   * ```ts
+   * const { status, value, error } = state(atom$);
+   * ```
+   *
+   * @param atom - The atom to get state from
+   * @returns SelectStateResult with status, value, error (no promise - for equality)
+   *
+   * @example
+   * ```ts
+   * // Get state of single atom
+   * const dashboard$ = derived(({ state }) => {
+   *   const userState = state(user$);
+   *   const postsState = state(posts$);
+   *
+   *   return {
+   *     user: userState.value, // undefined if not ready
+   *     isLoading: userState.status === 'loading' || postsState.status === 'loading',
+   *   };
+   * });
+   * ```
+   */
+  state<T>(atom: Atom<T>): SelectStateResult<Awaited<T>>;
+
+  /**
+   * Get the async state of a selector function without throwing.
+   *
+   * Wraps the selector in try/catch and returns the result as a
+   * `SelectStateResult<T>` object. Useful for getting state of combined
+   * operations like `all()`, `race()`, etc.
+   *
+   * @param selector - Function that may throw promises or errors
+   * @returns SelectStateResult with status, value, error (no promise - for equality)
+   *
+   * @example
+   * ```ts
+   * // Get state of combined operation
+   * const allData$ = derived(({ state, all }) => {
+   *   const result = state(() => all(a$, b$, c$));
+   *
+   *   if (result.status === 'loading') return { loading: true };
+   *   if (result.status === 'error') return { error: result.error };
+   *   return { data: result.value };
+   * });
+   * ```
+   */
+  state<T>(selector: () => T): SelectStateResult<T>;
 }
 
 /**
  * Selector function type for context-based API.
  */
-export type ContextSelectorFn<T> = (context: SelectContext) => T;
+export type ReactiveSelector<T, C extends SelectContext = SelectContext> = (
+  context: C
+) => T;
 
 /**
  * Custom error for when all atoms in `any()` are rejected.
@@ -145,7 +276,7 @@ export class AllAtomsRejectedError extends Error {
  * Selects/computes a value from atom(s) with dependency tracking.
  *
  * This is the core computation logic used by `derived()`. It:
- * 1. Creates a context with `get`, `all`, `any`, `race`, `settled` utilities
+ * 1. Creates a context with `read`, `all`, `any`, `race`, `settled`, `safe` utilities
  * 2. Tracks which atoms are accessed during computation
  * 3. Returns a result with value/error/promise and dependencies
  *
@@ -158,40 +289,128 @@ export class AllAtomsRejectedError extends Error {
  * If your selector returns a Promise, it will throw an error. This is because:
  * - `select()` is designed for synchronous derivation from atoms
  * - Async atoms should be created using `atom(Promise)` directly
- * - Use `get()` to read async atoms - it handles Suspense-style loading
+ * - Use `read()` to read async atoms - it handles Suspense-style loading
  *
  * ```ts
  * // ❌ WRONG - Don't return a Promise from selector
  * select(({ get }) => fetch('/api/data'));
  *
- * // ✅ CORRECT - Create async atom and read with get()
+ * // ✅ CORRECT - Create async atom and read with read()
  * const data$ = atom(fetch('/api/data').then(r => r.json()));
- * select(({ get }) => get(data$)); // Suspends until resolved
+ * select(({ read }) => read(data$)); // Suspends until resolved
+ * ```
+ *
+ * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
+ *
+ * **Never wrap `read()` calls in try/catch blocks.** The `read()` function throws
+ * Promises when atoms are loading (Suspense pattern). A try/catch will catch
+ * these Promises and break the Suspense mechanism.
+ *
+ * ```ts
+ * // ❌ WRONG - Catches Suspense Promise, breaks loading state
+ * select(({ read }) => {
+ *   try {
+ *     return read(asyncAtom$);
+ *   } catch (e) {
+ *     return 'fallback'; // This catches BOTH errors AND loading promises!
+ *   }
+ * });
+ *
+ * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
+ * select(({ read, safe }) => {
+ *   const [err, data] = safe(() => {
+ *     const raw = read(asyncAtom$);    // Can throw Promise (Suspense)
+ *     return JSON.parse(raw);          // Can throw Error
+ *   });
+ *
+ *   if (err) return { error: err.message };
+ *   return { data };
+ * });
+ * ```
+ *
+ * The `safe()` utility:
+ * - **Catches errors** and returns `[error, undefined]`
+ * - **Re-throws Promises** to preserve Suspense behavior
+ * - Returns `[undefined, result]` on success
+ *
+ * ## IMPORTANT: SelectContext Methods Are Synchronous Only
+ *
+ * **All context methods (`read`, `all`, `race`, `any`, `settled`, `safe`) must be
+ * called synchronously during selector execution.** They cannot be used in async
+ * callbacks like `setTimeout`, `Promise.then`, or event handlers.
+ *
+ * ```ts
+ * // ❌ WRONG - Calling read() in async callback
+ * select(({ read }) => {
+ *   setTimeout(() => {
+ *     read(atom$); // Error: called outside selection context
+ *   }, 100);
+ *   return 'value';
+ * });
+ *
+ * // ❌ WRONG - Storing read() for later use
+ * let savedRead;
+ * select(({ read }) => {
+ *   savedRead = read; // Don't do this!
+ *   return read(atom$);
+ * });
+ * savedRead(atom$); // Error: called outside selection context
+ *
+ * // ✅ CORRECT - For async access, use atom.get() directly
+ * effect(({ read }) => {
+ *   const config = read(config$);
+ *   setTimeout(async () => {
+ *     // Use atom.get() for async access
+ *     const data = await asyncAtom$.get();
+ *     console.log(data);
+ *   }, 100);
+ * });
  * ```
  *
  * @template T - The type of the computed value
  * @param fn - Context-based selector function (must return sync value)
  * @returns SelectResult with value, error, promise, and dependencies
  * @throws Error if selector returns a Promise or PromiseLike
+ * @throws Error if context methods are called outside selection context
  *
  * @example
  * ```ts
- * select(({ get, all }) => {
- *   const user = get(user$);
- *   const [posts, comments] = all(posts$, comments$);
+ * select(({ read, all }) => {
+ *   const user = read(user$);
+ *   const [posts, comments] = all([posts$, comments$]);
  *   return { user, posts, comments };
  * });
  * ```
  */
-export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
+export function select<T>(fn: ReactiveSelector<T>): SelectResult<T> {
   // Track accessed dependencies during computation
   const dependencies = new Set<Atom<unknown>>();
 
+  // Flag to detect calls outside selection context (e.g., in async callbacks)
+  let isExecuting = true;
+
+  /**
+   * Throws an error if called outside the synchronous selection context.
+   * This catches common mistakes like using get() in async callbacks.
+   */
+  const assertExecuting = (methodName: string) => {
+    if (!isExecuting) {
+      throw new Error(
+        `${methodName}() was called outside of the selection context. ` +
+          "This usually happens when calling context methods in async callbacks (setTimeout, Promise.then, etc.). " +
+          "All atom reads must happen synchronously during selector execution. " +
+          "For async access, use atom.get() directly (e.g., myMutableAtom$.get() or await myDerivedAtom$.get())."
+      );
+    }
+  };
+
   /**
    * Read atom value using getAtomState().
-   * Implements the v2 get() behavior from spec.
+   * Implements Suspense-like behavior.
    */
-  const get = <V>(atom: Atom<V>): Awaited<V> => {
+  const read = <V>(atom: Atom<V>): Awaited<V> => {
+    assertExecuting("read");
+
     // Track this atom as accessed dependency
     dependencies.add(atom as Atom<unknown>);
 
@@ -209,12 +428,15 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
 
   /**
    * all() - like Promise.all
+   * Array-based: waits for ALL loading atoms in parallel
    */
   const all = <A extends Atom<unknown>[]>(
-    ...atoms: A
+    atoms: A
   ): { [K in keyof A]: AtomValue<A[K]> } => {
+    assertExecuting("all");
+
     const results: unknown[] = [];
-    let loadingPromise: Promise<unknown> | null = null;
+    const loadingPromises: Promise<unknown>[] = [];
 
     for (const atom of atoms) {
       dependencies.add(atom);
@@ -230,17 +452,15 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
           throw state.error;
 
         case "loading":
-          // First loading without fallback → will throw
-          if (!loadingPromise) {
-            loadingPromise = state.promise;
-          }
+          // Collect ALL loading promises for parallel waiting
+          loadingPromises.push(state.promise!);
           break;
       }
     }
 
-    // If any loading without fallback → throw Promise
-    if (loadingPromise) {
-      throw loadingPromise;
+    // If any loading → throw combined Promise.all for parallel waiting
+    if (loadingPromises.length > 0) {
+      throw createCombinedPromise("all", loadingPromises);
     }
 
     return results as { [K in keyof A]: AtomValue<A[K]> };
@@ -248,36 +468,41 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
 
   /**
    * race() - like Promise.race
+   * Object-based: races all atoms, returns { key, value } for winner
    */
-  const race = <A extends Atom<unknown>[]>(
-    ...atoms: A
-  ): AtomValue<A[number]> => {
-    let firstLoadingPromise: Promise<unknown> | null = null;
+  const race = <T extends Record<string, Atom<unknown>>>(
+    atoms: T
+  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>> => {
+    assertExecuting("race");
 
-    for (const atom of atoms) {
+    const loadingPromises: Promise<unknown>[] = [];
+    const entries = Object.entries(atoms);
+
+    for (const [key, atom] of entries) {
       dependencies.add(atom);
 
       // For race(), we need raw state without fallback handling
-      const state = getAtomStateRaw(atom);
+      const state = getAtomState(atom);
 
       switch (state.status) {
         case "ready":
-          return state.value as AtomValue<A[number]>;
+          return {
+            key: key as keyof T & string,
+            value: state.value as AtomValue<T[keyof T]>,
+          };
 
         case "error":
           throw state.error;
 
         case "loading":
-          if (!firstLoadingPromise) {
-            firstLoadingPromise = state.promise;
-          }
+          loadingPromises.push(state.promise!);
           break;
       }
     }
 
-    // All loading → throw first Promise
-    if (firstLoadingPromise) {
-      throw firstLoadingPromise;
+    // All loading → race them (first to settle wins)
+    if (loadingPromises.length > 0) {
+      throw createCombinedPromise("race", loadingPromises);
     }
 
     throw new Error("race() called with no atoms");
@@ -285,38 +510,43 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
 
   /**
    * any() - like Promise.any
+   * Object-based: returns { key, value } for first ready atom
    */
-  const any = <A extends Atom<unknown>[]>(
-    ...atoms: A
-  ): AtomValue<A[number]> => {
+  const any = <T extends Record<string, Atom<unknown>>>(
+    atoms: T
+  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>> => {
+    assertExecuting("any");
+
     const errors: unknown[] = [];
-    let firstLoadingPromise: Promise<unknown> | null = null;
+    const loadingPromises: Promise<unknown>[] = [];
+    const entries = Object.entries(atoms);
 
-    for (const atom of atoms) {
+    for (const [key, atom] of entries) {
       dependencies.add(atom);
 
       // For any(), we need raw state without fallback handling
-      const state = getAtomStateRaw(atom);
+      const state = getAtomState(atom);
 
       switch (state.status) {
         case "ready":
-          return state.value as AtomValue<A[number]>;
+          return {
+            key: key as keyof T & string,
+            value: state.value as AtomValue<T[keyof T]>,
+          };
 
         case "error":
           errors.push(state.error);
           break;
 
         case "loading":
-          if (!firstLoadingPromise) {
-            firstLoadingPromise = state.promise;
-          }
+          loadingPromises.push(state.promise!);
           break;
       }
     }
 
-    // If any loading → throw Promise (might still fulfill)
-    if (firstLoadingPromise) {
-      throw firstLoadingPromise;
+    // If any loading → race them all (first to resolve wins)
+    if (loadingPromises.length > 0) {
+      throw createCombinedPromise("race", loadingPromises);
     }
 
     // All errored → throw AggregateError
@@ -325,12 +555,15 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
 
   /**
    * settled() - like Promise.allSettled
+   * Array-based: waits for ALL atoms in parallel
    */
   const settled = <A extends Atom<unknown>[]>(
-    ...atoms: A
+    atoms: A
   ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> } => {
+    assertExecuting("settled");
+
     const results: SettledResult<unknown>[] = [];
-    let pendingPromise: Promise<unknown> | null = null;
+    const loadingPromises: Promise<unknown>[] = [];
 
     for (const atom of atoms) {
       dependencies.add(atom);
@@ -346,24 +579,114 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
           break;
 
         case "loading":
-          // Loading without fallback → will throw
-          if (!pendingPromise) {
-            pendingPromise = state.promise;
-          }
+          // Collect ALL loading promises for parallel waiting
+          loadingPromises.push(state.promise!);
           break;
       }
     }
 
-    // If any loading without fallback → throw Promise
-    if (pendingPromise) {
-      throw pendingPromise;
+    // If any loading → throw combined Promise.allSettled for parallel waiting
+    // (allSettled never rejects, so we wait for ALL to settle regardless of success/failure)
+    if (loadingPromises.length > 0) {
+      throw createCombinedPromise("allSettled", loadingPromises);
     }
 
     return results as { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
   };
 
+  /**
+   * safe() - Execute function with error handling, preserving Suspense
+   */
+  const safe = <T>(fn: () => T): SafeResult<T> => {
+    assertExecuting("safe");
+
+    try {
+      const result = fn();
+      return [undefined, result];
+    } catch (e) {
+      // Re-throw Promises to preserve Suspense behavior
+      if (isPromiseLike(e)) {
+        throw e;
+      }
+      // Return errors as tuple instead of throwing
+      return [e, undefined];
+    }
+  };
+
+  /**
+   * state() - Get async state without throwing
+   * Overloaded: accepts atom or selector function
+   * Returns SelectStateResult with placeholder props for equality-friendly comparisons
+   */
+  function state<T>(atom: Atom<T>): SelectStateResult<Awaited<T>>;
+  function state<T>(selector: () => T): SelectStateResult<T>;
+  function state<T>(
+    atomOrSelector: Atom<T> | (() => T)
+  ): SelectStateResult<Awaited<T>> | SelectStateResult<T> {
+    assertExecuting("state");
+
+    // Atom shorthand - get state directly and convert to SelectStateResult
+    if (isAtom(atomOrSelector)) {
+      dependencies.add(atomOrSelector as Atom<unknown>);
+      const atomState = getAtomState(atomOrSelector);
+
+      // Convert AtomState to SelectStateResult (remove promise, add placeholders)
+      switch (atomState.status) {
+        case "ready":
+          return {
+            status: "ready",
+            value: atomState.value,
+            error: undefined,
+          } as SelectStateResult<Awaited<T>>;
+        case "error":
+          return {
+            status: "error",
+            value: undefined,
+            error: atomState.error,
+          } as SelectStateResult<Awaited<T>>;
+        case "loading":
+          return {
+            status: "loading",
+            value: undefined,
+            error: undefined,
+          } as SelectStateResult<Awaited<T>>;
+      }
+    }
+
+    // Selector function - wrap in try/catch
+    try {
+      const value = atomOrSelector();
+      return {
+        status: "ready",
+        value,
+        error: undefined,
+      } as SelectStateResult<T>;
+    } catch (e) {
+      if (isPromiseLike(e)) {
+        return {
+          status: "loading",
+          value: undefined,
+          error: undefined,
+        } as SelectStateResult<T>;
+      }
+      return {
+        status: "error",
+        value: undefined,
+        error: e,
+      } as SelectStateResult<T>;
+    }
+  }
+
   // Create the context
-  const context: SelectContext = { get, all, any, race, settled };
+  const context: SelectContext = withUse({
+    read,
+    all,
+    any,
+    race,
+    settled,
+    safe,
+    state,
+  });
 
   // Execute the selector function
   try {
@@ -399,56 +722,8 @@ export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
         dependencies,
       };
     }
-  }
-}
-
-// ============================================================================
-// Internal helpers
-// ============================================================================
-
-// Note: trackPromise is already imported at the top
-
-/**
- * Gets raw atom state WITHOUT fallback handling.
- * Used by race() and any() which need the actual loading state.
- */
-function getAtomStateRaw<T>(
-  atom: Atom<T>
-):
-  | { status: "ready"; value: Awaited<T> }
-  | { status: "error"; error: unknown }
-  | { status: "loading"; promise: Promise<Awaited<T>> } {
-  const value = atom.value;
-
-  // 1. Sync value - ready
-  if (!isPromiseLike(value)) {
-    return {
-      status: "ready",
-      value: value as Awaited<T>,
-    };
-  }
-
-  // 2. Promise value - check state via promiseCache
-  const state = trackPromise(value);
-
-  switch (state.status) {
-    case "fulfilled":
-      return {
-        status: "ready",
-        value: state.value as Awaited<T>,
-      };
-
-    case "rejected":
-      return {
-        status: "error",
-        error: state.error,
-      };
-
-    case "pending":
-      // Raw - don't use fallback
-      return {
-        status: "loading",
-        promise: state.promise as Promise<Awaited<T>>,
-      };
+  } finally {
+    // Mark execution as complete to catch async misuse
+    isExecuting = false;
   }
 }