atomirx 0.0.1 → 0.0.4

package/dist/react/rx.d.ts

@@ -1,9 +1,45 @@
+import { ReactElement, ReactNode } from 'react';
 import { Atom, Equality } from '../core/types';
-import { ContextSelectorFn } from '../core/select';
+import { ReactiveSelector } from '../core/select';
+/**
+ * Options for rx() with inline loading/error handling and memoization control.
+ */
+export interface RxOptions<T> {
+    /** Equality function for value comparison */
+    equals?: Equality<T>;
+    /** Render function for loading state */
+    loading?: () => ReactNode;
+    /** Render function for error state */
+    error?: (props: {
+        error: unknown;
+    }) => ReactNode;
+    /**
+     * Dependencies array for selector memoization.
+     *
+     * Controls when the selector callback is recreated:
+     * - **Atom shorthand** (`rx(atom$)`): Always memoized by atom reference (deps ignored)
+     * - **Function selector without deps**: No memoization (recreated every render)
+     * - **Function selector with `deps: []`**: Stable forever (never recreated)
+     * - **Function selector with `deps: [a, b]`**: Recreated when deps change
+     *
+     * @example
+     * ```tsx
+     * // No memoization (default for functions) - selector recreated every render
+     * rx(({ read }) => read(count$) * 2)
+     *
+     * // Stable selector - never recreated
+     * rx(({ read }) => read(count$) * 2, { deps: [] })
+     *
+     * // Recreate when multiplier changes
+     * rx(({ read }) => read(count$) * multiplier, { deps: [multiplier] })
+     * ```
+     */
+    deps?: unknown[];
+}
 /**
  * Reactive inline component that renders atom values directly in JSX.
  *
- * `rx` is a convenience wrapper around `useValue` that returns a memoized
+ * `rx` is a convenience wrapper around `useSelector` that returns a memoized
  * React component instead of a value. This enables fine-grained reactivity
  * without creating separate components for each reactive value.
  *
@@ -13,25 +49,54 @@ import { ContextSelectorFn } from '../core/select';
  *
  * ```tsx
  * // ❌ WRONG - Don't use async function
- * rx(async ({ get }) => {
+ * rx(async ({ read }) => {
  *   const data = await fetch('/api');
  *   return data.name;
  * });
  *
  * // ❌ WRONG - Don't return a Promise
- * rx(({ get }) => fetch('/api').then(r => r.json()));
+ * rx(({ 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()));
- * rx(({ get }) => get(data$).name); // Suspends until resolved
+ * rx(({ read }) => read(data$).name); // 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
+ * rx(({ read }) => {
+ *   try {
+ *     return <span>{read(user$).name}</span>;
+ *   } catch (e) {
+ *     return <span>Error</span>; // Catches BOTH errors AND loading promises!
+ *   }
+ * });
+ *
+ * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
+ * rx(({ read, safe }) => {
+ *   const [err, user] = safe(() => read(user$));
+ *   if (err) return <span>Error: {err.message}</span>;
+ *   return <span>{user.name}</span>;
+ * });
+ * ```
+ *
+ * The `safe()` utility:
+ * - **Catches errors** and returns `[error, undefined]`
+ * - **Re-throws Promises** to preserve Suspense behavior
+ * - Returns `[undefined, result]` on success
+ *
  * ## Why Use `rx`?
  *
  * Without `rx`, you need a separate component to subscribe to an atom:
  * ```tsx
  * function PostsList() {
- *   const posts = useValue(postsAtom);
+ *   const posts = useSelector(postsAtom);
  *   return posts.map((post) => <Post post={post} />);
  * }
  *
@@ -49,8 +114,8 @@ import { ContextSelectorFn } from '../core/select';
  * function Page() {
  *   return (
  *     <Suspense fallback={<Loading />}>
- *       {rx(({ get }) =>
- *         get(postsAtom).map((post) => <Post post={post} />)
+ *       {rx(({ read }) =>
+ *         read(postsAtom).map((post) => <Post post={post} />)
  *       )}
  *     </Suspense>
  *   );
@@ -68,7 +133,7 @@ import { ContextSelectorFn } from '../core/select';
  *
  * ## Async Atoms (Suspense-Style API)
  *
- * `rx` inherits the Suspense-style API from `useValue`:
+ * `rx` inherits the Suspense-style API from `useSelector`:
  * - **Loading state**: The getter throws a Promise (triggers Suspense)
  * - **Error state**: The getter throws the error (triggers ErrorBoundary)
  * - **Resolved state**: The getter returns the value
@@ -79,7 +144,7 @@ import { ContextSelectorFn } from '../core/select';
  *   return (
  *     <ErrorBoundary fallback={<div>Error!</div>}>
  *       <Suspense fallback={<div>Loading...</div>}>
- *         {rx(({ get }) => get(userAtom).name)}
+ *         {rx(({ read }) => read(userAtom).name)}
  *       </Suspense>
  *     </ErrorBoundary>
  *   );
@@ -88,9 +153,9 @@ import { ContextSelectorFn } from '../core/select';
  *
  * Or catch errors in the selector to handle loading/error inline:
  * ```tsx
- * {rx(({ get }) => {
+ * {rx(({ read }) => {
  *   try {
- *     return get(userAtom).name;
+ *     return read(userAtom).name;
  *   } catch {
  *     return "Loading...";
  *   }
@@ -98,13 +163,37 @@ import { ContextSelectorFn } from '../core/select';
  * ```
  *
  * @template T - The type of the selected/derived value
- * @param selector - Context-based selector function with `{ get, all, any, race, settled }`.
+ * @param selector - Context-based selector function with `{ read, all, any, race, settled }`.
  *                   Must return sync value, not a Promise.
  * @param equals - Equality function or shorthand ("strict", "shallow", "deep").
  *                 Defaults to "shallow".
  * @returns A React element that renders the selected value
  * @throws Error if selector returns a Promise or PromiseLike
  *
+ * ## IMPORTANT: Atom Value Must Be ReactNode
+ *
+ * When using the shorthand `rx(atom)`, the atom's value must be a valid `ReactNode`
+ * (string, number, boolean, null, undefined, or React element). Objects and arrays
+ * are NOT valid ReactNode values and will cause React to throw an error.
+ *
+ * ```tsx
+ * // ✅ CORRECT - Atom contains ReactNode (number)
+ * const count$ = atom(5);
+ * rx(count$);
+ *
+ * // ✅ CORRECT - Atom contains ReactNode (string)
+ * const name$ = atom("John");
+ * rx(name$);
+ *
+ * // ❌ WRONG - Atom contains object (not ReactNode)
+ * const user$ = atom({ name: "John", age: 30 });
+ * rx(user$); // React error: "Objects are not valid as a React child"
+ *
+ * // ✅ CORRECT - Use selector to extract ReactNode from object
+ * rx(({ read }) => read(user$).name);
+ * rx(({ read }) => <UserCard user={read(user$)} />);
+ * ```
+ *
  * @example Shorthand - render atom value directly
  * ```tsx
  * const count = atom(5);
@@ -119,7 +208,7 @@ import { ContextSelectorFn } from '../core/select';
  * const count = atom(5);
  *
  * function DoubledCounter() {
- *   return <div>Doubled: {rx(({ get }) => get(count) * 2)}</div>;
+ *   return <div>Doubled: {rx(({ read }) => read(count) * 2)}</div>;
  * }
  * ```
  *
@@ -131,7 +220,7 @@ import { ContextSelectorFn } from '../core/select';
  * function FullName() {
  *   return (
  *     <div>
- *       {rx(({ get }) => `${get(firstName)} ${get(lastName)}`)}
+ *       {rx(({ read }) => `${read(firstName)} ${read(lastName)}`)}
  *     </div>
  *   );
  * }
@@ -158,14 +247,14 @@ import { ContextSelectorFn } from '../core/select';
  *   return (
  *     <div>
  *       <header>
- *         <Suspense fallback="...">{rx(({ get }) => get(userAtom).name)}</Suspense>
+ *         <Suspense fallback="...">{rx(({ read }) => read(userAtom).name)}</Suspense>
  *       </header>
  *       <main>
  *         <Suspense fallback="...">
- *           {rx(({ get }) => get(postsAtom).length)} posts
+ *           {rx(({ read }) => read(postsAtom).length)} posts
  *         </Suspense>
  *         <Suspense fallback="...">
- *           {rx(({ get }) => get(notificationsAtom).length)} notifications
+ *           {rx(({ read }) => read(notificationsAtom).length)} notifications
  *         </Suspense>
  *       </main>
  *     </div>
@@ -182,8 +271,8 @@ import { ContextSelectorFn } from '../core/select';
  * function Info() {
  *   return (
  *     <div>
- *       {rx(({ get }) =>
- *         get(showDetails) ? get(details) : get(summary)
+ *       {rx(({ read }) =>
+ *         read(showDetails) ? read(details) : read(summary)
  *       )}
  *     </div>
  *   );
@@ -198,7 +287,7 @@ import { ContextSelectorFn } from '../core/select';
  *   return (
  *     <div>
  *       {rx(
- *         ({ get }) => get(user).name,
+ *         ({ read }) => read(user).name,
  *         (a, b) => a === b // Only re-render if name string changes
  *       )}
  *     </div>
@@ -216,7 +305,7 @@ import { ContextSelectorFn } from '../core/select';
  *     <Suspense fallback={<Loading />}>
  *       {rx(({ all }) => {
  *         // Use all() to wait for multiple atoms
- *         const [user, posts] = all([userAtom, postsAtom]);
+ *         const [user, posts] = all([user$, posts$]);
  *         return <DashboardContent user={user} posts={posts} />;
  *       })}
  *     </Suspense>
@@ -246,5 +335,5 @@ import { ContextSelectorFn } from '../core/select';
  * }
  * ```
  */
