atomirx 0.0.8 → 0.1.1

package/src/core/select.ts

@@ -1,729 +0,0 @@
-import { isPromiseLike } from "./isPromiseLike";
-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
-declare const AggregateError: any;
-const AggregateErrorClass =
-  typeof AggregateError !== "undefined"
-    ? AggregateError
-    : class AggregateErrorPolyfill extends Error {
-        errors: unknown[];
-        constructor(errors: unknown[], message?: string) {
-          super(message);
-          this.name = "AggregateError";
-          this.errors = errors;
-        }
-      };
-
-/**
- * Result of a select computation.
- *
- * @template T - The type of the computed value
- */
-export interface SelectResult<T> {
-  /** The computed value (undefined if error or loading) */
-  value: T | undefined;
-  /** Error thrown during computation (undefined if success or loading) */
-  error: unknown;
-  /** Promise thrown during computation - indicates loading state */
-  promise: PromiseLike<unknown> | undefined;
-  /** Set of atoms that were accessed during computation */
-  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 extends Pipeable {
-  /**
-   * Read the current value of an atom.
-   * Tracks the atom as a dependency.
-   *
-   * Suspense-like behavior using getAtomState():
-   * - If ready: returns value
-   * - If error: throws error
-   * - If loading: throws Promise (Suspense)
-   *
-   * @param atom - The atom to read
-   * @returns The atom's current value (Awaited<T>)
-   */
-  read<T>(atom: Atom<T>): Awaited<T>;
-
-  /**
-   * Wait for all atoms to resolve (like Promise.all).
-   * 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 - Array of atoms to wait for
-   * @returns Array of resolved values (same order as input)
-   *
-   * @example
-   * ```ts
-   * const [user, posts] = all([user$, posts$]);
-   * ```
-   */
-  all<A extends Atom<unknown>[]>(atoms: A): { [K in keyof A]: AtomValue<A[K]> };
-
-  /**
-   * Return the first settled value (like Promise.race).
-   * Object-based - pass atoms as a record with keys.
-   *
-   * - 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 - 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<T extends Record<string, Atom<unknown>>>(
-    atoms: T
-  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
-
-  /**
-   * Return the first ready value (like Promise.any).
-   * Object-based - pass atoms as a record with keys.
-   *
-   * - 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 - 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<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).
-   * 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 - 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
-  ): { [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 ReactiveSelector<T, C extends SelectContext = SelectContext> = (
-  context: C
-) => T;
-
-/**
- * Custom error for when all atoms in `any()` are rejected.
- */
-export class AllAtomsRejectedError extends Error {
-  readonly errors: unknown[];
-
-  constructor(errors: unknown[], message = "All atoms rejected") {
-    super(message);
-    this.name = "AllAtomsRejectedError";
-    this.errors = errors;
-  }
-}
-
-// ============================================================================
-// select() - Core selection/computation function
-// ============================================================================
-
-/**
- * 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 `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
- *
- * All context methods use `getAtomState()` internally.
- *
- * ## IMPORTANT: Selector Must Return Synchronous Value
- *
- * **The selector function MUST NOT return a Promise or PromiseLike value.**
- *
- * 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 `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 read()
- * const data$ = atom(fetch('/api/data').then(r => r.json()));
- * 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(({ read, all }) => {
- *   const user = read(user$);
- *   const [posts, comments] = all([posts$, comments$]);
- *   return { user, posts, comments };
- * });
- * ```
- */
-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 Suspense-like behavior.
-   */
-  const read = <V>(atom: Atom<V>): Awaited<V> => {
-    assertExecuting("read");
-
-    // Track this atom as accessed dependency
-    dependencies.add(atom as Atom<unknown>);
-
-    const state = getAtomState(atom);
-
-    switch (state.status) {
-      case "ready":
-        return state.value;
-      case "error":
-        throw state.error;
-      case "loading":
-        throw state.promise; // Suspense pattern
-    }
-  };
-
-  /**
-   * all() - like Promise.all
-   * Array-based: waits for ALL loading atoms in parallel
-   */
-  const all = <A extends Atom<unknown>[]>(
-    atoms: A
-  ): { [K in keyof A]: AtomValue<A[K]> } => {
-    assertExecuting("all");
-
-    const results: unknown[] = [];
-    const loadingPromises: Promise<unknown>[] = [];
-
-    for (const atom of atoms) {
-      dependencies.add(atom);
-      const state = getAtomState(atom);
-
-      switch (state.status) {
-        case "ready":
-          results.push(state.value);
-          break;
-
-        case "error":
-          // Any error → throw immediately
-          throw state.error;
-
-        case "loading":
-          // Collect ALL loading promises for parallel waiting
-          loadingPromises.push(state.promise!);
-          break;
-      }
-    }
-
-    // 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]> };
-  };
-
-  /**
-   * race() - like Promise.race
-   * Object-based: races all atoms, returns { key, value } for winner
-   */
-  const race = <T extends Record<string, Atom<unknown>>>(
-    atoms: T
-  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>> => {
-    assertExecuting("race");
-
-    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 = getAtomState(atom);
-
-      switch (state.status) {
-        case "ready":
-          return {
-            key: key as keyof T & string,
-            value: state.value as AtomValue<T[keyof T]>,
-          };
-
-        case "error":
-          throw state.error;
-
-        case "loading":
-          loadingPromises.push(state.promise!);
-          break;
-      }
-    }
-
-    // All loading → race them (first to settle wins)
-    if (loadingPromises.length > 0) {
-      throw createCombinedPromise("race", loadingPromises);
-    }
-
-    throw new Error("race() called with no atoms");
-  };
-
-  /**
-   * any() - like Promise.any
-   * Object-based: returns { key, value } for first ready atom
-   */
-  const any = <T extends Record<string, Atom<unknown>>>(
-    atoms: T
-  ): KeyedResult<keyof T & string, AtomValue<T[keyof T]>> => {
-    assertExecuting("any");
-
-    const errors: unknown[] = [];
-    const loadingPromises: Promise<unknown>[] = [];
-    const entries = Object.entries(atoms);
-
-    for (const [key, atom] of entries) {
-      dependencies.add(atom);
-
-      // For any(), we need raw state without fallback handling
-      const state = getAtomState(atom);
-
-      switch (state.status) {
-        case "ready":
-          return {
-            key: key as keyof T & string,
-            value: state.value as AtomValue<T[keyof T]>,
-          };
-
-        case "error":
-          errors.push(state.error);
-          break;
-
-        case "loading":
-          loadingPromises.push(state.promise!);
-          break;
-      }
-    }
-
-    // If any loading → race them all (first to resolve wins)
-    if (loadingPromises.length > 0) {
-      throw createCombinedPromise("race", loadingPromises);
-    }
-
-    // All errored → throw AggregateError
-    throw new AggregateErrorClass(errors, "All atoms rejected");
-  };
-
-  /**
-   * settled() - like Promise.allSettled
-   * Array-based: waits for ALL atoms in parallel
-   */
-  const settled = <A extends Atom<unknown>[]>(
-    atoms: A
-  ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> } => {
-    assertExecuting("settled");
-
-    const results: SettledResult<unknown>[] = [];
-    const loadingPromises: Promise<unknown>[] = [];
-
-    for (const atom of atoms) {
-      dependencies.add(atom);
-      const state = getAtomState(atom);
-
-      switch (state.status) {
-        case "ready":
-          results.push({ status: "ready", value: state.value });
-          break;
-
-        case "error":
-          results.push({ status: "error", error: state.error });
-          break;
-
-        case "loading":
-          // Collect ALL loading promises for parallel waiting
-          loadingPromises.push(state.promise!);
-          break;
-      }
-    }
-
-    // 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 = withUse({
-    read,
-    all,
-    any,
-    race,
-    settled,
-    safe,
-    state,
-  });
-
-  // Execute the selector function
-  try {
-    const result = fn(context);
-
-    // Selector must return synchronous value, not a Promise
-    if (isPromiseLike(result)) {
-      throw new Error(
-        "select() selector must return a synchronous value, not a Promise. " +
-          "For async data, create an async atom with atom(Promise) and use get() to read it."
-      );
-    }
-
-    return {
-      value: result,
-      error: undefined,
-      promise: undefined,
-      dependencies,
-    };
-  } catch (thrown) {
-    if (isPromiseLike(thrown)) {
-      return {
-        value: undefined,
-        error: undefined,
-        promise: thrown,
-        dependencies,
-      };
-    } else {
-      return {
-        value: undefined,
-        error: thrown,
-        promise: undefined,
-        dependencies,
-      };
-    }
-  } finally {
-    // Mark execution as complete to catch async misuse
-    isExecuting = false;
-  }
-}