atomirx 0.0.2 → 0.0.5

package/src/react/{useValue.test.ts → useSelector.test.ts}

@@ -1,19 +1,19 @@
 import { describe, it, expect, vi } from "vitest";
 import { renderHook, act, waitFor } from "@testing-library/react";
 import { atom } from "../core/atom";
-import { useValue } from "./useValue";
+import { useSelector } from "./useSelector";
 
-describe("useValue", () => {
+describe("useSelector", () => {
   describe("basic functionality", () => {
     it("should read value from sync atom", () => {
       const count$ = atom(5);
-      const { result } = renderHook(() => useValue(count$));
+      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(() => useValue(count$));
+      const { result } = renderHook(() => useSelector(count$));
 
       expect(result.current).toBe(0);
 
@@ -28,7 +28,7 @@ describe("useValue", () => {
 
     it("should work with object values", () => {
       const user$ = atom({ name: "John", age: 30 });
-      const { result } = renderHook(() => useValue(user$));
+      const { result } = renderHook(() => useSelector(user$));
 
       expect(result.current).toEqual({ name: "John", age: 30 });
     });
@@ -38,7 +38,7 @@ describe("useValue", () => {
     it("should support selector function", () => {
       const count$ = atom(5);
       const { result } = renderHook(() =>
-        useValue(({ get }) => get(count$) * 2)
+        useSelector(({ read }) => read(count$) * 2)
       );
 
       expect(result.current).toBe(10);
@@ -48,7 +48,7 @@ describe("useValue", () => {
       const a$ = atom(2);
       const b$ = atom(3);
       const { result } = renderHook(() =>
-        useValue(({ get }) => get(a$) + get(b$))
+        useSelector(({ read }) => read(a$) + read(b$))
       );
 
       expect(result.current).toBe(5);
@@ -58,7 +58,7 @@ describe("useValue", () => {
       const a$ = atom(2);
       const b$ = atom(3);
       const { result } = renderHook(() =>
-        useValue(({ get }) => get(a$) * get(b$))
+        useSelector(({ read }) => read(a$) * read(b$))
       );
 
       expect(result.current).toBe(6);
@@ -80,8 +80,8 @@ describe("useValue", () => {
       const details$ = atom("Detailed");
 
       const { result } = renderHook(() =>
-        useValue(({ get }) =>
-          get(showDetails$) ? get(details$) : get(summary$)
+        useSelector(({ read }) =>
+          read(showDetails$) ? read(details$) : read(summary$)
         )
       );
 
@@ -104,7 +104,7 @@ describe("useValue", () => {
 
       const { result } = renderHook(() => {
         renderCount();
-        return useValue(source$);
+        return useSelector(source$);
       });
 
       expect(result.current).toEqual({ a: 1 });
@@ -120,7 +120,7 @@ describe("useValue", () => {
     it("should support custom equality", async () => {
       const source$ = atom({ id: 1, name: "John" });
       const { result } = renderHook(() =>
-        useValue(source$, (a, b) => a.id === b.id)
+        useSelector(source$, (a, b) => a.id === b.id)
       );
 
       expect(result.current.name).toBe("John");
@@ -140,8 +140,8 @@ describe("useValue", () => {
       const c$ = atom(3);
 
       const { result } = renderHook(() =>
-        useValue(({ all }) => {
-          const [a, b, c] = all(a$, b$, c$);
+        useSelector(({ all }) => {
+          const [a, b, c] = all([a$, b$, c$]);
           return a + b + c;
         })
       );
@@ -153,7 +153,7 @@ describe("useValue", () => {
   describe("cleanup", () => {
     it("should unsubscribe on unmount", async () => {
       const count$ = atom(0);
-      const { unmount } = renderHook(() => useValue(count$));
+      const { unmount } = renderHook(() => useSelector(count$));
 
       unmount();
 
@@ -171,7 +171,7 @@ describe("useValue", () => {
 
   describe("async atoms", () => {
     it("should throw promise for pending atom (Suspense)", () => {
-      // When an atom's value is a pending Promise, useValue should throw
+      // 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

package/src/react/{useValue.ts → useSelector.ts}

@@ -1,7 +1,7 @@
-import { useSyncExternalStore, useCallback, useRef } from "react";
-import { select, ContextSelectorFn } from "../core/select";
-import { resolveEquality } from "../core/equality";
+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";
 
 /**
@@ -16,19 +16,52 @@ import { isAtom } from "../core/isAtom";
  *
  * ```tsx
  * // ❌ WRONG - Don't use async function
- * useValue(async ({ get }) => {
+ * useSelector(async ({ read }) => {
  *   const data = await fetch('/api');
  *   return data;
  * });
  *
  * // ❌ WRONG - Don't return a Promise
- * useValue(({ get }) => fetch('/api').then(r => r.json()));
+ * useSelector(({ read }) => fetch('/api').then(r => r.json()));
  *
- * // ✅ CORRECT - Create async atom and read with get()
+ * // ✅ CORRECT - Create async atom and read with read()
  * const data$ = atom(fetch('/api').then(r => r.json()));
- * useValue(({ get }) => get(data$)); // Suspends until resolved
+ * 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:
@@ -40,22 +73,19 @@ import { isAtom } from "../core/isAtom";
  * - **You MUST wrap components with `<Suspense>`** to handle loading states
  * - **You MUST wrap components with `<ErrorBoundary>`** to handle errors
  *
- * ## Alternative: Using staleValue for Non-Suspense
+ * ## Alternative: useAsyncState for Non-Suspense
  *
- * If you want to show loading states without Suspense:
+ * If you want to handle loading/error states imperatively without Suspense:
  *
  * ```tsx
+ * import { useAsyncState } from 'atomirx/react';
+ *
  * function MyComponent() {
- *   // Access staleValue directly - always has a value (with fallback)
- *   const count = myDerivedAtom$.staleValue;
- *   const isLoading = isPending(myDerivedAtom$.value);
+ *   const state = useAsyncState(myAtom$);
  *
- *   return (
- *     <div>
- *       {isLoading && <Spinner />}
- *       Count: {count}
- *     </div>
- *   );
+ *   if (state.status === "loading") return <Spinner />;
+ *   if (state.status === "error") return <Error error={state.error} />;
+ *   return <div>{state.value}</div>;
  * }
  * ```
  *
@@ -63,14 +93,15 @@ import { isAtom } from "../core/isAtom";
  * @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 Error if selector returns a Promise or PromiseLike
+ * @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 = useValue(count);
+ *   const value = useSelector(count);
  *   return <div>{value}</div>;
  * }
  * ```
@@ -80,7 +111,7 @@ import { isAtom } from "../core/isAtom";
  * const count = atom(5);
  *
  * function Counter() {
- *   const doubled = useValue(({ get }) => get(count) * 2);
+ *   const doubled = useSelector(({ read }) => read(count) * 2);
  *   return <div>{doubled}</div>;
  * }
  * ```
@@ -91,8 +122,8 @@ import { isAtom } from "../core/isAtom";
  * const lastName = atom("Doe");
  *
  * function FullName() {
- *   const fullName = useValue(({ get }) =>
- *     `${get(firstName)} ${get(lastName)}`
+ *   const fullName = useSelector(({ read }) =>
+ *     `${read(firstName)} ${read(lastName)}`
  *   );
  *   return <div>{fullName}</div>;
  * }
@@ -103,7 +134,7 @@ import { isAtom } from "../core/isAtom";
  * const userAtom = atom(fetchUser());
  *
  * function UserProfile() {
- *   const user = useValue(({ get }) => get(userAtom));
+ *   const user = useSelector(({ read }) => read(userAtom));
  *   return <div>{user.name}</div>;
  * }
  *
@@ -125,7 +156,7 @@ import { isAtom } from "../core/isAtom";
  * const postsAtom = atom(fetchPosts());
  *
  * function Dashboard() {
- *   const data = useValue(({ all }) => {
+ *   const data = useSelector(({ all }) => {
  *     const [user, posts] = all(userAtom, postsAtom);
  *     return { user, posts };
  *   });
@@ -135,25 +166,25 @@ import { isAtom } from "../core/isAtom";
  * ```
  */
 // Overload: Pass atom directly
-export function useValue<T>(
+export function useSelector<T>(
   atom: Atom<T>,
   equals?: Equality<Awaited<T>>
 ): Awaited<T>;
 
 // Overload: Context-based selector function
-export function useValue<T>(
-  selector: ContextSelectorFn<T>,
+export function useSelector<T>(
+  selector: ReactiveSelector<T>,
   equals?: Equality<T>
 ): T;
 
-export function useValue<T>(
-  selectorOrAtom: ContextSelectorFn<T> | Atom<T>,
+export function useSelector<T>(
+  selectorOrAtom: ReactiveSelector<T> | Atom<T>,
   equals?: Equality<T>
 ): T {
   // Convert atom shorthand to context selector
-  const selector: ContextSelectorFn<T> = isAtom(selectorOrAtom)
-    ? ({ get }) => get(selectorOrAtom as Atom<T>) as T
-    : (selectorOrAtom as ContextSelectorFn<T>);
+  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");

package/v2.md

@@ -108,13 +108,13 @@ Computed value. Always returns `Promise<T>` for `.value`.
 // Without fallback - staleValue is T | undefined
 function derived<T>(
   compute: (ctx: SelectContext) => T,
-  options?: DerivedOptions,
+  options?: DerivedOptions
 ): DerivedAtom<T, false>;
 
 // With fallback - staleValue is guaranteed T
 function derived<T>(
   compute: (ctx: SelectContext) => T,
-  options: DerivedOptions & { fallback: T },
+  options: DerivedOptions & { fallback: T }
 ): DerivedAtom<T, true>;
 
 interface DerivedOptions<T> {
@@ -387,12 +387,12 @@ function any<A extends AnyAtom<unknown>[]>(...atoms: A): AtomValue<A[number]> {
 }
 ```
 
-| Scenario       | Result                              |
-| -------------- | ----------------------------------- |
-| Any sync value | return first sync value             |
-| Any ready      | return first value                  |
-| Any loading    | throw Promise (wait for potential)  |
-| All errored    | throw `AggregateError`              |
+| Scenario       | Result                             |
+| -------------- | ---------------------------------- |
+| Any sync value | return first sync value            |
+| Any ready      | return first value                 |
+| Any loading    | throw Promise (wait for potential) |
+| All errored    | throw `AggregateError`             |
 
 > **Note:** `any()` does NOT use fallback - it waits for a real ready value.
 
@@ -437,22 +437,22 @@ function settled<A extends AnyAtom<unknown>[]>(
 }
 ```
 
-| Scenario    | Result                                   |
-| ----------- | ---------------------------------------- |
-| All settled | return `[{ status, value/error }, ...]`  |
-| Any loading | throw Promise                            |
+| Scenario    | Result                                  |
+| ----------- | --------------------------------------- |
+| All settled | return `[{ status, value/error }, ...]` |
+| Any loading | throw Promise                           |
 
 ### SelectContext Summary
 
 All methods use `getAtomState()` internally.
 
-| Method              | Returns         | Throws on Error?   |
-| ------------------- | --------------- | ------------------ |
-| `get(atom)`         | Single value    | Yes                |
-| `all(...atoms)`     | Array of values | Yes (first error)  |
-| `race(...atoms)`    | First settled   | Yes (if first)     |
-| `any(...atoms)`     | First ready     | Only if all error  |
-| `settled(...atoms)` | Array of status | No                 |
+| Method              | Returns         | Throws on Error?  |
+| ------------------- | --------------- | ----------------- |
+| `get(atom)`         | Single value    | Yes               |
+| `all(...atoms)`     | Array of values | Yes (first error) |
+| `race(...atoms)`    | First settled   | Yes (if first)    |
+| `any(...atoms)`     | First ready     | Only if all error |
+| `settled(...atoms)` | Array of status | No                |
 
 > **Note:** `race()` and `any()` are typically used with `MutableAtom<Promise<T>>` for racing data sources.
 
@@ -543,7 +543,7 @@ interface EffectContext extends SelectContext {
 
 function effect(
   fn: (ctx: EffectContext) => void,
-  options?: EffectOptions,
+  options?: EffectOptions
 ): () => void;
 
 interface EffectOptions {
@@ -585,7 +585,7 @@ const dispose = effect(
   },
   {
     onError: (e) => console.error("Unhandled error:", e),
-  },
+  }
 );
 ```
 
@@ -593,13 +593,13 @@ const dispose = effect(
 
 ## React Hooks
 
-### useValue
+### useSelector
 
 ```typescript
-function useValue<T>(atom: Atom<T>): Awaited<T>;
-function useValue<T>(
+function useSelector<T>(atom: Atom<T>): Awaited<T>;
+function useSelector<T>(
   selector: (ctx: SelectContext) => T,
-  equals?: Equality<Awaited<T>>,
+  equals?: Equality<Awaited<T>>
 ): Awaited<T>;
 ```
 
@@ -608,7 +608,7 @@ function useValue<T>(
 ```typescript
 // With DerivedAtom (Suspense handles loading)
 function PostCount() {
-  const count = useValue(postCount$); // number (awaited)
+  const count = useSelector(postCount$); // number (awaited)
   return <div>Count: {count}</div>;
 }
 
@@ -688,7 +688,7 @@ derived<T>(compute, { fallback }): DerivedAtom<T, true>
 effect(fn, options?): () => void
 
 // React
-useValue(source): T | Awaited<T>
+useSelector(source): T | Awaited<T>
 
 // Types
 Atom<T>
@@ -701,25 +701,25 @@ SelectContext
 
 ## Summary Table
 
-|                  | MutableAtom | DerivedAtom         | DerivedAtom with fallback |
-| ---------------- | ----------- | ------------------- | ------------------------- |
-| Purpose          | Raw storage | Computed (async)    | Computed + sync access    |
-| `.value`         | `T` (raw)   | `Promise<T>`        | `Promise<T>`              |
-| `.staleValue`    | ❌          | ✅ `T \| undefined` | ✅ `T`                    |
-| `.state()`       | ❌          | ✅ `AtomState<T>`   | ✅ `AtomState<T>`         |
-| `.set()`         | ✅          | ❌                  | ❌                        |
-| `.reset()`       | ✅          | ❌                  | ❌                        |
-| `.refresh()`     | ❌          | ✅                  | ✅                        |
-| `.on()`          | ✅          | ✅                  | ✅                        |
+|               | MutableAtom | DerivedAtom         | DerivedAtom with fallback |
+| ------------- | ----------- | ------------------- | ------------------------- |
+| Purpose       | Raw storage | Computed (async)    | Computed + sync access    |
+| `.value`      | `T` (raw)   | `Promise<T>`        | `Promise<T>`              |
+| `.staleValue` | ❌          | ✅ `T \| undefined` | ✅ `T`                    |
+| `.state()`    | ❌          | ✅ `AtomState<T>`   | ✅ `AtomState<T>`         |
+| `.set()`      | ✅          | ❌                  | ❌                        |
+| `.reset()`    | ✅          | ❌                  | ❌                        |
+| `.refresh()`  | ❌          | ✅                  | ✅                        |
+| `.on()`       | ✅          | ✅                  | ✅                        |
 
 ---
 
 ## Migration from v1
 
-| v1                             | v2                                            |
-| ------------------------------ | --------------------------------------------- |
-| `atom(promise, { fallback })`  | `atom(promise)` (no fallback on atom)         |
-| `atom.loading`                 | `isPending(derived$.value)` from promiseCache |
-| `atom.error`                   | `await derived.value` throws                  |
-| `atom.stale()`                 | `isPending(derived$.value)` from promiseCache |
-| `useValue(atom)` with Suspense | `useValue(derived)` with Suspense             |
+| v1                                | v2                                            |
+| --------------------------------- | --------------------------------------------- |
+| `atom(promise, { fallback })`     | `atom(promise)` (no fallback on atom)         |
+| `atom.loading`                    | `isPending(derived$.value)` from promiseCache |
+| `atom.error`                      | `await derived.value` throws                  |
+| `atom.stale()`                    | `isPending(derived$.value)` from promiseCache |
+| `useSelector(atom)` with Suspense | `useSelector(derived)` with Suspense          |