atomirx 0.0.2 → 0.0.4

package/README.md

@@ -24,8 +24,6 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
   - [Purpose](#purpose)
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
-    - [Using Create React App](#using-create-react-app)
-    - [Adding to an Existing Project](#adding-to-an-existing-project)
   - [Why atomirx?](#why-atomirx)
     - [The Problem](#the-problem)
     - [The Solution](#the-solution)
@@ -36,11 +34,23 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
   - [Getting Started](#getting-started)
     - [Basic Example: Counter](#basic-example-counter)
     - [React Example: Todo App](#react-example-todo-app)
-  - [Code Conventions](#code-conventions)
+  - [Patterns \& Best Practices](#patterns--best-practices)
     - [Naming: The `$` Suffix](#naming-the--suffix)
     - [When to Use Each Primitive](#when-to-use-each-primitive)
     - [Atom Storage: Stable Scopes Only](#atom-storage-stable-scopes-only)
+    - [Error Handling: Use `safe()` Not try/catch](#error-handling-use-safe-not-trycatch)
+      - [The Problem with try/catch](#the-problem-with-trycatch)
+      - [The Solution: safe()](#the-solution-safe)
+      - [Use Cases for safe()](#use-cases-for-safe)
+    - [SelectContext Methods: Synchronous Only](#selectcontext-methods-synchronous-only)
     - [Complete Example: Todo App with Async](#complete-example-todo-app-with-async)
+    - [Deferred Entity Loading with `ready()`](#deferred-entity-loading-with-ready)
+      - [The Pattern](#the-pattern)
+      - [How It Works](#how-it-works)
+      - [Component Usage](#component-usage)
+      - [Benefits](#benefits)
+      - [When to Use `ready()`](#when-to-use-ready)
+      - [Important Notes](#important-notes)
   - [Usage Guide](#usage-guide)
     - [Atoms: The Foundation](#atoms-the-foundation)
       - [Creating Atoms](#creating-atoms)
@@ -56,7 +66,6 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
     - [Effects: Side Effect Management](#effects-side-effect-management)
       - [Basic Effects](#basic-effects)
       - [Effects with Cleanup](#effects-with-cleanup)
-      - [Effects with Error Handling](#effects-with-error-handling)
       - [Effects with Multiple Dependencies](#effects-with-multiple-dependencies)
     - [Async Patterns](#async-patterns)
       - [`all()` - Wait for All (like Promise.all)](#all---wait-for-all-like-promiseall)
@@ -74,9 +83,12 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
       - [Multiple Middleware Example](#multiple-middleware-example)
       - [Hook Info Types](#hook-info-types)
   - [React Integration](#react-integration)
-    - [useValue Hook](#usevalue-hook)
+    - [useSelector Hook](#useselector-hook)
       - [Custom Equality](#custom-equality)
+      - [Why useSelector is Powerful](#why-useselector-is-powerful)
     - [Reactive Components with rx](#reactive-components-with-rx)
+      - [Inline Loading and Error Handling](#inline-loading-and-error-handling)
+      - [Selector Memoization with `deps`](#selector-memoization-with-deps)
     - [Async Actions with useAction](#async-actions-with-useaction)
       - [Eager Execution](#eager-execution)
       - [useAction API](#useaction-api)
@@ -93,8 +105,9 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
       - [`define<T>(factory, options?)`](#definetfactory-options)
       - [`isAtom(value)`](#isatomvalue)
     - [SelectContext API](#selectcontext-api)
+      - [`state()` - Get Async State Without Throwing](#state---get-async-state-without-throwing)
     - [React API](#react-api)
-      - [`useValue`](#usevalue)
+      - [`useSelector`](#useselector)
       - [`rx`](#rx)
       - [`useAction`](#useaction)
       - [`useStable`](#usestable)
@@ -109,16 +122,6 @@ We can't solve every use case, but in the spirit of [`create-react-app`](https:/
 
 ## Installation
 
-### Using Create React App
-
-The fastest way to get started is using our official template:
-
-```bash
-npx create-react-app my-app --template atomirx
-```
-
-### Adding to an Existing Project
-
 atomirx is available as a package on NPM for use with a module bundler or in a Node application:
 
 ```bash
@@ -184,8 +187,8 @@ atomirx includes these APIs:
 
 ### React Bindings (`atomirx/react`)
 
-- **`useValue()`**: Subscribe to atoms with automatic re-rendering
-- **`rx()`**: Inline reactive components for fine-grained updates
+- **`useSelector()`**: Subscribe to atoms with automatic re-rendering (Suspense-based)
+- **`rx()`**: Inline reactive components with optional loading/error handlers
 - **`useAction()`**: Handle async operations with loading/error states
 - **`useStable()`**: Stabilize object/array/callback references
 
@@ -200,16 +203,16 @@ import { atom, derived, effect } from "atomirx";
 const count$ = atom(0);
 
 // Step 2: Create derived state (computed values)
-const doubled$ = derived(({ get }) => get(count$) * 2);
-const message$ = derived(({ get }) => {
-  const count = get(count$);
+const doubled$ = derived(({ read }) => read(count$) * 2);
+const message$ = derived(({ read }) => {
+  const count = read(count$);
   return count === 0 ? "Click to start!" : `Count: ${count}`;
 });
 
 // Step 3: React to changes with effects
-effect(({ get }) => {
-  console.log("Current count:", get(count$));
-  console.log("Doubled value:", get(doubled$));
+effect(({ read }) => {
+  console.log("Current count:", read(count$));
+  console.log("Doubled value:", read(doubled$));
 });
 
 // Step 4: Update state
@@ -221,7 +224,7 @@ count$.set((n) => n + 1); // Logs: Current count: 6, Doubled value: 12
 
 ```tsx
 import { atom, derived } from "atomirx";
-import { useValue, rx } from "atomirx/react";
+import { useSelector, rx } from "atomirx/react";
 
 // Define your state
 interface Todo {
@@ -234,9 +237,9 @@ const todos$ = atom<Todo[]>([]);
 const filter$ = atom<"all" | "active" | "completed">("all");
 
 // Derive computed state
-const filteredTodos$ = derived(({ get }) => {
-  const todos = get(todos$);
-  const filter = get(filter$);
+const filteredTodos$ = derived(({ read }) => {
+  const todos = read(todos$);
+  const filter = read(filter$);
 
   switch (filter) {
     case "active":
@@ -248,8 +251,8 @@ const filteredTodos$ = derived(({ get }) => {
   }
 });
 
-const stats$ = derived(({ get }) => {
-  const todos = get(todos$);
+const stats$ = derived(({ read }) => {
+  const todos = read(todos$);
   return {
     total: todos.length,
     completed: todos.filter((t) => t.completed).length,
@@ -270,7 +273,7 @@ const toggleTodo = (id: number) => {
 
 // Components
 function TodoList() {
-  const todos = useValue(filteredTodos$);
+  const todos = useSelector(filteredTodos$);
 
   return (
     <ul>
@@ -287,8 +290,8 @@ function Stats() {
   // Fine-grained updates: only re-renders when stats change
   return (
     <footer>
-      {rx(({ get }) => {
-        const { total, completed, remaining } = get(stats$);
+      {rx(({ read }) => {
+        const { total, completed, remaining } = read(stats$);
         return (
           <span>
             {remaining} of {total} remaining
@@ -300,9 +303,9 @@ function Stats() {
 }
 ```
 
-## Code Conventions
+## Patterns & Best Practices
 
-Following consistent conventions makes atomirx code more readable and maintainable across your team.
+Following consistent patterns and best practices makes atomirx code more readable and maintainable across your team.
 
 ### Naming: The `$` Suffix
 
@@ -316,7 +319,7 @@ All atoms (both `atom()` and `derived()`) should use the `$` suffix. This conven
 // ✅ Good - clear that these are atoms
 const count$ = atom(0);
 const user$ = atom<User | null>(null);
-const filteredItems$ = derived(({ get }) => /* ... */);
+const filteredItems$ = derived(({ read }) => /* ... */);
 
 // ❌ Avoid - unclear what's reactive
 const count = atom(0);
@@ -353,7 +356,7 @@ const todos$ = atom(() => fetchTodos());
 const filter$ = atom("all");
 
 function TodoList() {
-  const todos = useValue(filteredTodos$);
+  const todos = useSelector(filteredTodos$);
   // ...
 }
 ```
@@ -367,9 +370,9 @@ const TodoModule = define(() => {
   const todos$ = atom(() => fetchTodos(), { meta: { key: "todos" } });
   const filter$ = atom<"all" | "active" | "completed">("all");
 
-  const filteredTodos$ = derived(({ get }) => {
-    const filter = get(filter$);
-    const todos = get(todos$);
+  const filteredTodos$ = derived(({ read }) => {
+    const filter = read(filter$);
+    const todos = read(todos$);
     return filter === "all" ? todos : todos.filter(/* ... */);
   });
 
@@ -386,7 +389,7 @@ const TodoModule = define(() => {
 // Usage in React
 function TodoList() {
   const { filteredTodos$, setFilter } = TodoModule();
-  const todos = useValue(filteredTodos$);
+  const todos = useSelector(filteredTodos$);
   // ...
 }
 ```
@@ -414,9 +417,9 @@ const userData$ = atom(fetchUser(userId)); // Fetch immediately
 
 ```typescript
 // derived() automatically unwraps Promises from atoms
-const filteredTodoList$ = derived(({ get }) => {
-  const filter = get(filter$);
-  const todoList = get(todoList$); // Promise is unwrapped automatically!
+const filteredTodoList$ = derived(({ read }) => {
+  const filter = read(filter$);
+  const todoList = read(todoList$); // Promise is unwrapped automatically!
 
   switch (filter) {
     case "active":
@@ -433,8 +436,8 @@ const filteredTodoList$ = derived(({ get }) => {
 
 ```typescript
 // Sync local state to server when it changes
-effect(({ get, onCleanup }) => {
-  const settings = get(settings$);
+effect(({ read, onCleanup }) => {
+  const settings = read(settings$);
 
   const controller = new AbortController();
   saveSettingsToServer(settings, { signal: controller.signal });
@@ -443,8 +446,8 @@ effect(({ get, onCleanup }) => {
 });
 
 // Update multiple atoms based on another atom's change
-effect(({ get }) => {
-  const user = get(currentUser$);
+effect(({ read }) => {
+  const user = read(currentUser$);
 
   if (user) {
     // Trigger fetches for user-specific data
@@ -454,11 +457,204 @@ effect(({ get }) => {
 });
 ```
 
+### Error Handling: Use `safe()` Not try/catch
+
+When working with reactive selectors in `derived()`, `effect()`, `useSelector()`, and `rx()`, you need to be careful about how you handle errors. The standard JavaScript `try/catch` pattern can break atomirx's Suspense mechanism.
+
+#### The Problem with try/catch
+
+The `read()` function in selectors uses a **Suspense-like pattern**: when an atom is loading (contains a pending Promise), `read()` throws that Promise. This is how atomirx signals to React's Suspense that it should show a fallback.
+
+**If you wrap `read()` in a try/catch, you'll catch the Promise** along with any actual errors:
+
+```typescript
+// ❌ WRONG - This breaks Suspense!
+const data$ = derived(({ read }) => {
+  try {
+    const user = read(asyncUser$); // Throws Promise when loading!
+    return processUser(user);
+  } catch (e) {
+    // This catches BOTH:
+    // 1. The Promise (when loading) - breaks Suspense!
+    // 2. Actual errors from processUser()
+    return null;
+  }
+});
+```
+
+This causes several problems:
+
+1. **Loading state is lost** - Instead of suspending, your derived atom immediately returns `null`
+2. **No Suspense fallback** - React never sees the loading state
+3. **Silent failures** - You can't distinguish between "loading" and "error"
+
+#### The Solution: safe()
+
+atomirx provides the `safe()` utility in all selector contexts. It catches actual errors but **re-throws Promises** to preserve Suspense:
+
+```typescript
+// ✅ CORRECT - Use safe() for error handling
+const data$ = derived(({ read, safe }) => {
+  const [err, user] = safe(() => {
+    const raw = read(asyncUser$); // Can throw Promise (Suspense) ✓
+    return processUser(raw); // Can throw Error ✓
+  });
+
+  if (err) {
+    // Only actual errors reach here, not loading state
+    console.error("Processing failed:", err);
+    return { error: err.message };
+  }
+
+  return { user };
+});
+```
+
+**How `safe()` works:**
+
+| Scenario          | `try/catch`        | `safe()`                        |
+| ----------------- | ------------------ | ------------------------------- |
+| Loading (Promise) | ❌ Catches Promise | ✅ Re-throws → Suspense         |
+| Error             | ✅ Catches error   | ✅ Returns `[error, undefined]` |
+| Success           | ✅ Returns value   | ✅ Returns `[undefined, value]` |
+
+#### Use Cases for safe()
+
+**1. Parsing/Validation that might fail:**
+
+```typescript
+const parsedConfig$ = derived(({ read, safe }) => {
+  const [err, config] = safe(() => {
+    const raw = read(rawConfig$);
+    return JSON.parse(raw); // Can throw SyntaxError
+  });
+
+  if (err) {
+    return { valid: false, error: "Invalid JSON" };
+  }
+  return { valid: true, config };
+});
+```
+
+**2. Graceful degradation with multiple sources:**
+
+```typescript
+const dashboard$ = derived(({ read, safe }) => {
+  // Primary data - required
+  const user = read(user$);
+
+  // Optional data - graceful degradation
+  const [err1, analytics] = safe(() => read(analytics$));
+  const [err2, notifications] = safe(() => read(notifications$));
+
+  return {
+    user,
+    analytics: err1 ? null : analytics,
+    notifications: err2 ? [] : notifications,
+    errors: [err1, err2].filter(Boolean),
+  };
+});
+```
+
+**3. Error handling in effects:**
+
+```typescript
+effect(({ read, safe }) => {
+  const [err, data] = safe(() => {
+    const raw = read(asyncData$);
+    return transformData(raw);
+  });
+
+  if (err) {
+    console.error("Effect failed:", err);
+    return; // Skip the rest of the effect
+  }
+
+  saveToLocalStorage(data);
+});
+```
+
+**4. Error handling in React components:**
+
+```tsx
+function UserProfile() {
+  const result = useSelector(({ read, safe }) => {
+    const [err, user] = safe(() => read(user$));
+    return { err, user };
+  });
+
+  if (result.err) {
+    return <ErrorMessage error={result.err} />;
+  }
+
+  return <Profile user={result.user} />;
+}
+```
+
+**5. With rx() for inline error handling:**
+
+```tsx
+<Suspense fallback={<Loading />}>
+  {rx(({ read, safe }) => {
+    const [err, posts] = safe(() => read(posts$));
+    if (err) return <ErrorBanner message="Failed to load posts" />;
+    return posts.map((post) => <PostCard key={post.id} post={post} />);
+  })}
+</Suspense>
+```
+
+### SelectContext Methods: 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.
+
+```typescript
+// ❌ WRONG - Calling read() in async callback
+derived(({ 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 (not tracked as dependency)
+    const data = myMutableAtom$.get();
+    const asyncData = await myDerivedAtom$.get();
+    console.log(data, asyncData);
+  }, 100);
+});
+```
+
+**Why this restriction?**
+
+1. **Dependency tracking**: Context methods track which atoms are accessed to know when to recompute. This tracking only works during synchronous execution.
+
+2. **Predictable behavior**: If `read()` could be called at any time, the reactive graph would be unpredictable and hard to debug.
+
+3. **Clear error messages**: Rather than silently failing to track dependencies, atomirx throws a helpful error explaining the issue.
+
+**For async access**, use `atom.get()` directly:
+
+- `mutableAtom$.get()` - Returns the raw value (may be a Promise)
+- `await derivedAtom$.get()` - Returns a Promise that resolves to the computed value
+
 ### Complete Example: Todo App with Async
 
 ```typescript
 import { atom, derived } from "atomirx";
-import { useValue, rx } from "atomirx/react";
+import { useSelector, rx } from "atomirx/react";
 import { Suspense } from "react";
 
 // Atoms store values (including Promises)
@@ -466,9 +662,9 @@ const filter$ = atom<"all" | "active" | "completed">("all");
 const todoList$ = atom(() => fetchAllTodos()); // Lazy init, re-runs on reset()
 
 // Derived handles reactive transformations (auto-unwraps Promises)
-const filteredTodoList$ = derived(({ get }) => {
-  const filter = get(filter$);
-  const todoList = get(todoList$); // This is the resolved value, not a Promise!
+const filteredTodoList$ = derived(({ read }) => {
+  const filter = read(filter$);
+  const todoList = read(todoList$); // This is the resolved value, not a Promise!
 
   switch (filter) {
     case "active": return todoList.filter(t => !t.completed);
@@ -477,9 +673,9 @@ const filteredTodoList$ = derived(({ get }) => {
   }
 });
 
-// In UI - useValue suspends until data is ready
+// In UI - useSelector suspends until data is ready
 function TodoList() {
-  const filteredTodoList = useValue(filteredTodoList$);
+  const filteredTodoList = useSelector(filteredTodoList$);
 
   return (
     <ul>
@@ -494,8 +690,8 @@ function TodoList() {
 function App() {
   return (
     <Suspense fallback={<div>Loading todos...</div>}>
-      {rx(({ get }) =>
-        get(filteredTodoList$).map(todo => <Todo key={todo.id} todo={todo} />)
+      {rx(({ read }) =>
+        read(filteredTodoList$).map(todo => <Todo key={todo.id} todo={todo} />)
       )}
     </Suspense>
   );
@@ -511,6 +707,229 @@ function RefreshButton() {
 }
 ```
 
+### Deferred Entity Loading with `ready()`
+
+When building detail pages (e.g., `/article/:id`), you often need to:
+
+1. Wait for a route parameter to be set
+2. Fetch data based on that parameter
+3. Share the loaded entity across multiple components
+
+The `ready()` method in derived atoms provides an elegant solution for this pattern.
+
+#### The Pattern
+
+```typescript
+import { atom, derived, effect, readonly, define } from "atomirx";
+
+const articleModule = define(() => {
+  // Current article ID - set from route
+  const currentArticleId$ = atom<string | undefined>(undefined);
+
+  // Article cache - normalized storage
+  const articleCache$ = atom<Record<string, Article>>({});
+
+  // Current article - uses ready() to wait for both ID and cached data
+  const currentArticle$ = derived(({ ready }) => {
+    const id = ready(currentArticleId$); // Suspends if undefined
+    const article = ready(articleCache$, (cache) => cache[id]); // Suspends if not cached
+    return article;
+  });
+
+  // Fetch article when ID changes
+  effect(({ read }) => {
+    const id = read(currentArticleId$);
+    if (!id) return;
+
+    // Skip if already cached
+    const cache = read(articleCache$);
+    if (cache[id]) return;
+
+    // Fetch and cache
+    // ─────────────────────────────────────────────────────────────
+    // Optional: Track loading/error states in cache for more control
+    // type CacheEntry<T> =
+    //   | { status: "loading" }
+    //   | { status: "error"; error: Error }
+    //   | { status: "success"; data: T };
+    // const articleCache$ = atom<Record<string, CacheEntry<Article>>>({});
+    //
+    // articleCache$.set((prev) => ({ ...prev, [id]: { status: "loading" } }));
+    // fetch(...)
+    //   .then((article) => articleCache$.set((prev) => ({
+    //     ...prev, [id]: { status: "success", data: article }
+    //   })))
+    //   .catch((error) => articleCache$.set((prev) => ({
+    //     ...prev, [id]: { status: "error", error }
+    //   })));
+    // ─────────────────────────────────────────────────────────────
+    fetch(`/api/articles/${id}`)
+      .then((r) => r.json())
+      .then((article) => {
+        articleCache$.set((prev) => ({ ...prev, [id]: article }));
+      });
+  });
+
+  return {
+    ...readonly({ currentArticleId$, currentArticle$ }),
+
+    // ─────────────────────────────────────────────────────────────
+    // navigateTo(id) - Navigate to a new article
+    // ─────────────────────────────────────────────────────────────
+    // Flow:
+    // 1. Set currentArticleId$ to new ID
+    // 2. currentArticle$ recomputes:
+    //    - If cached: ready() succeeds → UI shows article immediately
+    //    - If not cached: ready() suspends → UI shows <Skeleton />
+    // 3. effect() runs in parallel:
+    //    - If cached: early return (no fetch)
+    //    - If not cached: fetch → update articleCache$
+    // 4. When cache updated, currentArticle$ recomputes → UI shows article
+    navigateTo: (id: string) => currentArticleId$.set(id),
+
+    // ─────────────────────────────────────────────────────────────
+    // invalidate(id) - Mark an article as stale (soft invalidation)
+    // ─────────────────────────────────────────────────────────────
+    // Flow:
+    // 1. Guard: Skip if id === currentArticleId (don't disrupt current view)
+    // 2. Remove article from cache
+    // 3. No immediate effect on UI (current article unchanged)
+    // 4. Next navigateTo(id) will trigger fresh fetch
+    // Use case: Background sync detected article was updated elsewhere
+    invalidate: (id: string) => {
+      if (id === currentArticleId$.get()) return;
+      articleCache$.set((prev) => {
+        const { [id]: _, ...rest } = prev;
+        return rest;
+      });
+    },
+
+    // ─────────────────────────────────────────────────────────────
+    // refresh() - Force refetch current article (hard refresh)
+    // ─────────────────────────────────────────────────────────────
+    // Flow:
+    // 1. Remove current article from cache
+    // 2. currentArticle$ recomputes:
+    //    - ready() suspends (cache miss) → UI shows <Skeleton />
+    // 3. effect() runs:
+    //    - Cache miss detected → fetch starts
+    // 4. Fetch completes → cache updated → UI shows fresh data
+    // Use case: Pull-to-refresh, retry after error
+    refresh() {
+      articleCache$.set((prev) => {
+        const { [currentArticleId$.get()]: _, ...rest } = prev;
+        return rest;
+      });
+    },
+  };
+});
+```
+
+#### How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Route: /article/:id                                        │
+│  → navigateTo(id)                                           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  effect() detects ID change                                 │
+│  → Checks cache, fetches if not cached                      │
+│  → Updates articleCache$                                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  currentArticle$ (derived with ready())                     │
+│  → Suspends until ID is set AND article is in cache         │
+│  → Returns article when both conditions met                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Components with Suspense                                   │
+│  → Show loading fallback while suspended                    │
+│  → Render article when ready                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Component Usage
+
+```tsx
+// Page component - syncs route and provides boundaries
+export const ArticlePage = () => {
+  const { id } = useParams();
+  const { navigateTo } = articleModule();
+
+  useEffect(() => {
+    navigateTo(id);
+  }, [id]);
+
+  return (
+    <ErrorBoundary fallback={<ErrorDialog />}>
+      <Suspense fallback={<ArticleSkeleton />}>
+        <ArticleHeader />
+        <ArticleContent />
+        <ArticleMeta />
+      </Suspense>
+    </ErrorBoundary>
+  );
+};
+
+// Child components - clean, no loading/error handling needed
+export const ArticleHeader = () => {
+  const { currentArticle$ } = articleModule();
+  const article = useSelector(currentArticle$);
+
+  return <h1>{article.title}</h1>;
+};
+
+export const ArticleContent = () => {
+  const { currentArticle$ } = articleModule();
+  const article = useSelector(currentArticle$);
+
+  return <div className="content">{article.body}</div>;
+};
+
+export const ArticleMeta = () => {
+  const { currentArticle$ } = articleModule();
+  const article = useSelector(currentArticle$);
+
+  return (
+    <span>
+      By {article.author} • {article.date}
+    </span>
+  );
+};
+```
+
+#### Benefits
+
+| Benefit                  | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| **Clean components**     | Child components just read the atom - no loading/error handling  |
+| **No prop drilling**     | All components access `currentArticle$` directly from the module |
+| **Automatic suspension** | `ready()` handles the "wait for data" logic declaratively        |
+| **Centralized fetching** | Effect handles when/how to fetch, components just consume        |
+| **Cache management**     | Normalized cache enables invalidation and updates                |
+
+#### When to Use `ready()`
+
+| Use Case             | Example                                          |
+| -------------------- | ------------------------------------------------ |
+| Route-based entities | `/article/:id`, `/user/:userId`, `/product/:sku` |
+| Auth-gated content   | Wait for `currentUser$` before showing dashboard |
+| Dependent data       | Wait for parent entity before fetching children  |
+| Multi-step forms     | Wait for previous step data before showing next  |
+
+#### Important Notes
+
+- **Only use in `derived()` or `effect()`** - `ready()` suspends computation, which only works in reactive contexts
+- **Separate fetching from derivation** - Use `effect()` for side effects (fetching), `derived()` for computing values
+- **Read from cache in effect** - Don't read `currentArticle$` in the effect that populates it; read `articleCache$` directly
+
 ## Usage Guide
 
 ### Atoms: The Foundation
@@ -543,7 +962,7 @@ const posts$ = atom(fetchPosts(), { fallback: [] });
 import { getAtomState, isPending } from "atomirx";
 
 // Direct access (outside reactive context)
-console.log(count$.value); // Current value (T or Promise<T>)
+console.log(count$.get()); // Current value (T or Promise<T>)
 
 // Check atom state
 const state = getAtomState(userData$);
@@ -556,7 +975,7 @@ if (state.status === "loading") {
 }
 
 // Quick loading check
-console.log(isPending(userData$.value)); // true while Promise is pending
+console.log(isPending(userData$.get())); // true while Promise is pending
 ```
 
 #### Updating Atoms
@@ -585,7 +1004,7 @@ const unsubscribe = count$.on((newValue) => {
 
 // Await async atoms
 await userData$;
-console.log("User loaded:", userData$.value);
+console.log("User loaded:", userData$.get());
 
 // Unsubscribe when done
 unsubscribe();
@@ -597,7 +1016,7 @@ unsubscribe();
 
 | Property/Method | Type         | Description                                        |
 | --------------- | ------------ | -------------------------------------------------- |
-| `value`         | `T`          | Current value (may be a Promise for async atoms)   |
+| `get()`         | `T`          | Current value (may be a Promise for async atoms)   |
 | `set(value)`    | `void`       | Update with value, Promise, or updater function    |
 | `reset()`       | `void`       | Reset to initial value                             |
 | `on(listener)`  | `() => void` | Subscribe to changes, returns unsubscribe function |
@@ -606,7 +1025,7 @@ unsubscribe();
 
 | Property/Method | Type             | Description                                    |
 | --------------- | ---------------- | ---------------------------------------------- |
-| `value`         | `Promise<T>`     | Always returns a Promise                       |
+| `get()`         | `Promise<T>`     | Always returns a Promise                       |
 | `staleValue`    | `T \| undefined` | Fallback or last resolved value during loading |
 | `state()`       | `AtomState<T>`   | Current state (ready/error/loading)            |
 | `refresh()`     | `void`           | Re-run the computation                         |
@@ -625,6 +1044,8 @@ type AtomState<T> =
 
 Derived atoms automatically compute values based on other atoms. They track dependencies at runtime and only recompute when those specific dependencies change.
 
+> **Note:** For error handling in derived selectors, use `safe()` instead of try/catch. See [Error Handling: Use `safe()` Not try/catch](#error-handling-use-safe-not-trycatch).
+
 #### Basic Derived State
 
 ```typescript
@@ -634,12 +1055,12 @@ const firstName$ = atom("John");
 const lastName$ = atom("Doe");
 
 // Derived state with automatic dependency tracking
-const fullName$ = derived(({ get }) => {
-  return `${get(firstName$)} ${get(lastName$)}`;
+const fullName$ = derived(({ read }) => {
+  return `${read(firstName$)} ${read(lastName$)}`;
 });
 
-// Derived atoms always return Promise<T> for .value
-await fullName$.value; // "John Doe"
+// Derived atoms always return Promise<T> for .get()
+await fullName$.get(); // "John Doe"
 
 // Or use staleValue for synchronous access (after first resolution)
 fullName$.staleValue; // "John Doe" (or undefined before first resolution)
@@ -648,7 +1069,7 @@ fullName$.staleValue; // "John Doe" (or undefined before first resolution)
 fullName$.state(); // { status: "ready", value: "John Doe" }
 
 firstName$.set("Jane");
-await fullName$.value; // "Jane Doe"
+await fullName$.get(); // "Jane Doe"
 ```
 
 #### Conditional Dependencies
@@ -660,13 +1081,13 @@ const showDetails$ = atom(false);
 const summary$ = atom("Brief overview");
 const details$ = atom("Detailed information...");
 
-const content$ = derived(({ get }) => {
+const content$ = derived(({ read }) => {
   // Only tracks showDetails$ initially
-  if (get(showDetails$)) {
+  if (read(showDetails$)) {
     // details$ becomes a dependency only when showDetails$ is true
-    return get(details$);
+    return read(details$);
   }
-  return get(summary$);
+  return read(summary$);
 });
 
 // When showDetails$ is false:
@@ -676,9 +1097,9 @@ const content$ = derived(({ get }) => {
 
 #### Suspense-Style Getters
 
-The `get()` function follows React Suspense semantics for async atoms:
+The `read()` function follows React Suspense semantics for async atoms:
 
-| Atom State | `get()` Behavior                                |
+| Atom State | `read()` Behavior                               |
 | ---------- | ----------------------------------------------- |
 | Loading    | Throws the Promise (caught by derived/Suspense) |
 | Error      | Throws the error                                |
@@ -687,9 +1108,9 @@ The `get()` function follows React Suspense semantics for async atoms:
 ```typescript
 const user$ = atom(fetchUser());
 
-const userName$ = derived(({ get }) => {
+const userName$ = derived(({ read }) => {
   // Automatically handles loading/error states
-  const user = get(user$);
+  const user = read(user$);
   return user.name;
 });
 
@@ -704,7 +1125,7 @@ if (state.status === "loading") {
 }
 
 // Or use staleValue with a fallback
-const userName = derived(({ get }) => get(user$).name, { fallback: "Guest" });
+const userName = derived(({ read }) => read(user$).name, { fallback: "Guest" });
 userName.staleValue; // "Guest" during loading, then actual name
 ```
 
@@ -714,9 +1135,9 @@ userName.staleValue; // "Guest" during loading, then actual name
 const user$ = atom(fetchUser());
 const posts$ = atom(fetchPosts());
 
-const dashboard$ = derived(({ get }) => {
-  const user = get(user$); // Suspends if loading
-  const posts = get(posts$); // Suspends if loading
+const dashboard$ = derived(({ read }) => {
+  const user = read(user$); // Suspends if loading
+  const posts = read(posts$); // Suspends if loading
 
   return {
     userName: user.name,
@@ -730,7 +1151,7 @@ const state = dashboard$.state();
 
 // Or use all() for explicit parallel loading
 const dashboard2$ = derived(({ all }) => {
-  const [user, posts] = all(user$, posts$);
+  const [user, posts] = all([user$, posts$]);
   return { userName: user.name, postCount: posts.length };
 });
 ```
@@ -739,6 +1160,8 @@ const dashboard2$ = derived(({ all }) => {
 
 Effects run side effects whenever their dependencies change. They use the same reactive context as `derived()`.
 
+> **Note:** For error handling in effects, use `safe()` instead of try/catch. See [Error Handling: Use `safe()` Not try/catch](#error-handling-use-safe-not-trycatch).
+
 #### Basic Effects
 
 ```typescript
@@ -747,8 +1170,8 @@ import { atom, effect } from "atomirx";
 const count$ = atom(0);
 
 // Effect runs immediately and on every change
-const dispose = effect(({ get }) => {
-  console.log("Count is now:", get(count$));
+const dispose = effect(({ read }) => {
+  console.log("Count is now:", read(count$));
 });
 
 count$.set(5); // Logs: "Count is now: 5"
@@ -764,8 +1187,8 @@ Use `onCleanup()` to register cleanup functions that run before the next executi
 ```typescript
 const interval$ = atom(1000);
 
-const dispose = effect(({ get, onCleanup }) => {
-  const ms = get(interval$);
+const dispose = effect(({ read, onCleanup }) => {
+  const ms = read(interval$);
   const id = setInterval(() => console.log("tick"), ms);
 
   // Cleanup runs before next execution or on dispose
@@ -776,36 +1199,15 @@ interval$.set(500); // Clears old interval, starts new one
 dispose(); // Clears interval completely
 ```
 
-#### Effects with Error Handling
-
-Use `onError()` to handle errors within the effect:
-
-```typescript
-const dispose = effect(({ get, onError }) => {
-  onError((e) => console.error("Effect failed:", e));
-
-  const data = get(dataAtom$);
-  riskyOperation(data);
-});
-
-// Or use options.onError for unhandled errors
-const dispose2 = effect(
-  ({ get }) => {
-    riskyOperation(get(dataAtom$));
-  },
-  { onError: (e) => console.error("Unhandled:", e) }
-);
-```
-
 #### Effects with Multiple Dependencies
 
 ```typescript
 const user$ = atom<User | null>(null);
 const settings$ = atom({ notifications: true });
 
-effect(({ get }) => {
-  const user = get(user$);
-  const settings = get(settings$);
+effect(({ read }) => {
+  const user = read(user$);
+  const settings = read(settings$);
 
   if (user && settings.notifications) {
     analytics.identify(user.id);
@@ -826,8 +1228,8 @@ const posts$ = atom(fetchPosts());
 const comments$ = atom(fetchComments());
 
 const dashboard$ = derived(({ all }) => {
-  // Suspends until ALL atoms resolve (variadic args)
-  const [user, posts, comments] = all(user$, posts$, comments$);
+  // Suspends until ALL atoms resolve (array-based)
+  const [user, posts, comments] = all([user$, posts$, comments$]);
 
   return { user, posts, comments };
 });
@@ -840,8 +1242,9 @@ const primaryApi$ = atom(fetchFromPrimary());
 const fallbackApi$ = atom(fetchFromFallback());
 
 const data$ = derived(({ any }) => {
-  // Returns first successfully resolved value (variadic args)
-  return any(primaryApi$, fallbackApi$);
+  // Returns first successfully resolved value (object-based, returns { key, value })
+  const result = any({ primary: primaryApi$, fallback: fallbackApi$ });
+  return result.value;
 });
 ```
 
@@ -852,8 +1255,9 @@ const cache$ = atom(checkCache());
 const api$ = atom(fetchFromApi());
 
 const data$ = derived(({ race }) => {
-  // Returns first settled (ready OR error) (variadic args)
-  return race(cache$, api$);
+  // Returns first settled (ready OR error) (object-based, returns { key, value })
+  const result = race({ cache: cache$, api: api$ });
+  return result.value;
 });
 ```
 
@@ -864,8 +1268,8 @@ const user$ = atom(fetchUser());
 const posts$ = atom(fetchPosts());
 
 const results$ = derived(({ settled }) => {
-  // Returns status for each atom (variadic args)
-  const [userResult, postsResult] = settled(user$, posts$);
+  // Returns status for each atom (array-based)
+  const [userResult, postsResult] = settled([user$, posts$]);
 
   return {
     user: userResult.status === "ready" ? userResult.value : null,
@@ -877,12 +1281,12 @@ const results$ = derived(({ settled }) => {
 
 #### Async Utility Summary
 
-| Utility     | Input          | Output                 | Behavior                           |
-| ----------- | -------------- | ---------------------- | ---------------------------------- |
-| `all()`     | Variadic atoms | Array of values        | Suspends until all ready           |
-| `any()`     | Variadic atoms | First ready value      | First to resolve wins              |
-| `race()`    | Variadic atoms | First settled value    | First to settle (ready/error) wins |
-| `settled()` | Variadic atoms | Array of SettledResult | Suspends until all settled         |
+| Utility     | Input           | Output                   | Behavior                           |
+| ----------- | --------------- | ------------------------ | ---------------------------------- |
+| `all()`     | Array of atoms  | Array of values          | Suspends until all ready           |
+| `any()`     | Record of atoms | `{ key, value }` (first) | First to resolve wins              |
+| `race()`    | Record of atoms | `{ key, value }` (first) | First to settle (ready/error) wins |
+| `settled()` | Array of atoms  | Array of SettledResult   | Suspends until all settled         |
 
 **SettledResult type:**
 
@@ -1039,7 +1443,7 @@ onCreateHook.override((prev) => (info) => {
 
     // Save to localStorage on every change
     info.atom.on(() => {
-      localStorage.setItem(storageKey, JSON.stringify(info.atom.value));
+      localStorage.setItem(storageKey, JSON.stringify(info.atom.get()));
     });
   }
 });
@@ -1088,7 +1492,7 @@ onCreateHook.override((prev) => (info) => {
       // Resolve the next value (handle both direct value and reducer)
       const nextValue =
         typeof valueOrReducer === "function"
-          ? (valueOrReducer as (prev: unknown) => unknown)(info.atom.value)
+          ? (valueOrReducer as (prev: unknown) => unknown)(info.atom.get())
           : valueOrReducer;
 
       // Validate before applying
@@ -1167,12 +1571,14 @@ interface ModuleCreateInfo {
 
 atomirx provides first-class React integration through the `atomirx/react` package.
 
-### useValue Hook
+### useSelector Hook
 
-Subscribe to atom values with automatic re-rendering:
+Subscribe to atom values with automatic re-rendering.
+
+> **Note:** For error handling in selectors, use `safe()` instead of try/catch. See [Error Handling: Use `safe()` Not try/catch](#error-handling-use-safe-not-trycatch).
 
 ```tsx
-import { useValue } from "atomirx/react";
+import { useSelector } from "atomirx/react";
 import { atom } from "atomirx";
 
 const count$ = atom(0);
@@ -1180,15 +1586,15 @@ const user$ = atom<User | null>(null);
 
 function Counter() {
   // Shorthand: pass atom directly
-  const count = useValue(count$);
+  const count = useSelector(count$);
 
   // Context selector: compute derived value
-  const doubled = useValue(({ get }) => get(count$) * 2);
+  const doubled = useSelector(({ read }) => read(count$) * 2);
 
   // Multiple atoms
-  const display = useValue(({ get }) => {
-    const count = get(count$);
-    const user = get(user$);
+  const display = useSelector(({ read }) => {
+    const count = read(count$);
+    const user = read(user$);
     return user ? `${user.name}: ${count}` : `Anonymous: ${count}`;
   });
 
@@ -1200,15 +1606,100 @@ function Counter() {
 
 ```tsx
 // Only re-render when specific fields change
-const userName = useValue(
-  ({ get }) => get(user$)?.name,
+const userName = useSelector(
+  ({ read }) => read(user$)?.name,
   (prev, next) => prev === next
 );
 ```
 
+#### Why useSelector is Powerful
+
+`useSelector` provides a unified API that replaces multiple hooks from other libraries:
+
+**One hook for all use cases:**
+
+```tsx
+// 1. Single atom (shorthand)
+const count = useSelector(count$);
+
+// 2. Derived value (selector)
+const doubled = useSelector(({ read }) => read(count$) * 2);
+
+// 3. Multiple atoms (all) - array-based
+const [user, posts] = useSelector(({ all }) => all([user$, posts$]));
+
+// 4. Loadable mode (state) - no Suspense needed
+const userState = useSelector(({ state }) => state(user$));
+// { status: "loading" | "ready" | "error", value, error }
+
+// 5. Error handling (safe) - preserves Suspense
+const result = useSelector(({ read, safe }) => {
+  const [err, data] = safe(() => JSON.parse(read(rawJson$)));
+  return err ? { error: err.message } : { data };
+});
+
+// 6. First ready (any), race, allSettled
+const fastest = useSelector(({ any }) => any({ cache: cache$, api: api$ }));
+const results = useSelector(({ settled }) => settled([a$, b$, c$]));
+```
+
+**Comparison with other libraries:**
+
+| Use Case            | atomirx                                    | Jotai                          | Recoil                          | Zustand                    |
+| ------------------- | ------------------------------------------ | ------------------------------ | ------------------------------- | -------------------------- |
+| Single atom         | `useSelector(atom$)`                       | `useAtomValue(atom)`           | `useRecoilValue(atom)`          | `useStore(s => s.value)`   |
+| Derived value       | `useSelector(({ read }) => ...)`           | `useAtomValue(derivedAtom)`    | `useRecoilValue(selector)`      | `useStore(s => derive(s))` |
+| Multiple atoms      | `useSelector(({ all }) => all([a$, b$]))`  | Multiple `useAtomValue` calls  | Multiple `useRecoilValue` calls | Multiple selectors         |
+| Suspense mode       | Built-in (default)                         | Built-in                       | Built-in                        | Manual                     |
+| Loadable mode       | `useSelector(({ state }) => state(atom$))` | `useAtomValue(loadable(atom))` | `useRecoilValueLoadable(atom)`  | Manual                     |
+| Safe error handling | `safe()` in selector                       | Manual try/catch               | Manual try/catch                | Manual                     |
+| Custom equality     | 2nd parameter                              | `selectAtom`                   | N/A                             | 2nd parameter              |
+
+**Key advantages:**
+
+1. **Single unified hook** - No need to choose between `useAtomValue`, `useAtomValueLoadable`, etc.
+2. **Composable selectors** - Combine multiple atoms, derive values, handle errors in one selector
+3. **Flexible async modes** - Switch between Suspense and loadable without changing atoms
+4. **Built-in utilities** - `all()`, `any()`, `race()`, `settled()`, `safe()`, `state()` available in selector
+5. **Type-safe** - Full TypeScript inference across all patterns
+
+**Boilerplate comparison - Loading multiple async atoms:**
+
+```tsx
+// ❌ Jotai - Multiple hooks + loadable wrapper
+const userLoadable = useAtomValue(loadable(userAtom));
+const postsLoadable = useAtomValue(loadable(postsAtom));
+const isLoading =
+  userLoadable.state === "loading" || postsLoadable.state === "loading";
+const user = userLoadable.state === "hasData" ? userLoadable.data : null;
+const posts = postsLoadable.state === "hasData" ? postsLoadable.data : [];
+
+// ❌ Recoil - Multiple hooks
+const userLoadable = useRecoilValueLoadable(userAtom);
+const postsLoadable = useRecoilValueLoadable(postsAtom);
+const isLoading =
+  userLoadable.state === "loading" || postsLoadable.state === "loading";
+const user = userLoadable.state === "hasValue" ? userLoadable.contents : null;
+const posts = postsLoadable.state === "hasValue" ? postsLoadable.contents : [];
+
+// ✅ atomirx - One hook, one selector
+const { isLoading, user, posts } = useSelector(({ state }) => {
+  const userState = state(user$);
+  const postsState = state(posts$);
+  return {
+    isLoading:
+      userState.status === "loading" || postsState.status === "loading",
+    user: userState.value,
+    posts: postsState.value ?? [],
+  };
+});
+```
+
 ### Reactive Components with rx
 
-The `rx()` function creates inline reactive components for fine-grained updates:
+The `rx()` function creates inline reactive components for fine-grained updates.
+
+> **Note:** For error handling in selectors, use `safe()` instead of try/catch. See [Error Handling: Use `safe()` Not try/catch](#error-handling-use-safe-not-trycatch).
 
 ```tsx
 import { rx } from "atomirx/react";
@@ -1220,17 +1711,17 @@ function Dashboard() {
       <span>Count: {rx(count$)}</span>
 
       {/* Derived value */}
-      <span>Doubled: {rx(({ get }) => get(count$) * 2)}</span>
+      <span>Doubled: {rx(({ read }) => read(count$) * 2)}</span>
 
       {/* Complex rendering */}
-      {rx(({ get }) => {
-        const user = get(user$);
+      {rx(({ read }) => {
+        const user = read(user$);
         return user ? <UserCard user={user} /> : <LoginPrompt />;
       })}
 
       {/* Async with utilities */}
       {rx(({ all }) => {
-        const [user, posts] = all(user$, posts$);
+        const [user, posts] = all([user$, posts$]);
         return <Feed user={user} posts={posts} />;
       })}
     </div>
@@ -1240,6 +1731,79 @@ function Dashboard() {
 
 **Key benefit**: The parent component doesn't re-render when atoms change - only the `rx` components do.
 
+#### Inline Loading and Error Handling
+
+`rx()` supports optional `loading` and `error` handlers for inline async state handling without Suspense/ErrorBoundary:
+
+```tsx
+function Dashboard() {
+  return (
+    <div>
+      {/* With loading handler - no Suspense needed */}
+      {rx(userData$, {
+        loading: () => <Spinner />,
+      })}
+
+      {/* With error handler - no ErrorBoundary needed */}
+      {rx(userData$, {
+        error: ({ error }) => <Alert>{String(error)}</Alert>,
+      })}
+
+      {/* Both handlers - fully self-contained */}
+      {rx(userData$, {
+        loading: () => <UserSkeleton />,
+        error: ({ error }) => <UserError error={error} />,
+      })}
+
+      {/* With selector and options */}
+      {rx(({ read }) => read(posts$).slice(0, 5), {
+        loading: () => <PostsSkeleton count={5} />,
+        error: ({ error }) => <PostsError onRetry={() => posts$.refresh()} />,
+        equals: "shallow",
+      })}
+    </div>
+  );
+}
+```
+
+**When to use each approach:**
+
+| Approach                      | Use When                                               |
+| ----------------------------- | ------------------------------------------------------ |
+| `rx()` with Suspense          | Shared loading UI across multiple components           |
+| `rx()` with `loading`/`error` | Self-contained component with custom inline UI         |
+| `rx()` with `state()`         | Complex conditional rendering based on multiple states |
+
+#### Selector Memoization with `deps`
+
+By default, function selectors are recreated on every render. Use `deps` to control memoization:
+
+```tsx
+function Component({ multiplier }: { multiplier: number }) {
+  return (
+    <div>
+      {/* No memoization (default) - selector recreated every render */}
+      {rx(({ read }) => read(count$) * 2)}
+      {/* Stable forever - selector never recreated */}
+      {rx(({ read }) => read(count$) * 2, { deps: [] })}
+      {/* Recreate when multiplier changes */}
+      {rx(({ read }) => read(count$) * multiplier, { deps: [multiplier] })}
+      {/* Atom shorthand is always stable by reference */}
+      {rx(count$)} {/* No deps needed */}
+    </div>
+  );
+}
+```
+
+**Memoization behavior:**
+
+| Input                           | `deps`      | Behavior                          |
+| ------------------------------- | ----------- | --------------------------------- |
+| Atom (`rx(atom$)`)              | (ignored)   | Always memoized by atom reference |
+| Function (`rx(({ read }) => …`) | `undefined` | No memoization (recreated always) |
+| Function                        | `[]`        | Stable forever (never recreated)  |
+| Function                        | `[a, b]`    | Recreated when deps change        |
+
 ### Async Actions with useAction
 
 Handle async operations with built-in loading/error states:
@@ -1285,7 +1849,7 @@ const fetchUser = useAction(
 
 // Re-execute when atom changes
 const fetchPosts = useAction(
-  async ({ signal }) => fetchPostsApi(filter$.value, { signal }),
+  async ({ signal }) => fetchPostsApi(filter$.get(), { signal }),
   { lazy: false, deps: [filter$] }
 );
 ```
@@ -1340,13 +1904,13 @@ atomirx is designed to work seamlessly with React Suspense:
 import { Suspense } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { atom } from "atomirx";
-import { useValue } from "atomirx/react";
+import { useSelector } from "atomirx/react";
 
 const user$ = atom(fetchUser());
 
 function UserProfile() {
   // Suspends until user$ resolves
-  const user = useValue(user$);
+  const user = useSelector(user$);
   return <div>{user.name}</div>;
 }
 
@@ -1475,34 +2039,104 @@ function isAtom<T>(value: unknown): value is Atom<T>;
 
 ### SelectContext API
 
-Available in `derived()`, `effect()`, `useValue()`, and `rx()`:
+Available in `derived()`, `effect()`, `useSelector()`, and `rx()`:
 
-| Method    | Signature                          | Description                                  |
-| --------- | ---------------------------------- | -------------------------------------------- |
-| `get`     | `<T>(atom: Atom<T>) => Awaited<T>` | Read atom value with dependency tracking     |
-| `all`     | `(...atoms) => [values...]`        | Wait for all atoms (Promise.all semantics)   |
-| `any`     | `(...atoms) => value`              | First ready value (Promise.any semantics)    |
-| `race`    | `(...atoms) => value`              | First settled value (Promise.race semantics) |
-| `settled` | `(...atoms) => SettledResult[]`    | All results (Promise.allSettled semantics)   |
+| Method    | Signature                                 | Description                                          |
+| --------- | ----------------------------------------- | ---------------------------------------------------- |
+| `read`    | `<T>(atom: Atom<T>) => Awaited<T>`        | Read atom value with dependency tracking             |
+| `ready`   | `<T>(atom: Atom<T>) => NonNullable<T>`    | Wait for non-null value (only in derived/effect)     |
+| `all`     | `(atoms[]) => values[]`                   | Wait for all atoms (Promise.all semantics)           |
+| `any`     | `({ key: atom }) => { key, value }`       | First ready value (Promise.any semantics)            |
+| `race`    | `({ key: atom }) => { key, value }`       | First settled value (Promise.race semantics)         |
+| `settled` | `(atoms[]) => SettledResult[]`            | All results (Promise.allSettled semantics)           |
+| `state`   | `(atom \| selector) => SelectStateResult` | Get async state without throwing (equality-friendly) |
+| `safe`    | `(fn) => [error, result]`                 | Catch errors, preserve Suspense                      |
 
 **Behavior:**
 
-- `get()`: Returns value if ready, throws error if error, throws Promise if loading
+- `read()`: Returns value if ready, throws error if error, throws Promise if loading
+- `ready()`: Returns non-null value, suspends if null/undefined (only in derived/effect)
 - `all()`: Suspends until all atoms are ready, throws on first error
 - `any()`: Returns first ready value, throws AggregateError if all error
 - `race()`: Returns first settled (ready or error)
 - `settled()`: Returns `{ status: "ready", value }` or `{ status: "error", error }` for each atom
+- `state()`: Returns `AtomState<T>` without throwing - useful for inline state handling
+- `safe()`: Catches errors but re-throws Promises to preserve Suspense
+
+#### `state()` - Get Async State Without Throwing
+
+The `state()` method returns an `AtomState<T>` object instead of throwing. This is useful when you want to handle loading/error states inline without Suspense.
+
+**Available at every level** - derived, rx, useSelector, effect:
+
+```typescript
+// 1. In derived() - Build dashboard with partial loading
+const dashboard$ = derived(({ state }) => {
+  const userState = state(user$);
+  const postsState = state(posts$);
+
+  return {
+    user: userState.status === 'ready' ? userState.value : null,
+    posts: postsState.status === 'ready' ? postsState.value : [],
+    isLoading: userState.status === 'loading' || postsState.status === 'loading',
+  };
+});
+
+// 2. In rx() - Inline loading/error UI
+{rx(({ state }) => {
+  const dataState = state(data$);
+
+  if (dataState.status === 'loading') return <Spinner />;
+  if (dataState.status === 'error') return <Error error={dataState.error} />;
+  return <Content data={dataState.value} />;
+})}
+
+// 3. In useSelector() - Get state object in component
+function Component() {
+  const dataState = useSelector(({ state }) => state(asyncAtom$));
+
+  if (dataState.status === 'loading') return <Spinner />;
+  // ...
+}
+
+// 4. In effect() - React to state changes
+effect(({ state }) => {
+  const connState = state(connection$);
+
+  if (connState.status === 'ready') {
+    console.log('Connected:', connState.value);
+  }
+});
+
+// 5. With combined operations
+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()` vs `read()`:**
+
+| Method    | On Loading                                                          | On Error                                               | On Ready                                               |
+| --------- | ------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
+| `read()`  | Throws Promise (Suspense)                                           | Throws Error                                           | Returns value                                          |
+| `state()` | Returns `{ status: "loading", value: undefined, error: undefined }` | Returns `{ status: "error", value: undefined, error }` | Returns `{ status: "ready", value, error: undefined }` |
+
+**Note:** `state()` returns `SelectStateResult<T>` with all properties always present (`status`, `value`, `error`). This enables easy destructuring and equality comparisons (no promise reference issues).
 
 ### React API
 
-#### `useValue`
+#### `useSelector`
 
 ```typescript
 // Shorthand
-function useValue<T>(atom: Atom<T>): T;
+function useSelector<T>(atom: Atom<T>): T;
 
 // Context selector
-function useValue<T>(
+function useSelector<T>(
   selector: (context: SelectContext) => T,
   equals?: (prev: T, next: T) => boolean
 ): T;
@@ -1513,14 +2147,87 @@ function useValue<T>(
 ```typescript
 // Shorthand
 function rx<T>(atom: Atom<T>): ReactNode;
+function rx<T>(atom: Atom<T>, options?: RxOptions<T>): ReactNode;
 
 // Context selector
+function rx<T>(selector: (context: SelectContext) => T): ReactNode;
 function rx<T>(
   selector: (context: SelectContext) => T,
-  equals?: (prev: T, next: T) => boolean
+  options?: Equality<T> | RxOptions<T>
 ): ReactNode;
+
+interface RxOptions<T> {
+  /** Equality function for value comparison */
+  equals?: Equality<T>;
+  /** Render function for loading state (wraps with Suspense) */
+  loading?: () => ReactNode;
+  /** Render function for error state (wraps with ErrorBoundary) */
+  error?: (props: { error: unknown }) => ReactNode;
+  /** Dependencies for selector memoization */
+  deps?: unknown[];
+}
+```
+
+**Selector memoization with `deps`:**
+
+```tsx
+// No memoization (default) - selector recreated every render
+rx(({ read }) => read(count$) * multiplier);
+
+// Stable forever - never recreated
+rx(({ read }) => read(count$) * 2, { deps: [] });
+
+// Recreate when multiplier changes
+rx(({ read }) => read(count$) * multiplier, { deps: [multiplier] });
+
+// Atom shorthand is always stable (deps ignored)
+rx(count$);
+```
+
+**With inline loading/error handlers:**
+
+```tsx
+// Loading handler only
+{
+  rx(asyncAtom$, {
+    loading: () => <Spinner />,
+  });
+}
+
+// Error handler only
+{
+  rx(asyncAtom$, {
+    error: ({ error }) => <Alert>{String(error)}</Alert>,
+  });
+}
+
+// Both handlers
+{
+  rx(asyncAtom$, {
+    loading: () => <Skeleton />,
+    error: ({ error }) => <ErrorMessage error={error} />,
+  });
+}
+
+// With selector and options
+{
+  rx(({ read }) => read(user$).profile, {
+    loading: () => <ProfileSkeleton />,
+    error: ({ error }) => <ProfileError error={error} />,
+    equals: "shallow",
+  });
+}
 ```
 
+**Behavior with options:**
+
+| Options              | Loading State      | Error State      | Ready State  |
+| -------------------- | ------------------ | ---------------- | ------------ |
+| No options           | Suspense           | ErrorBoundary    | Render value |
+| `{ loading }`        | Render `loading()` | ErrorBoundary    | Render value |
+| `{ error }`          | Suspense           | Render `error()` | Render value |
+| `{ loading, error }` | Render `loading()` | Render `error()` | Render value |
+
 #### `useAction`
 
 ```typescript
@@ -1559,7 +2266,7 @@ import { atom, derived } from "atomirx";
 // Types are automatically inferred
 const count$ = atom(0); // MutableAtom<number>
 const name$ = atom("John"); // MutableAtom<string>
-const doubled$ = derived(({ get }) => get(count$) * 2); // Atom<number>
+const doubled$ = derived(({ read }) => read(count$) * 2); // Atom<number>
 
 // Explicit typing when needed
 interface User {
@@ -1572,8 +2279,8 @@ const user$ = atom<User | null>(null); // MutableAtom<User | null>
 const userData$ = atom<User>(fetchUser()); // MutableAtom<User>
 
 // Type-safe selectors
-const userName$ = derived(({ get }) => {
-  const user = get(user$);
+const userName$ = derived(({ read }) => {
+  const user = read(user$);
   return user?.name ?? "Anonymous"; // Atom<string>
 });
 
@@ -1638,8 +2345,8 @@ const todoList = createListAtom<Todo>();
 
 ### Community
 
-- [GitHub Issues](https://github.com/atomirx/atomirx/issues) - Bug reports and feature requests
-- [Discussions](https://github.com/atomirx/atomirx/discussions) - Questions and community support
+- [GitHub Issues](https://github.com/linq2js/atomirx/issues) - Bug reports and feature requests
+- [Discussions](https://github.com/linq2js/atomirx/discussions) - Questions and community support
 
 ## License