atomirx 0.0.1

package/src/core/select.ts

@@ -0,0 +1,454 @@
+import { isPromiseLike } from "./isPromiseLike";
+import { getAtomState, trackPromise } from "./promiseCache";
+import { Atom, AtomValue, SettledResult } from "./types";
+
+// 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>>;
+}
+
+/**
+ * Context object passed to selector functions.
+ * Provides utilities for reading atoms and handling async operations.
+ */
+export interface SelectContext {
+  /**
+   * 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>)
+   */
+  get<T>(atom: Atom<T>): Awaited<T>;
+
+  /**
+   * Wait for all atoms to resolve (like Promise.all).
+   * Variadic form - pass atoms as arguments.
+   *
+   * - 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)
+   * @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).
+   * Variadic form - pass atoms as arguments.
+   *
+   * - If any atom is ready → returns first ready value
+   * - If any atom has error → throws first error
+   * - If all atoms are loading → throws first Promise
+   *
+   * Note: race() does NOT use fallback - it's meant for first "real" settled value.
+   *
+   * @param atoms - Atoms to race (variadic)
+   * @returns First settled value
+   */
+  race<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+
+  /**
+   * Return the first ready value (like Promise.any).
+   * Variadic form - pass atoms as arguments.
+   *
+   * - If any atom is ready → returns first ready value
+   * - If all atoms have errors → throws AggregateError
+   * - If any loading (not all errored) → throws Promise
+   *
+   * Note: any() does NOT use fallback - it waits for a real ready value.
+   *
+   * @param atoms - Atoms to check (variadic)
+   * @returns First ready value
+   */
+  any<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+
+  /**
+   * Get all atom statuses when all are settled (like Promise.allSettled).
+   * Variadic form - pass atoms as arguments.
+   *
+   * - 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)
+   * @returns Array of settled results
+   */
+  settled<A extends Atom<unknown>[]>(
+    ...atoms: A
+  ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
+}
+
+/**
+ * Selector function type for context-based API.
+ */
+export type ContextSelectorFn<T> = (context: SelectContext) => 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 `get`, `all`, `any`, `race`, `settled` 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 `get()` 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()
+ * const data$ = atom(fetch('/api/data').then(r => r.json()));
+ * select(({ get }) => get(data$)); // Suspends until resolved
+ * ```
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * select(({ get, all }) => {
+ *   const user = get(user$);
+ *   const [posts, comments] = all(posts$, comments$);
+ *   return { user, posts, comments };
+ * });
+ * ```
+ */
+export function select<T>(fn: ContextSelectorFn<T>): SelectResult<T> {
+  // Track accessed dependencies during computation
+  const dependencies = new Set<Atom<unknown>>();
+
+  /**
+   * Read atom value using getAtomState().
+   * Implements the v2 get() behavior from spec.
+   */
+  const get = <V>(atom: Atom<V>): Awaited<V> => {
+    // 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
+   */
+  const all = <A extends Atom<unknown>[]>(
+    ...atoms: A
+  ): { [K in keyof A]: AtomValue<A[K]> } => {
+    const results: unknown[] = [];
+    let loadingPromise: Promise<unknown> | null = null;
+
+    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":
+          // First loading without fallback → will throw
+          if (!loadingPromise) {
+            loadingPromise = state.promise;
+          }
+          break;
+      }
+    }
+
+    // If any loading without fallback → throw Promise
+    if (loadingPromise) {
+      throw loadingPromise;
+    }
+
+    return results as { [K in keyof A]: AtomValue<A[K]> };
+  };
+
+  /**
+   * race() - like Promise.race
+   */
+  const race = <A extends Atom<unknown>[]>(
+    ...atoms: A
+  ): AtomValue<A[number]> => {
+    let firstLoadingPromise: Promise<unknown> | null = null;
+
+    for (const atom of atoms) {
+      dependencies.add(atom);
+
+      // For race(), we need raw state without fallback handling
+      const state = getAtomStateRaw(atom);
+
+      switch (state.status) {
+        case "ready":
+          return state.value as AtomValue<A[number]>;
+
+        case "error":
+          throw state.error;
+
+        case "loading":
+          if (!firstLoadingPromise) {
+            firstLoadingPromise = state.promise;
+          }
+          break;
+      }
+    }
+
+    // All loading → throw first Promise
+    if (firstLoadingPromise) {
+      throw firstLoadingPromise;
+    }
+
+    throw new Error("race() called with no atoms");
+  };
+
+  /**
+   * any() - like Promise.any
+   */
+  const any = <A extends Atom<unknown>[]>(
+    ...atoms: A
+  ): AtomValue<A[number]> => {
+    const errors: unknown[] = [];
+    let firstLoadingPromise: Promise<unknown> | null = null;
+
+    for (const atom of atoms) {
+      dependencies.add(atom);
+
+      // For any(), we need raw state without fallback handling
+      const state = getAtomStateRaw(atom);
+
+      switch (state.status) {
+        case "ready":
+          return state.value as AtomValue<A[number]>;
+
+        case "error":
+          errors.push(state.error);
+          break;
+
+        case "loading":
+          if (!firstLoadingPromise) {
+            firstLoadingPromise = state.promise;
+          }
+          break;
+      }
+    }
+
+    // If any loading → throw Promise (might still fulfill)
+    if (firstLoadingPromise) {
+      throw firstLoadingPromise;
+    }
+
+    // All errored → throw AggregateError
+    throw new AggregateErrorClass(errors, "All atoms rejected");
+  };
+
+  /**
+   * settled() - like Promise.allSettled
+   */
+  const settled = <A extends Atom<unknown>[]>(
+    ...atoms: A
+  ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> } => {
+    const results: SettledResult<unknown>[] = [];
+    let pendingPromise: Promise<unknown> | null = null;
+
+    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":
+          // Loading without fallback → will throw
+          if (!pendingPromise) {
+            pendingPromise = state.promise;
+          }
+          break;
+      }
+    }
+
+    // If any loading without fallback → throw Promise
+    if (pendingPromise) {
+      throw pendingPromise;
+    }
+
+    return results as { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
+  };
+
+  // Create the context
+  const context: SelectContext = { get, all, any, race, settled };
+
+  // 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,
+      };
+    }
+  }
+}
+
+// ============================================================================
+// 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>>,
+      };
+  }
+}

