atomirx 0.0.7 → 0.1.0

package/src/react/useSelector.test.ts

@@ -1,182 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { renderHook, act, waitFor } from "@testing-library/react";
-import { atom } from "../core/atom";
-import { useSelector } from "./useSelector";
-
-describe("useSelector", () => {
-  describe("basic functionality", () => {
-    it("should read value from sync atom", () => {
-      const count$ = atom(5);
-      const { result } = renderHook(() => useSelector(count$));
-      expect(result.current).toBe(5);
-    });
-
-    it("should update when atom value changes", async () => {
-      const count$ = atom(0);
-      const { result } = renderHook(() => useSelector(count$));
-
-      expect(result.current).toBe(0);
-
-      act(() => {
-        count$.set(10);
-      });
-
-      await waitFor(() => {
-        expect(result.current).toBe(10);
-      });
-    });
-
-    it("should work with object values", () => {
-      const user$ = atom({ name: "John", age: 30 });
-      const { result } = renderHook(() => useSelector(user$));
-
-      expect(result.current).toEqual({ name: "John", age: 30 });
-    });
-  });
-
-  describe("selector function", () => {
-    it("should support selector function", () => {
-      const count$ = atom(5);
-      const { result } = renderHook(() =>
-        useSelector(({ read }) => read(count$) * 2)
-      );
-
-      expect(result.current).toBe(10);
-    });
-
-    it("should derive from multiple atoms", () => {
-      const a$ = atom(2);
-      const b$ = atom(3);
-      const { result } = renderHook(() =>
-        useSelector(({ read }) => read(a$) + read(b$))
-      );
-
-      expect(result.current).toBe(5);
-    });
-
-    it("should update when any source atom changes", async () => {
-      const a$ = atom(2);
-      const b$ = atom(3);
-      const { result } = renderHook(() =>
-        useSelector(({ read }) => read(a$) * read(b$))
-      );
-
-      expect(result.current).toBe(6);
-
-      act(() => {
-        a$.set(5);
-      });
-
-      await waitFor(() => {
-        expect(result.current).toBe(15);
-      });
-    });
-  });
-
-  describe("conditional dependencies", () => {
-    it("should track conditional dependencies", async () => {
-      const showDetails$ = atom(false);
-      const summary$ = atom("Brief");
-      const details$ = atom("Detailed");
-
-      const { result } = renderHook(() =>
-        useSelector(({ read }) =>
-          read(showDetails$) ? read(details$) : read(summary$)
-        )
-      );
-
-      expect(result.current).toBe("Brief");
-
-      act(() => {
-        showDetails$.set(true);
-      });
-
-      await waitFor(() => {
-        expect(result.current).toBe("Detailed");
-      });
-    });
-  });
-
-  describe("equality checks", () => {
-    it("should use shallow equality by default", async () => {
-      const renderCount = vi.fn();
-      const source$ = atom({ a: 1 });
-
-      const { result } = renderHook(() => {
-        renderCount();
-        return useSelector(source$);
-      });
-
-      expect(result.current).toEqual({ a: 1 });
-
-      act(() => {
-        source$.set({ a: 1 }); // Same content, different reference
-      });
-
-      // With shallow equality, same content should not cause re-render
-      // (depends on implementation)
-    });
-
-    it("should support custom equality", async () => {
-      const source$ = atom({ id: 1, name: "John" });
-      const { result } = renderHook(() =>
-        useSelector(source$, (a, b) => a.id === b.id)
-      );
-
-      expect(result.current.name).toBe("John");
-
-      act(() => {
-        source$.set({ id: 1, name: "Jane" }); // Same id
-      });
-
-      // Custom equality by id - should not re-render
-    });
-  });
-
-  describe("context utilities", () => {
-    it("should support all() in selector", () => {
-      const a$ = atom(1);
-      const b$ = atom(2);
-      const c$ = atom(3);
-
-      const { result } = renderHook(() =>
-        useSelector(({ all }) => {
-          const [a, b, c] = all([a$, b$, c$]);
-          return a + b + c;
-        })
-      );
-
-      expect(result.current).toBe(6);
-    });
-  });
-
-  describe("cleanup", () => {
-    it("should unsubscribe on unmount", async () => {
-      const count$ = atom(0);
-      const { unmount } = renderHook(() => useSelector(count$));
-
-      unmount();
-
-      // After unmount, setting the atom should not cause issues
-      act(() => {
-        count$.set(100);
-      });
-
-      // No error should be thrown
-    });
-  });
-
-  // Note: Async/Suspense tests require proper Suspense boundary setup
-  // which is more complex to test. The following are placeholder tests.
-
-  describe("async atoms", () => {
-    it("should throw promise for pending atom (Suspense)", () => {
-      // When an atom's value is a pending Promise, useSelector should throw
-      // the Promise to trigger Suspense. This is hard to test without
-      // proper Suspense boundary setup.
-      // The hook will throw the Promise which is caught by Suspense
-      // Testing this properly requires a Suspense wrapper
-      expect(true).toBe(true); // Placeholder
-    });
-  });
-});