-export declare function rx<T>(atom: Atom<T>, equals?: Equality<Awaited<T>>): Awaited<T>;
-export declare function rx<T>(selector: ContextSelectorFn<T>, equals?: Equality<T>): T;
+export declare function rx<T extends ReactNode | PromiseLike<ReactNode>>(atom: Atom<T>, options?: Equality<T> | RxOptions<T>): ReactElement;
+export declare function rx<T extends ReactNode | PromiseLike<ReactNode>>(selector: ReactiveSelector<T>, options?: Equality<T> | RxOptions<T>): ReactElement;

package/dist/react/useAction.d.ts

@@ -1,3 +1,4 @@
+import { Pipeable } from '../core/types';
 /**
  * State for an action that hasn't been dispatched yet.
  */
@@ -59,7 +60,7 @@ export interface UseActionOptions {
     /**
      * Dependencies array. When lazy is false, re-executes when deps change.
      * - Regular values: compared by reference (like useEffect deps)
-     * - Atoms: automatically tracked via useValue, re-executes when atom values change
+     * - Atoms: automatically tracked via useSelector, re-executes when atom values change
      * @default []
      */
     deps?: unknown[];
@@ -67,7 +68,7 @@ export interface UseActionOptions {
 /**
  * Context passed to the action function.
  */
-export interface ActionContext {
+export interface ActionContext extends Pipeable {
     /** AbortSignal for cancellation. New signal per dispatch. */
     signal: AbortSignal;
 }
@@ -229,11 +230,11 @@ export type Action<TResult, TLazy extends boolean = true> = ActionDispatch<TResu
  *
  * function UserProfile() {
  *   const fetchUser = useAction(
- *     async ({ signal }) => fetchUserApi(userIdAtom.value, { signal }),
+ *     async ({ signal }) => fetchUserApi(userIdAtom.get(), { signal }),
  *     { lazy: false, deps: [userIdAtom] }
  *   );
  *   // Automatically re-fetches when userIdAtom changes
- *   // Atoms in deps are tracked reactively via useValue
+ *   // Atoms in deps are tracked reactively via useSelector
  * }
  * ```
  *

package/dist/react/{useValue.d.ts → useSelector.d.ts}

@@ -1,4 +1,4 @@
-import { ContextSelectorFn } from '../core/select';
+import { ReactiveSelector } from '../core/select';
 import { Atom, Equality } from '../core/types';
 /**
  * React hook that selects/derives a value from atom(s) with automatic subscriptions.
@@ -12,19 +12,52 @@ import { Atom, Equality } from '../core/types';
  *
  * ```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:
@@ -36,22 +69,19 @@ import { Atom, Equality } from '../core/types';
  * - **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>;
  * }
  * ```
  *
@@ -59,14 +89,15 @@ import { Atom, Equality } from '../core/types';
  * @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>;
  * }
  * ```
@@ -76,7 +107,7 @@ import { Atom, Equality } from '../core/types';
  * const count = atom(5);
  *
  * function Counter() {
- *   const doubled = useValue(({ get }) => get(count) * 2);
+ *   const doubled = useSelector(({ read }) => read(count) * 2);
  *   return <div>{doubled}</div>;
  * }
  * ```
@@ -87,8 +118,8 @@ import { Atom, Equality } from '../core/types';
  * 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>;
  * }
@@ -99,7 +130,7 @@ import { Atom, Equality } from '../core/types';
  * const userAtom = atom(fetchUser());
  *
  * function UserProfile() {
- *   const user = useValue(({ get }) => get(userAtom));
+ *   const user = useSelector(({ read }) => read(userAtom));
  *   return <div>{user.name}</div>;
  * }
  *
@@ -121,7 +152,7 @@ import { Atom, Equality } from '../core/types';
  * const postsAtom = atom(fetchPosts());
  *
  * function Dashboard() {
- *   const data = useValue(({ all }) => {
+ *   const data = useSelector(({ all }) => {
  *     const [user, posts] = all(userAtom, postsAtom);
  *     return { user, posts };
  *   });
@@ -130,5 +161,5 @@ import { Atom, Equality } from '../core/types';
  * }
  * ```
  */
-export declare function useValue<T>(atom: Atom<T>, equals?: Equality<Awaited<T>>): Awaited<T>;
-export declare function useValue<T>(selector: ContextSelectorFn<T>, equals?: Equality<T>): T;
+export declare function useSelector<T>(atom: Atom<T>, equals?: Equality<Awaited<T>>): Awaited<T>;
+export declare function useSelector<T>(selector: ReactiveSelector<T>, equals?: Equality<T>): T;

package/dist/react/useSelector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "atomirx",
-  "version": "0.0.1",
+  "description": "Opinionated, Batteries-Included Reactive State Management",
+  "keywords": [
+    "reactive",
+    "state",
+    "management",
+    "atom",
+    "derived",
+    "effect"
+  ],
+  "author": "Gignuyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/linq2js/atomirx"
+  },
+  "homepage": "https://github.com/linq2js/atomirx",
+  "version": "0.0.4",
   "type": "module",
   "main": "./dist/atomirx.umd.cjs",
   "module": "./dist/atomirx.js",