package/src/core/selector.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect } from "vitest";
+import { atom } from "./atom";
+import { select } from "./select";
+
+describe("select", () => {
+  describe("get()", () => {
+    it("should read value from sync atom", () => {
+      const count$ = atom(5);
+      const result = select(({ get }) => get(count$));
+
+      expect(result.value).toBe(5);
+      expect(result.error).toBe(undefined);
+      expect(result.promise).toBe(undefined);
+    });
+
+    it("should track dependencies", () => {
+      const a$ = atom(1);
+      const b$ = atom(2);
+
+      const result = select(({ get }) => get(a$) + get(b$));
+
+      expect(result.dependencies.size).toBe(2);
+      expect(result.dependencies.has(a$)).toBe(true);
+      expect(result.dependencies.has(b$)).toBe(true);
+    });
+
+    it("should throw error if computation throws", () => {
+      const count$ = atom(5);
+      const error = new Error("Test error");
+
+      const result = select(({ get }) => {
+        get(count$);
+        throw error;
+      });
+
+      expect(result.value).toBe(undefined);
+      expect(result.error).toBe(error);
+      expect(result.promise).toBe(undefined);
+    });
+  });
+
+  describe("all()", () => {
+    it("should return array of values for all sync atoms", () => {
+      const a$ = atom(1);
+      const b$ = atom(2);
+      const c$ = atom(3);
+
+      const result = select(({ all }) => all(a$, b$, c$));
+
+      expect(result.value).toEqual([1, 2, 3]);
+    });
+
+    it("should throw promise if any atom is pending", () => {
+      const a$ = atom(1);
+      const b$ = atom(new Promise<number>(() => {}));
+
+      const result = select(({ all }) => all(a$, b$));
+
+      expect(result.promise).toBeDefined();
+      expect(result.value).toBe(undefined);
+    });
+
+    it("should throw error if any atom has rejected promise", async () => {
+      const error = new Error("Test error");
+      const a$ = atom(1);
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {}); // Prevent unhandled rejection
+      const b$ = atom(rejectedPromise);
+
+      // First call to select tracks the promise but returns pending
+      select(({ all }) => all(a$, b$));
+
+      // Wait for promise handlers to run
+      await Promise.resolve();
+      await Promise.resolve();
+
+      // Now the promise state should be updated
+      const result = select(({ all }) => all(a$, b$));
+
+      expect(result.error).toBe(error);
+    });
+  });
+
+  describe("race()", () => {
+    it("should return first fulfilled value", () => {
+      const a$ = atom(1);
+      const b$ = atom(2);
+
+      const result = select(({ race }) => race(a$, b$));
+
+      expect(result.value).toBe(1);
+    });
+
+    it("should throw first error if first atom is rejected", async () => {
+      const error = new Error("Test error");
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {});
+      const a$ = atom(rejectedPromise);
+      const b$ = atom(2);
+
+      // Track the promise first
+      select(({ race }) => race(a$, b$));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const result = select(({ race }) => race(a$, b$));
+
+      expect(result.error).toBe(error);
+    });
+
+    it("should throw promise if all are pending", () => {
+      const a$ = atom(new Promise<number>(() => {}));
+      const b$ = atom(new Promise<number>(() => {}));
+
+      const result = select(({ race }) => race(a$, b$));
+
+      expect(result.promise).toBeDefined();
+    });
+  });
+
+  describe("any()", () => {
+    it("should return first fulfilled value", () => {
+      const a$ = atom(1);
+      const b$ = atom(2);
+
+      const result = select(({ any }) => any(a$, b$));
+
+      expect(result.value).toBe(1);
+    });
+
+    it("should skip rejected and return next fulfilled", async () => {
+      const error = new Error("Test error");
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {});
+      const a$ = atom(rejectedPromise);
+      const b$ = atom(2);
+
+      // Track first, then wait for microtasks
+      select(({ any }) => any(a$, b$));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const result = select(({ any }) => any(a$, b$));
+
+      expect(result.value).toBe(2);
+    });
+
+    it("should throw AggregateError if all rejected", async () => {
+      const error1 = new Error("Error 1");
+      const error2 = new Error("Error 2");
+      const p1 = Promise.reject(error1);
+      const p2 = Promise.reject(error2);
+      p1.catch(() => {});
+      p2.catch(() => {});
+
+      const a$ = atom(p1);
+      const b$ = atom(p2);
+
+      // Track first, then wait for microtasks
+      select(({ any }) => any(a$, b$));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const result = select(({ any }) => any(a$, b$));
+
+      expect(result.error).toBeDefined();
+      expect((result.error as Error).name).toBe("AggregateError");
+    });
+  });
+
+  describe("settled()", () => {
+    it("should return array of settled results", async () => {
+      const a$ = atom(1);
+      const error = new Error("Test error");
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {});
+      const b$ = atom(rejectedPromise);
+
+      // Track first, wait for microtasks
+      select(({ settled }) => settled(a$, b$));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const result = select(({ settled }) => settled(a$, b$));
+
+      expect(result.value).toEqual([
+        { status: "ready", value: 1 },
+        { status: "error", error },
+      ]);
+    });
+
+    it("should throw promise if any atom is pending", () => {
+      const a$ = atom(1);
+      const b$ = atom(new Promise<number>(() => {}));
+
+      const result = select(({ settled }) => settled(a$, b$));
+
+      expect(result.promise).toBeDefined();
+    });
+  });
+
+  describe("conditional dependencies", () => {
+    it("should only track accessed atoms", () => {
+      const condition$ = atom(false);
+      const a$ = atom(1);
+      const b$ = atom(2);
+
+      const result = select(({ get }) => (get(condition$) ? get(a$) : get(b$)));
+
+      expect(result.dependencies.size).toBe(2);
+      expect(result.dependencies.has(condition$)).toBe(true);
+      expect(result.dependencies.has(b$)).toBe(true);
+      // a$ was not accessed because condition was false
+      expect(result.dependencies.has(a$)).toBe(false);
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw error if selector returns a Promise", () => {
+      const result = select(() => Promise.resolve(42));
+
+      expect(result.error).toBeDefined();
+      expect(result.error).toBeInstanceOf(Error);
+      expect((result.error as Error).message).toContain(
+        "select() selector must return a synchronous value"
+      );
+      expect(result.value).toBe(undefined);
+      expect(result.promise).toBe(undefined);
+    });
+
+    it("should throw error if selector returns a PromiseLike", () => {
+      // Custom PromiseLike object
+      const promiseLike = {
+        then: (resolve: (value: number) => void) => {
+          resolve(42);
+          return promiseLike;
+        },
+      };
+
+      const result = select(() => promiseLike);
+
+      expect(result.error).toBeDefined();
+      expect(result.error).toBeInstanceOf(Error);
+      expect((result.error as Error).message).toContain(
+        "select() selector must return a synchronous value"
+      );
+    });
+
+    it("should work fine with sync values", () => {
+      const result = select(() => 42);
+
+      expect(result.value).toBe(42);
+      expect(result.error).toBe(undefined);
+      expect(result.promise).toBe(undefined);
+    });
+  });
+});