package/src/react/useSelector.ts

@@ -1,292 +0,0 @@
-import { useCallback, useRef, useSyncExternalStore } from "react";
-import { ReactiveSelector, select } from "../core/select";
-import { Atom, Equality } from "../core/types";
-import { resolveEquality } from "../core/equality";
-import { isAtom } from "../core/isAtom";
-
-/**
- * React hook that selects/derives a value from atom(s) with automatic subscriptions.
- *
- * Uses `useSyncExternalStore` for proper React 18+ concurrent mode support.
- * Only subscribes to atoms that are actually accessed during selection.
- *
- * ## IMPORTANT: Selector Must Return Synchronous Value
- *
- * **The selector function MUST NOT be async or return a Promise.**
- *
- * ```tsx
- * // ❌ WRONG - Don't use async function
- * useSelector(async ({ read }) => {
- *   const data = await fetch('/api');
- *   return data;
- * });
- *
- * // ❌ WRONG - Don't return a Promise
- * useSelector(({ read }) => fetch('/api').then(r => r.json()));
- *
- * // ✅ CORRECT - Create async atom and read with read()
- * const data$ = atom(fetch('/api').then(r => r.json()));
- * useSelector(({ 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.
- *
- * ```tsx
- * // ❌ WRONG - Catches Suspense Promise, breaks loading state
- * const data = useSelector(({ read }) => {
- *   try {
- *     return read(asyncAtom$);
- *   } catch (e) {
- *     return null; // This catches BOTH errors AND loading promises!
- *   }
- * });
- *
- * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
- * const result = useSelector(({ 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: Suspense-Style API
- *
- * This hook uses a **Suspense-style API** for async atoms:
- * - When an atom is **loading**, the getter throws a Promise (suspends)
- * - When an atom has an **error**, the getter throws the error
- * - When an atom is **resolved**, the getter returns the value
- *
- * This means:
- * - **You MUST wrap components with `<Suspense>`** to handle loading states
- * - **You MUST wrap components with `<ErrorBoundary>`** to handle errors
- *
- * ## Alternative: useAsyncState for Non-Suspense
- *
- * If you want to handle loading/error states imperatively without Suspense:
- *
- * ```tsx
- * import { useAsyncState } from 'atomirx/react';
- *
- * function MyComponent() {
- *   const state = useAsyncState(myAtom$);
- *
- *   if (state.status === "loading") return <Spinner />;
- *   if (state.status === "error") return <Error error={state.error} />;
- *   return <div>{state.value}</div>;
- * }
- * ```
- *
- * @template T - The type of the selected value
- * @param selectorOrAtom - Atom or context-based selector function (must return sync value)
- * @param equals - Equality function or shorthand. Defaults to "shallow"
- * @returns The selected value (Awaited<T>)
- * @throws Promise when loading (caught by Suspense)
- * @throws Error when failed (caught by ErrorBoundary)
- *
- * @example Single atom (shorthand)
- * ```tsx
- * const count = atom(5);
- *
- * function Counter() {
- *   const value = useSelector(count);
- *   return <div>{value}</div>;
- * }
- * ```
- *
- * @example With selector
- * ```tsx
- * const count = atom(5);
- *
- * function Counter() {
- *   const doubled = useSelector(({ read }) => read(count) * 2);
- *   return <div>{doubled}</div>;
- * }
- * ```
- *
- * @example Multiple atoms
- * ```tsx
- * const firstName = atom("John");
- * const lastName = atom("Doe");
- *
- * function FullName() {
- *   const fullName = useSelector(({ read }) =>
- *     `${read(firstName)} ${read(lastName)}`
- *   );
- *   return <div>{fullName}</div>;
- * }
- * ```
- *
- * @example Async atom with Suspense
- * ```tsx
- * const userAtom = atom(fetchUser());
- *
- * function UserProfile() {
- *   const user = useSelector(({ read }) => read(userAtom));
- *   return <div>{user.name}</div>;
- * }
- *
- * // MUST wrap with Suspense and ErrorBoundary
- * function App() {
- *   return (
- *     <ErrorBoundary fallback={<div>Error!</div>}>
- *       <Suspense fallback={<div>Loading...</div>}>
- *         <UserProfile />
- *       </Suspense>
- *     </ErrorBoundary>
- *   );
- * }
- * ```
- *
- * @example Using all() for multiple async atoms
- * ```tsx
- * const userAtom = atom(fetchUser());
- * const postsAtom = atom(fetchPosts());
- *
- * function Dashboard() {
- *   const data = useSelector(({ all }) => {
- *     const [user, posts] = all(userAtom, postsAtom);
- *     return { user, posts };
- *   });
- *
- *   return <DashboardContent user={data.user} posts={data.posts} />;
- * }
- * ```
- */
-// Overload: Pass atom directly
-export function useSelector<T>(
-  atom: Atom<T>,
-  equals?: Equality<Awaited<T>>
-): Awaited<T>;
-
-// Overload: Context-based selector function
-export function useSelector<T>(
-  selector: ReactiveSelector<T>,
-  equals?: Equality<T>
-): T;
-
-export function useSelector<T>(
-  selectorOrAtom: ReactiveSelector<T> | Atom<T>,
-  equals?: Equality<T>
-): T {
-  // Convert atom shorthand to context selector
-  const selector: ReactiveSelector<T> = isAtom(selectorOrAtom)
-    ? ({ read }) => read(selectorOrAtom as Atom<T>) as T
-    : (selectorOrAtom as ReactiveSelector<T>);
-
-  // Default to shallow equality
-  const eq = resolveEquality((equals as Equality<unknown>) ?? "shallow");
-
-  // Store selector in ref to avoid recreating callbacks
-  const selectorRef = useRef(selector);
-  const eqRef = useRef(eq);
-
-  // Update refs on each render
-  selectorRef.current = selector;
-  eqRef.current = eq;
-
-  // Track current dependencies and their unsubscribe functions
-  const subscriptionsRef = useRef<Map<Atom<unknown>, VoidFunction>>(new Map());
-  const dependenciesRef = useRef<Set<Atom<unknown>>>(new Set());
-
-  // Cache the last snapshot
-  const snapshotRef = useRef<{ value: T; initialized: boolean }>({
-    value: undefined as T,
-    initialized: false,
-  });
-
-  /**
-   * Get the current snapshot by running the selector.
-   */
-  const getSnapshot = useCallback(() => {
-    const result = select(selectorRef.current);
-
-    // Update dependencies
-    dependenciesRef.current = result.dependencies;
-
-    // Handle Suspense-style states
-    if (result.promise !== undefined) {
-      // Loading state - throw Promise
-      throw result.promise;
-    }
-
-    if (result.error !== undefined) {
-      // Error state - throw error
-      throw result.error;
-    }
-
-    // Success - check equality and update cache
-    const newValue = result.value as T;
-
-    if (
-      !snapshotRef.current.initialized ||
-      !eqRef.current(newValue, snapshotRef.current.value)
-    ) {
-      snapshotRef.current = { value: newValue, initialized: true };
-    }
-
-    return snapshotRef.current.value;
-  }, []);
-
-  /**
-   * Subscribe to atom changes.
-   */
-  const subscribe = useCallback((onStoreChange: () => void) => {
-    const subscriptions = subscriptionsRef.current;
-
-    const updateSubscriptions = () => {
-      const currentDeps = dependenciesRef.current;
-
-      // Unsubscribe from atoms no longer dependencies
-      for (const [atom, unsubscribe] of subscriptions) {
-        if (!currentDeps.has(atom)) {
-          unsubscribe();
-          subscriptions.delete(atom);
-        }
-      }
-
-      // Subscribe to new dependencies
-      for (const atom of currentDeps) {
-        if (!subscriptions.has(atom)) {
-          const unsubscribe = atom.on(() => {
-            // Re-run selector to update dependencies
-            const result = select(selectorRef.current);
-            dependenciesRef.current = result.dependencies;
-
-            // Update subscriptions if dependencies changed
-            updateSubscriptions();
-
-            // Notify React
-            onStoreChange();
-          });
-          subscriptions.set(atom, unsubscribe);
-        }
-      }
-    };
-
-    // Initial subscription setup
-    updateSubscriptions();
-
-    // Cleanup function
-    return () => {
-      for (const unsubscribe of subscriptions.values()) {
-        unsubscribe();
-      }
-      subscriptions.clear();
-    };
-  }, []);
-
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}