rexfect 0.0.7

package/README.md

@@ -0,0 +1,1756 @@
+# rexfect
+
+Minimal reactive state management for JavaScript/TypeScript.
+
+## Introduction
+
+rexfect provides simple, predictable reactive state management with a minimal API surface. Unlike larger state management solutions, rexfect gives you just a few core primitives that compose together to handle any state management scenario:
+
+- **Atoms** for reactive state storage
+- **Effects** for synchronous reactions to state changes
+- **Actions** for async operations and business logic workflows
+
+This guide covers the most common use cases and patterns. Whether you're building a small widget or a large application, these patterns will help you write maintainable, reactive code.
+
+## Comparison with Other Tools
+
+### Boilerplate Comparison
+
+rexfect is designed to minimize boilerplate while maintaining type safety. Here's how a simple counter compares across libraries:
+
+**rexfect:**
+
+```typescript
+import { atom } from "rexfect";
+import { useRx } from "rexfect/react";
+
+const [count, setCount] = atom(0);
+
+function Counter() {
+  const value = useRx(() => count());
+  return <button onClick={() => setCount(count() + 1)}>{value}</button>;
+}
+```
+
+**Redux Toolkit:**
+
+```typescript
+import { createSlice, configureStore } from "@reduxjs/toolkit";
+import { Provider, useSelector, useDispatch } from "react-redux";
+
+const counterSlice = createSlice({
+  name: "counter",
+  initialState: { value: 0 },
+  reducers: {
+    increment: (state) => {
+      state.value += 1;
+    },
+  },
+});
+
+const store = configureStore({ reducer: { counter: counterSlice.reducer } });
+const { increment } = counterSlice.actions;
+
+function Counter() {
+  const value = useSelector((state) => state.counter.value);
+  const dispatch = useDispatch();
+  return <button onClick={() => dispatch(increment())}>{value}</button>;
+}
+
+// Must wrap app in <Provider store={store}>
+```
+
+**Zustand:**
+
+```typescript
+import { create } from "zustand";
+
+const useStore = create((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+}));
+
+function Counter() {
+  const count = useStore((state) => state.count);
+  const increment = useStore((state) => state.increment);
+  return <button onClick={increment}>{count}</button>;
+}
+```
+
+**Jotai:**
+
+```typescript
+import { atom, useAtom } from "jotai";
+
+const countAtom = atom(0);
+
+function Counter() {
+  const [count, setCount] = useAtom(countAtom);
+  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
+}
+```
+
+### Feature Comparison
+
+| Feature                    | rexfect        | Redux      | Zustand | Jotai   | MobX    |
+| -------------------------- | -------------- | ---------- | ------- | ------- | ------- |
+| **Boilerplate**            | Minimal        | High       | Low     | Minimal | Low     |
+| **Bundle Size**            | ~3KB           | ~10KB+     | ~2KB    | ~5KB    | ~15KB   |
+| **TypeScript**             | First-class    | Good       | Good    | Good    | Good    |
+| **Conditional Reactivity** | ✅             | ❌         | ❌      | ❌      | ✅      |
+| **React Suspense**         | ✅ Built-in    | ❌         | ❌      | ✅      | ❌      |
+| **Async Cancellation**     | ✅ Built-in    | Manual     | Manual  | Manual  | Manual  |
+| **Actions System**         | ✅ First-class | Middleware | Manual  | Manual  | Actions |
+| **DevTools**               | Planned        | ✅         | ✅      | ✅      | ✅      |
+
+### Conditional Reactivity
+
+Most libraries require you to select all dependencies upfront. rexfect tracks dependencies dynamically, so conditional reads just work:
+
+**rexfect - Conditional reads are automatic:**
+
+```typescript
+function UserDisplay() {
+  const display = useRx(() => {
+    // Only subscribes to lastName when showFull is true
+    // When showFull becomes false, lastName is automatically untracked
+    if (showFull()) {
+      return `${firstName()} ${lastName()}`;
+    }
+    return firstName();
+  });
+  return <span>{display}</span>;
+}
+```
+
+**Other libraries - Must handle manually:**
+
+```typescript
+// Zustand: Selector always subscribes to all selected state
+const useUserStore = create((set) => ({
+  showFull: true,
+  firstName: "Ada",
+  lastName: "Lovelace",
+}));
+
+function UserDisplay() {
+  // Option 1: Single selector - re-renders on ANY of these changes
+  const { showFull, firstName, lastName } = useUserStore((state) => ({
+    showFull: state.showFull,
+    firstName: state.firstName,
+    lastName: state.lastName, // Always tracked, even when showFull is false!
+  }));
+
+  return <span>{showFull ? `${firstName} ${lastName}` : firstName}</span>;
+}
+
+// Redux: Same issue with useSelector
+function UserDisplay() {
+  const { showFull, firstName, lastName } = useSelector((state) => ({
+    showFull: state.user.showFull,
+    firstName: state.user.firstName,
+    lastName: state.user.lastName, // Always tracked!
+  }));
+
+  return <span>{showFull ? `${firstName} ${lastName}` : firstName}</span>;
+}
+
+// Jotai: Derived atom reads all dependencies upfront
+const displayAtom = atom((get) => {
+  const showFull = get(showFullAtom);
+  const first = get(firstNameAtom);
+  const last = get(lastNameAtom); // Always read, even when showFull is false
+  return showFull ? `${first} ${last}` : first;
+});
+```
+
+### Suspense Support
+
+rexfect has first-class Suspense support with `read()` and `loadable()`:
+
+**rexfect:**
+
+```typescript
+import { read } from "rexfect/async";
+
+function UserProfile() {
+  // Automatically suspends until resolved
+  // Works with any Signal<Promise<T>>
+  const user = useRx(() => read(userPromise));
+  return <h1>{user.name}</h1>;
+}
+
+// Or use loadable() for manual loading states
+function UserProfileManual() {
+  const state = useRx(() => loadable(userPromise));
+  if (state?.loading) return <Spinner />;
+  if (state?.error) return <Error error={state.error} />;
+  return <h1>{state?.data?.name}</h1>;
+}
+```
+
+**Redux/Zustand:** No built-in Suspense support. Requires manual loading state management or additional libraries.
+
+**Jotai:** Has Suspense support but requires specific async atoms:
+
+```typescript
+// Must use special async atom pattern
+const userAtom = atom(async () => {
+  const response = await fetch("/api/user");
+  return response.json();
+});
+```
+
+### The Power of Actions
+
+rexfect's `action()` is a unique feature that handles async workflows elegantly.
+
+#### Key Characteristics
+
+Actions are more powerful than traditional functions because they are:
+
+1. **Listenable** - Subscribe to dispatches with `.on()`
+
+   - Multiple listeners can react to the same dispatch
+   - Perfect for side effects like analytics, logging, or state updates
+   - Supports async listeners
+
+2. **Awaitable** - Actions implement `PromiseLike` interface
+
+   - `await action` waits for the next dispatch
+   - `.latest()` gets the last value immediately or waits for next
+   - Enables elegant async coordination patterns
+
+3. **Simple** - No context, no lifecycle complexity
+   - Handlers are simple functions that receive the payload
+   - For complex cancellation/lifecycle needs, use `abortable()` utility
+
+#### Actions vs Traditional Functions
+
+| Feature                | Action                               | Traditional Function                     |
+| ---------------------- | ------------------------------------ | ---------------------------------------- |
+| **Multiple Listeners** | ✅ `.on()` for side effects          | ❌ Must call multiple functions manually |
+| **Awaitable**          | ✅ `await action` waits for dispatch | ❌ Must wrap in Promise manually         |
+| **Sealed (One-time)**  | ✅ `{ sealed: true }` option         | ❌ Manual flag checking                  |
+| **Late Subscribers**   | ✅ Auto-called with last value       | ❌ Manual synchronization                |
+| **Type Safety**        | ✅ Full TypeScript inference         | ✅ Same (functions are typed)            |
+| **Cancellation**       | ✅ Use `abortable()` wrapper         | ❌ Manual `AbortController` setup        |
+
+**Example Comparison:**
+
+```typescript
+// ❌ Traditional function - manual cancellation, no listeners, not awaitable
+let abortController: AbortController | null = null;
+
+function search(query: string) {
+  abortController?.abort();
+  abortController = new AbortController();
+
+  return fetch(`/api/search?q=${query}`, {
+    signal: abortController.signal,
+  }).then((r) => r.json());
+}
+
+// Must manually track listeners
+const listeners: Array<(query: string) => void> = [];
+function onSearch(callback: (query: string) => void) {
+  listeners.push(callback);
+}
+
+// Must wrap in Promise to await
+const promise = new Promise((resolve) => {
+  const result = search("hello");
+  listeners.forEach((cb) => cb("hello"));
+  resolve(result);
+});
+
+// ✅ Action - simple and powerful
+const search = action(async (query: string) => {
+  const res = await fetch(`/api/search?q=${query}`);
+  return res.json();
+});
+
+// Listeners subscribe easily
+search.on((query) => {
+  analytics.track("search", { query });
+});
+
+// Await directly
+const results = await search("hello");
+
+// For cancellation, wrap with abortable()
+import { abortable } from "rexfect/async";
+const cancellableSearch = abortable(async ({ signal }, query: string) => {
+  const res = await fetch(`/api/search?q=${query}`, { signal });
+  return res.json();
+});
+```
+
+**Naming Convention:**
+
+- **Void actions** (notifications): Use `on` prefix → `onClick`, `onLogin`, `onSearch`
+- **Actions with handlers** (commands): Use verbs → `addToCart`, `submitForm`, `fetchUser`
+
+**Thenable Actions - Await the next dispatch:**
+
+```typescript
+const onUserLogin = action<User>();
+
+// In one part of your app
+async function waitForLogin() {
+  const user = await onUserLogin; // Waits for next dispatch
+  console.log("User logged in:", user);
+}
+
+// In another part
+onUserLogin(currentUser); // Resolves the waiting promise
+```
+
+**Actions with Handlers - Return results:**
+
+```typescript
+// Simple sync handler
+const addToCart = action((item: CartItem) => {
+  const newCart = [...cart(), item];
+  setCart(newCart);
+  return newCart.length;
+});
+
+const count = addToCart({ id: "123", qty: 1 }); // count = new cart length
+```
+
+**Note:** Action handlers are automatically wrapped in `batch()`, so multiple atom updates in sync handlers are automatically batched. Only use explicit `batch()` if you need to batch updates that happen in async operations (after `await`).
+
+**Async Handlers:**
+
+```typescript
+// Simple async handler - no context needed
+const search = action(async (query: string) => {
+  const res = await fetch(`/api/search?q=${query}`);
+  return res.json();
+});
+
+const results = await search("hello");
+```
+
+**For cancellation, use `abortable()`:**
+
+```typescript
+import { abortable } from "rexfect/async";
+
+// Wrap with abortable for cancellation support
+const cancellableSearch = abortable(
+  async ({ signal, abortPrev }, query: string) => {
+    abortPrev(); // Cancel previous search
+
+    const res = await fetch(`/api/search?q=${query}`, {
+      signal, // Pass signal to fetch
+    });
+
+    return res.json();
+  }
+);
+
+// Rapid calls - only last one completes
+cancellableSearch("h");
+cancellableSearch("he");
+cancellableSearch("hel");
+const results = await cancellableSearch("hello"); // Only this completes
+```
+
+**Or use listeners for side effects:**
+
+```typescript
+// Void action with listener for side effects
+const onSearch = action<string>();
+
+onSearch.on(async (query) => {
+  const results = await fetch(`/api/search?q=${query}`);
+  const data = await results.json();
+  setResults(data);
+});
+
+onSearch("react");
+```
+
+**Sealed Actions - One-time initialization:**
+
+```typescript
+const onAppReady = action<Config>({ sealed: true });
+
+// Automatically seals after first dispatch
+onAppReady(config);
+onAppReady(newConfig); // No-op, safely ignored
+
+// Late subscribers get the sealed value immediately
+onAppReady.on((config) => {
+  // Called immediately with original config
+});
+```
+
+**Compare to other libraries:**
+
+| Pattern               | rexfect            | Redux            | Zustand                | Jotai       |
+| --------------------- | ------------------ | ---------------- | ---------------------- | ----------- |
+| Await action dispatch | `await action`     | N/A              | N/A                    | N/A         |
+| Cancel previous async | `abortable()`      | Write middleware | Manual AbortController | Manual      |
+| One-time init         | `{ sealed: true }` | Check flags      | Check flags            | Check flags |
+| Late subscribers      | Auto-called        | Manual sync      | Manual sync            | Manual sync |
+
+### When to Choose rexfect
+
+**Choose rexfect if you want:**
+
+- Minimal boilerplate with maximum type safety
+- Conditional reactivity without selector gymnastics
+- First-class async handling with cancellation
+- Built-in Suspense support
+- Action-driven architecture for complex workflows
+- Fine-grained reactivity with `pick()`
+
+**Consider Redux if you need:**
+
+- Time-travel debugging
+- Large ecosystem of middleware
+- Strict unidirectional data flow enforcement
+- Team familiarity with Redux patterns
+
+**Consider Zustand if you need:**
+
+- Minimal API similar to rexfect but more established
+- Easy migration from Redux
+- DevTools support today
+
+**Consider Jotai if you need:**
+
+- Atom-based model with React-first design
+- Strong Suspense integration
+- Atom-in-atom composition patterns
+
+## Mental Model: How It All Fits Together
+
+Understanding the relationship between atoms, effects, and events is key to using rexfect effectively.
+
+### The Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           APPLICATION                               │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   ┌─────────┐         ┌─────────┐         ┌─────────────────┐      │
+│   │  ATOMS  │◄────────│ EVENTS  │◄────────│   COMPONENTS    │      │
+│   │ (State) │         │ (Async) │         │   (UI Layer)    │      │
+│   └────┬────┘         └────▲────┘         └────────┬────────┘      │
+│        │                   │                       │               │
+│        │    ┌─────────┐    │                       │               │
+│        └───►│ EFFECTS │────┘                       │               │
+│             │ (Sync)  │                            │               │
+│             └─────────┘                            │               │
+│                                                    │               │
+│   ┌─────────┐                                      │               │
+│   │  ATOMS  │◄─────────────────────────────────────┘               │
+│   │ (Read)  │         Components read atoms via useRx()            │
+│   └─────────┘                                                      │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### The Three Primitives
+
+| Primitive   | Purpose          | Sync/Async          | Typical Use                                              |
+| ----------- | ---------------- | ------------------- | -------------------------------------------------------- |
+| **Atoms**   | Store state      | -                   | Hold your application data                               |
+| **Effects** | React to changes | **Sync only**       | Logging, localStorage, derived updates, dispatch actions |
+| **Actions** | Handle workflows | **Async supported** | API calls, business logic, user interactions             |
+
+### How They Work Together
+
+**1. Atoms hold your state:**
+
+```typescript
+const [user, setUser] = atom<User | null>(null);
+const [isLoading, setIsLoading] = atom(false);
+const [error, setError] = atom<Error | null>(null);
+```
+
+**2. Actions handle async operations and business logic:**
+
+```typescript
+// Action with handler for login
+const login = action(
+  async (credentials: { email: string; password: string }) => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const user = await api.login(credentials);
+      setUser(user);
+      return user;
+    } catch (err) {
+      setError(err as Error);
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }
+);
+```
+
+**3. Effects react to atom changes (sync only):**
+
+```typescript
+// Log when user changes
+effect(() => {
+  const currentUser = user();
+  if (currentUser) {
+    console.log("User logged in:", currentUser.email);
+  }
+});
+
+// Sync to localStorage
+effect((ctx) => {
+  const currentUser = user();
+  if (ctx.nth > 0) {
+    // Skip first run
+    localStorage.setItem("user", JSON.stringify(currentUser));
+  }
+});
+
+// Dispatch actions based on state changes
+effect(() => {
+  const currentUser = user();
+  if (currentUser && !currentUser.profileComplete) {
+    onShowProfileWizard(); // Dispatch an action
+  }
+});
+```
+
+**4. Components read atoms and dispatch actions:**
+
+```typescript
+function LoginForm() {
+  const loading = useRx(() => isLoading());
+  const loginError = useRx(() => error());
+
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault();
+    login({ email, password }); // Dispatch action
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {loginError && <p className="error">{loginError.message}</p>}
+      {/* ... form fields ... */}
+      <button disabled={loading}>{loading ? "Logging in..." : "Login"}</button>
+    </form>
+  );
+}
+
+function UserProfile() {
+  const currentUser = useRx(() => user());
+
+  if (!currentUser) return <LoginForm />;
+
+  return <h1>Welcome, {currentUser.name}!</h1>;
+}
+```
+
+### The Key Insight
+
+Think of it as a unidirectional flow:
+
+1. **User interactions** → dispatch **Actions**
+2. **Actions** → perform async work → update **Atoms**
+3. **Atoms** change → trigger **Effects** (sync reactions)
+4. **Effects** can → dispatch more **Actions** (for async follow-ups)
+5. **Components** → read **Atoms** → render UI
+
+```
+User Interaction ──► Action ──► Atom Update ──► Effect ──► Action (optional)
+                                    │
+                                    ▼
+                               Component Re-render
+```
+
+### Why This Separation Matters
+
+| Concern              | Handled By         | Why                                             |
+| -------------------- | ------------------ | ----------------------------------------------- |
+| **State storage**    | Atoms              | Single source of truth, fine-grained reactivity |
+| **Sync reactions**   | Effects            | Predictable, debuggable, no race conditions     |
+| **Async operations** | Actions            | Cancellation, error handling, workflow control  |
+| **UI rendering**     | Components + useRx | Automatic subscriptions, conditional tracking   |
+
+This separation keeps your code organized:
+
+- **Atoms** are just data - no logic
+- **Effects** are synchronous and predictable - easy to debug
+- **Actions** handle all the messy async stuff - with proper cancellation
+- **Components** just render - no business logic
+
+## Installation
+
+```bash
+# npm
+npm install rexfect
+
+# yarn
+yarn add rexfect
+
+# pnpm
+pnpm add rexfect
+```
+
+## Store Setup
+
+Every rexfect application needs to set up state using atoms. This is simpler than Redux - no store configuration, no reducers, just atoms.
+
+### Creating Your First Store
+
+The simplest way to create state is with the `atom()` function. Unlike Redux, there's no central store to configure:
+
+```typescript
+import { atom } from "rexfect";
+
+// Create reactive state - returns [getter, setter] tuple
+// Similar to React's useState, but works outside of components
+const [count, setCount] = atom(0);
+
+// Read the current value by calling the signal
+console.log(count()); // 0
+
+// Update the value with the setter
+setCount(5);
+console.log(count()); // 5
+```
+
+### Organizing State in Modules
+
+For larger applications, organize related atoms together in modules:
+
+```typescript
+// store/user.ts
+import { atom } from "rexfect";
+
+// User state
+export const [currentUser, setCurrentUser] = atom<User | null>(null);
+export const [isAuthenticated, setIsAuthenticated] = atom(false);
+
+// Preferences state
+export const [theme, setTheme] = atom<"light" | "dark">("light");
+export const [language, setLanguage] = atom("en");
+```
+
+```typescript
+// store/cart.ts
+import { atom } from "rexfect";
+
+interface CartItem {
+  productId: string;
+  quantity: number;
+  price: number;
+}
+
+// Shopping cart state
+export const [cartItems, setCartItems] = atom<CartItem[]>([]);
+export const [isCartOpen, setIsCartOpen] = atom(false);
+
+// Helper functions that work with the atoms
+export function addToCart(item: CartItem) {
+  setCartItems([...cartItems(), item]);
+}
+
+export function removeFromCart(productId: string) {
+  setCartItems(cartItems().filter((item) => item.productId !== productId));
+}
+
+export function getCartTotal(): number {
+  return cartItems().reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+```
+
+### Configuring Equality for Objects
+
+When atoms hold objects or arrays, you'll want to configure equality to avoid unnecessary updates:
+
+```typescript
+import { atom } from "rexfect";
+
+// Problem: Without equality config, setting the same object triggers updates
+const [user, setUser] = atom({ name: "Ada", age: 30 });
+setUser({ name: "Ada", age: 30 }); // This triggers subscribers (different reference)
+
+// Solution: Use shallow equality for simple objects
+const [user, setUser] = atom(
+  { name: "Ada", age: 30 },
+  { equals: "shallow" } // Only notifies if properties actually changed
+);
+setUser({ name: "Ada", age: 30 }); // No notification (same values)
+
+// For nested objects, use deeper equality
+const [config, setConfig] = atom(
+  {
+    ui: { theme: "dark", fontSize: 14 },
+    api: { baseUrl: "https://api.example.com", timeout: 5000 },
+  },
+  { equals: "shallow2" } // Compares 2 levels deep
+);
+
+// For complex nested structures, use deep equality
+const [appState, setAppState] = atom(deeplyNestedObject, { equals: "deep" });
+```
+
+**Available equality strategies:**
+
+| Strategy     | Use Case                              | Performance |
+| ------------ | ------------------------------------- | ----------- |
+| `"strict"`   | Primitives, immutable references      | Fastest     |
+| `"shallow"`  | Simple objects, arrays                | Fast        |
+| `"shallow2"` | Objects containing simple objects     | Medium      |
+| `"shallow3"` | 3 levels of nesting                   | Medium      |
+| `"deep"`     | Deeply nested structures              | Slower      |
+| `(a, b) =>…` | Custom comparison (e.g., by ID field) | Depends     |
+
+## Writing Effects
+
+Effects are synchronous reactions that run whenever their dependencies change. They're perfect for:
+
+- Logging and debugging
+- Syncing state to localStorage
+- Updating DOM elements
+- Triggering side effects
+
+### Basic Effect Pattern
+
+```typescript
+import { atom, effect } from "rexfect";
+
+const [firstName, setFirstName] = atom("Ada");
+const [lastName, setLastName] = atom("Lovelace");
+
+// Create an effect - it runs immediately, then re-runs when dependencies change
+// Dependencies are automatically tracked: any atom() called inside is a dependency
+const dispose = effect(() => {
+  // Reading firstName() and lastName() creates dependencies
+  console.log(`Hello, ${firstName()} ${lastName()}!`);
+});
+// Output: "Hello, Ada Lovelace!"
+
+// Update firstName - effect re-runs automatically
+setFirstName("Grace");
+// Output: "Hello, Grace Lovelace!"
+
+// When done, dispose the effect to stop it from running
+dispose();
+
+// Now updates won't trigger the effect
+setFirstName("Margaret"); // No output
+```
+
+### Effect Context and Error Handling
+
+Effects receive a context object with useful utilities:
+
+```typescript
+import { atom, effect } from "rexfect";
+
+const [data, setData] = atom<string | null>(null);
+
+const dispose = effect(
+  (ctx) => {
+    // ctx.nth: How many times the effect has run (0 on first run)
+    console.log(`Effect run #${ctx.nth}`);
+
+    // ctx.name: Effect name (from options) for debugging
+    console.log(`Effect name: ${ctx.name}`);
+
+    const value = data();
+
+    // ctx.onError: Register error handler for this effect run
+    ctx.onError((error) => {
+      console.error("Effect failed:", error);
+      // Handle error gracefully instead of crashing
+    });
+
+    if (value === "bad") {
+      throw new Error("Invalid data!");
+    }
+
+    console.log("Data:", value);
+  },
+  { name: "dataLogger" }
+);
+```
+
+### Syncing State to localStorage
+
+A common pattern is persisting state to localStorage:
+
+```typescript
+import { atom, effect } from "rexfect";
+
+// Create the atom with initial value from localStorage
+const [theme, setTheme] = atom<"light" | "dark">(
+  (localStorage.getItem("theme") as "light" | "dark") || "light"
+);
+
+// Sync to localStorage whenever theme changes
+effect((ctx) => {
+  const currentTheme = theme();
+
+  // Skip localStorage on first run (we just read from it)
+  if (ctx.nth === 0) return;
+
+  localStorage.setItem("theme", currentTheme);
+  console.log(`Theme saved: ${currentTheme}`);
+});
+
+// Now theme changes are automatically persisted
+setTheme("dark"); // Saves to localStorage
+```
+
+### ⚠️ Important: Effects Must Be Synchronous
+
+Effects are designed for synchronous operations only. If you need async operations, use Actions instead:
+
+```typescript
+import { atom, effect, action } from "rexfect";
+
+// ❌ WRONG: Don't use async in effects
+effect(async () => {
+  const data = await fetchData(); // This will throw an error!
+  setData(data);
+});
+
+// ✅ CORRECT: Use actions for async operations
+const fetchData = action(async (_, ctx) => {
+  ctx.abortPrev();
+  const data = await fetchDataFromApi();
+  setData(data);
+  return data;
+});
+
+// Dispatch the action to trigger the async operation
+fetchData();
+```
+
+## Batching Updates
+
+When updating multiple atoms, use `batch()` to ensure effects only run once.
+
+**Important:** Action handlers are automatically wrapped in `batch()`, so you don't need to wrap sync code inside action handlers. Only use explicit `batch()` for:
+
+- Updates outside of actions
+- Updates that happen after `await` in async action handlers
+
+```typescript
+import { atom, effect, batch, action } from "rexfect";
+
+const [x, setX] = atom(0);
+const [y, setY] = atom(0);
+const [z, setZ] = atom(0);
+
+// This effect depends on all three atoms
+effect(() => {
+  console.log(`Position: (${x()}, ${y()}, ${z()})`);
+});
+// Output: "Position: (0, 0, 0)"
+
+// ❌ WITHOUT batching - effect runs 3 times
+setX(1); // Output: "Position: (1, 0, 0)"
+setY(2); // Output: "Position: (1, 2, 0)"
+setZ(3); // Output: "Position: (1, 2, 3)"
+
+// ✅ WITH batching - effect runs once with final values
+batch(() => {
+  setX(10);
+  setY(20);
+  setZ(30);
+});
+// Output: "Position: (10, 20, 30)" (just once!)
+
+// ✅ Action handlers are automatically batched - no need for explicit batch()
+const updatePosition = action((coords: { x: number; y: number; z: number }) => {
+  setX(coords.x); // These are automatically batched
+  setY(coords.y);
+  setZ(coords.z);
+});
+updatePosition({ x: 100, y: 200, z: 300 });
+// Output: "Position: (100, 200, 300)" (just once!)
+
+// ✅ For async handlers, only wrap updates after await
+const fetchAndUpdate = action(async (_, ctx) => {
+  const data = await fetchData(); // Async operation
+
+  // Wrap updates after await in batch()
+  batch(() => {
+    setX(data.x);
+    setY(data.y);
+    setZ(data.z);
+  });
+});
+```
+
+## Handling Async Logic with Actions
+
+Actions are the primary way to handle async operations in rexfect. Unlike effects, actions support async handlers and provide cancellation utilities.
+
+### Basic Action Pattern
+
+```typescript
+import { action } from "rexfect";
+
+// Action with handler - executes logic and returns result
+const loginUser = action(
+  async (payload: { userId: string; timestamp: Date }) => {
+    console.log(`User ${payload.userId} logging in...`);
+
+    // Perform async operations
+    const profile = await fetchUserProfile(payload.userId);
+    console.log("Profile loaded:", profile);
+
+    return profile;
+  }
+);
+
+// Dispatch the action and get result
+const profile = await loginUser({ userId: "123", timestamp: new Date() });
+```
+
+### Actions with Handlers
+
+Actions can have a handler that returns a result. Handlers are simple functions:
+
+```typescript
+import { action, atom } from "rexfect";
+
+const [cart, setCart] = atom<CartItem[]>([]);
+
+// Simple sync handler
+const addToCart = action((item: CartItem) => {
+  const newCart = [...cart(), item];
+  setCart(newCart);
+  return newCart.length;
+});
+
+const cartCount = addToCart({ id: "123", qty: 1 });
+
+// Async handler
+const fetchProduct = action(async (id: string) => {
+  const res = await fetch(`/api/products/${id}`);
+  return res.json();
+});
+
+const product = await fetchProduct("123");
+```
+
+### Cancellation with `abortable()`
+
+For cancellation support, wrap your handler with `abortable()`:
+
+```typescript
+import { action } from "rexfect";
+import { abortable } from "rexfect/async";
+
+// Wrap with abortable for cancellation support
+const search = abortable(async ({ signal, abortPrev }, query: string) => {
+  // abortPrev(): Cancel the previous dispatch
+  // Call at start for "latest only" patterns
+  abortPrev();
+
+  // signal: AbortSignal for cancellation
+  // Pass to fetch, axios, etc.
+  const response = await fetch(`/api/search?q=${query}`, {
+    signal,
+  });
+
+  return response.json();
+});
+
+// Rapid dispatches: only the last one completes
+search("r");
+search("re");
+search("rea");
+search("reac");
+const results = await search("react"); // Only this one completes
+```
+
+### Actions are Thenable
+
+Actions implement the Promise interface, so you can await them:
+
+```typescript
+import { action } from "rexfect";
+
+const onUserReady = action<User>();
+
+// Await the NEXT dispatch
+async function waitForUser() {
+  const user = await onUserReady;
+  console.log("User is ready:", user);
+}
+
+// Or use .latest() to get the last value OR wait for next
+async function getUser() {
+  const user = await onUserReady.latest();
+  return user;
+}
+```
+
+### Sealed Actions for One-Time Initialization
+
+Use sealed actions for initialization that should only happen once:
+
+```typescript
+import { action } from "rexfect";
+
+// Sealed action with handler - auto-seals after first dispatch
+const initApp = action(
+  async (config: { version: string }) => {
+    console.log(`App v${config.version} initializing...`);
+    await initializeServices();
+    return { initialized: true, version: config.version };
+  },
+  { sealed: true }
+);
+
+// First call executes handler and seals
+const result = await initApp({ version: "1.0.0" });
+// Output: "App v1.0.0 initializing..."
+
+// Subsequent calls still execute handler but listeners don't fire
+await initApp({ version: "2.0.0" }); // Handler runs, but sealed
+
+// Check action state
+console.log(initApp.sealed()); // true
+console.log(initApp.fired()); // true
+
+// Late subscribers on sealed actions fire immediately with last payload
+initApp.on((config) => {
+  console.log("Late subscriber:", config.version);
+});
+// Output: "Late subscriber: 1.0.0"
+```
+
+### Real-World Example: Search with Cancellation
+
+```typescript
+import { atom, action } from "rexfect";
+import { abortable } from "rexfect/async";
+
+// State
+const [searchQuery, setSearchQuery] = atom("");
+const [searchResults, setSearchResults] = atom<Result[]>([]);
+const [isSearching, setIsSearching] = atom(false);
+const [searchError, setSearchError] = atom<Error | null>(null);
+
+// Wrap with abortable for cancellation support
+const search = abortable(async ({ signal, abortPrev }, query: string) => {
+  // Cancel any in-flight search
+  abortPrev();
+
+  // Reset error state
+  setSearchError(null);
+  setIsSearching(true);
+
+  try {
+    // Make API call with cancellation support
+    const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
+      signal,
+    });
+
+    const data = await response.json();
+
+    // Only update state if not aborted
+    setSearchResults(data.results);
+    return data.results;
+  } catch (error) {
+    // Don't set error if it was just an abort
+    if (error instanceof Error && error.name !== "AbortError") {
+      setSearchError(error);
+    }
+    throw error;
+  } finally {
+    setIsSearching(false);
+  }
+});
+
+// UI handler
+function handleSearchInput(query: string) {
+  setSearchQuery(query);
+  search(query);
+}
+```
+
+## Async UI Patterns
+
+For React and other UI frameworks, rexfect provides utilities for handling async state in the UI layer.
+
+### Loading States with `loadable()`
+
+Extract loading, data, and error states from Promise-valued atoms:
+
+```typescript
+import { atom, effect } from "rexfect";
+import { loadable } from "rexfect/async";
+
+// Create an atom that holds a Promise (or null for "not started")
+const [userPromise, setUserPromise] = atom<Promise<User> | null>(null);
+
+// React to loading states
+effect(() => {
+  const state = loadable(userPromise);
+
+  // null means we haven't started loading yet
+  if (state === null) {
+    console.log("Idle - click to load");
+    return;
+  }
+
+  // state.loading: true while Promise is pending
+  if (state.loading) {
+    console.log("Loading user...");
+    return;
+  }
+
+  // state.error: set if Promise rejected
+  if (state.error) {
+    console.error("Failed to load:", state.error);
+    return;
+  }
+
+  // state.data: the resolved value
+  console.log("User loaded:", state.data);
+});
+
+// Start loading by setting a Promise
+function loadUser(id: string) {
+  setUserPromise(fetch(`/api/users/${id}`).then((r) => r.json()));
+}
+
+// Example usage
+loadUser("123");
+```
+
+### React Suspense with `read()`
+
+For React Suspense integration, use `read()` to suspend until data is ready:
+
+```typescript
+import { atom } from "rexfect";
+import { useRx } from "rexfect/react";
+import { read } from "rexfect/async";
+import { Suspense } from "react";
+
+// Create atom holding a Promise
+const [userPromise] = atom(fetchUser("123"));
+
+function UserProfile() {
+  // read() throws the Promise (suspends) until resolved
+  // When resolved, returns the value directly
+  const user = useRx(() => read(userPromise));
+
+  // This only renders after user is loaded!
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
+  );
+}
+
+// Wrap in Suspense boundary to handle loading state
+function App() {
+  return (
+    <Suspense fallback={<div>Loading user...</div>}>
+      <UserProfile />
+    </Suspense>
+  );
+}
+```
+
+### Multiple Async Dependencies
+
+Use `read.all()` for components that depend on multiple async values:
+
+```typescript
+import { read } from "rexfect/async";
+import { useRx } from "rexfect/react";
+
+function Dashboard() {
+  // Suspends until BOTH promises resolve
+  const { user, settings, notifications } = useRx(() =>
+    read.all({
+      user: userSignal,
+      settings: settingsSignal,
+      notifications: notificationsSignal,
+    })
+  );
+
+  return (
+    <div>
+      <h1>Welcome, {user.name}!</h1>
+      <p>Theme: {settings.theme}</p>
+      <p>Notifications: {notifications.length}</p>
+    </div>
+  );
+}
+```
+
+### Using `wait` for Async Workflows
+
+The `wait` utilities are for use with `await` in action handlers:
+
+```typescript
+import { action } from "rexfect";
+import { wait } from "rexfect/async";
+
+// Initialize with multiple async dependencies
+const initialize = action(async (_, ctx) => {
+  ctx.abortPrev();
+
+  // wait.all(): Wait for multiple promises/actions
+  const { user, config } = await wait.all({
+    user: fetchUser(),
+    config: fetchConfig(),
+  });
+
+  console.log("Initialized with:", { user, config });
+  return { user, config };
+});
+
+// Racing multiple operations with timeout
+const fetchWithTimeout = action(async (_, ctx) => {
+  ctx.abortPrev();
+
+  // wait.race(): Returns [winner, value] for objects
+  const [winner, value] = await wait.race({
+    data: fetchData(),
+    timeout: delay(5000),
+  });
+
+  if (winner === "timeout") {
+    throw new Error("Request timed out!");
+  }
+
+  return value;
+});
+
+// Get first success, ignore failures
+const fetchWithFallback = action(async (_, ctx) => {
+  ctx.abortPrev();
+
+  // wait.any(): Returns first successful result
+  const [winner, value] = await wait.any({
+    primary: fetchFromPrimary(),
+    backup: fetchFromBackup(),
+  });
+
+  console.log(`Got data from ${winner}`);
+  return value;
+});
+```
+
+## React Integration
+
+### The `useRx` Hook
+
+The `useRx` hook lets you use reactive values in React components. Unlike other libraries:
+
+- Works with **multiple atoms** in a single call
+- Supports **conditional** atom reads
+- Detects changes on **atoms themselves**, not selector results
+
+```typescript
+import { atom } from "rexfect";
+import { useRx } from "rexfect/react";
+
+// Define atoms at module level (outside components)
+const [firstName, setFirstName] = atom("Ada");
+const [lastName, setLastName] = atom("Lovelace");
+const [showFullName, setShowFullName] = atom(true);
+
+function UserGreeting() {
+  // useRx tracks ALL atoms read inside the callback
+  // Component re-renders when ANY of them change
+  const greeting = useRx(() => {
+    const first = firstName();
+
+    // Conditional reads are fully supported!
+    // lastName is only tracked when showFullName is true
+    if (showFullName()) {
+      return `Hello, ${first} ${lastName()}!`;
+    }
+
+    return `Hello, ${first}!`;
+  });
+
+  return <h1>{greeting}</h1>;
+}
+```
+
+### Working with Complex State
+
+```typescript
+import { atom } from "rexfect";
+import { useRx } from "rexfect/react";
+
+interface Todo {
+  id: string;
+  text: string;
+  completed: boolean;
+}
+
+const [todos, setTodos] = atom<Todo[]>([]);
+const [filter, setFilter] = atom<"all" | "active" | "completed">("all");
+
+function TodoList() {
+  // Computed values work naturally
+  const filteredTodos = useRx(() => {
+    const all = todos();
+    const currentFilter = filter();
+
+    switch (currentFilter) {
+      case "active":
+        return all.filter((t) => !t.completed);
+      case "completed":
+        return all.filter((t) => t.completed);
+      default:
+        return all;
+    }
+  });
+
+  const stats = useRx(() => ({
+    total: todos().length,
+    completed: todos().filter((t) => t.completed).length,
+    active: todos().filter((t) => !t.completed).length,
+  }));
+
+  return (
+    <div>
+      <p>
+        {stats.active} active, {stats.completed} completed
+      </p>
+      <ul>
+        {filteredTodos.map((todo) => (
+          <li key={todo.id}>{todo.text}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function FilterButtons() {
+  // Each component subscribes to just what it needs
+  const currentFilter = useRx(() => filter());
+
+  return (
+    <div>
+      <button
+        className={currentFilter === "all" ? "active" : ""}
+        onClick={() => setFilter("all")}
+      >
+        All
+      </button>
+      <button
+        className={currentFilter === "active" ? "active" : ""}
+        onClick={() => setFilter("active")}
+      >
+        Active
+      </button>
+      <button
+        className={currentFilter === "completed" ? "active" : ""}
+        onClick={() => setFilter("completed")}
+      >
+        Completed
+      </button>
+    </div>
+  );
+}
+```
+
+### StrictMode Compatibility
+
+`useRx` is fully compatible with React StrictMode. It properly handles the double-invocation of effects that StrictMode uses to detect side effects.
+
+## Fine-Grained Reactivity with `pick()`
+
+The `pick()` function enables fine-grained subscriptions to specific properties. This prevents unnecessary re-renders when unrelated properties change.
+
+### Basic Usage
+
+```typescript
+import { atom, effect, pick } from "rexfect";
+
+const [user, setUser] = atom({
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+  visits: 0,
+  lastActive: new Date(),
+});
+
+// ❌ WITHOUT pick() - re-runs on ANY property change
+effect(() => {
+  const u = user(); // Tracks entire object
+  console.log("User name:", u.name);
+});
+
+// ✅ WITH pick() - only re-runs when name changes
+effect(() => {
+  // pick() creates a fine-grained subscription to just the selected value
+  const name = pick(() => user().name);
+  console.log("User name (optimized):", name);
+});
+
+// This triggers the first effect but NOT the second
+setUser({ ...user(), visits: user().visits + 1 });
+
+// This triggers BOTH effects
+setUser({ ...user(), name: "Grace Hopper" });
+```
+
+### Using pick() with React
+
+```typescript
+import { atom } from "rexfect";
+import { useRx, pick } from "rexfect/react";
+
+const [user, setUser] = atom({
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+  avatar: "/avatars/ada.png",
+  stats: { posts: 42, followers: 1000 },
+});
+
+// This component only re-renders when name changes
+function UserName() {
+  const name = useRx(() => pick(() => user().name));
+  return <h1>{name}</h1>;
+}
+
+// This component only re-renders when email changes
+function UserEmail() {
+  const email = useRx(() => pick(() => user().email));
+  return <p>{email}</p>;
+}
+
+// This component only re-renders when stats changes
+// Using shallow equality for the stats object
+function UserStats() {
+  const stats = useRx(() => pick(() => user().stats, "shallow"));
+  return (
+    <p>
+      {stats.posts} posts, {stats.followers} followers
+    </p>
+  );
+}
+```
+
+### Custom Equality with pick()
+
+For object properties, you can specify how to compare values:
+
+```typescript
+import { atom, effect, pick } from "rexfect";
+
+const [state, setState] = atom({
+  user: {
+    profile: { name: "Ada", avatar: "👩‍💻" },
+    settings: { theme: "dark", notifications: true },
+  },
+  stats: { pageViews: 0 },
+});
+
+effect(() => {
+  // Use "shallow" equality for the profile object
+  // Only re-runs if profile properties actually changed
+  const profile = pick(() => state().user.profile, "shallow");
+  console.log("Profile:", profile);
+});
+
+effect(() => {
+  // Use custom equality - compare by specific field
+  const theme = pick(
+    () => state().user.settings,
+    (a, b) => a.theme === b.theme // Only care about theme changes
+  );
+  console.log("Settings (theme only):", theme);
+});
+```
+
+## Reading Without Tracking
+
+Use `untrack()` to read atoms without creating dependencies:
+
+```typescript
+import { atom, effect, untrack } from "rexfect";
+
+const [count, setCount] = atom(0);
+const [multiplier, setMultiplier] = atom(2);
+
+effect(() => {
+  const c = count(); // Tracked - changes trigger re-run
+
+  // multiplier is read but NOT tracked
+  // Changes to multiplier won't trigger this effect
+  const m = untrack(() => multiplier());
+
+  console.log(`${c} x ${m} = ${c * m}`);
+});
+
+setCount(5); // Effect runs: "5 x 2 = 10"
+setMultiplier(3); // Effect does NOT run (untracked)
+setCount(6); // Effect runs: "6 x 3 = 18" (uses current multiplier)
+```
+
+## TypeScript Support
+
+rexfect is written in TypeScript and provides full type inference:
+
+```typescript
+import { atom, effect, action, pick } from "rexfect";
+
+// Types are inferred from initial value
+const [count, setCount] = atom(0);
+// count: Signal<number>
+// setCount: Setter<number>
+
+// Explicit generic for complex types
+const [user, setUser] = atom<User | null>(null);
+// user: Signal<User | null>
+// setUser: Setter<User | null>
+
+// Actions with payload types (use "on" prefix for void actions)
+const onClick = action<MouseEvent>();
+// onClick: Action<MouseEvent, void>
+
+// Void actions (no payload needed)
+const onReset = action();
+// onReset: Action<void, void>
+
+// Actions with handlers (use verb naming)
+const addItem = action((item: Item) => items.push(item));
+// addItem: Action<Item, number>
+
+// pick() infers the selected type
+const [state] = atom({ user: { name: "Ada" }, count: 0 });
+effect(() => {
+  const name = pick(() => state().user.name);
+  // name: string (inferred!)
+});
+```
+
+## API Reference
+
+### Core Functions
+
+#### `atom(initialValue, options?)`
+
+Creates a reactive state container.
+
+```typescript
+function atom<T>(
+  initialValue: T,
+  options?: {
+    equals?: Equality<T>; // "strict" | "shallow" | "shallow2" | "shallow3" | "deep" | (a, b) => boolean
+    key?: string; // For debugging
+  }
+): [Signal<T>, Setter<T>];
+```
+
+**Returns:** `[signal, setter]` tuple
+
+- `signal()` - Call to get current value (tracks in reactive contexts)
+- `signal.on(listener)` - Subscribe to changes, returns unsubscribe function
+- `setter(value)` - Update the value
+
+#### `effect(fn, options?)`
+
+Creates a synchronous reactive effect that re-runs when dependencies change.
+
+```typescript
+function effect(
+  fn: (ctx: EffectContext) => void,
+  options?: { name?: string }
+): VoidFunction; // Returns dispose function
+
+interface EffectContext {
+  nth: number; // Run count (0 on first run)
+  name?: string; // Effect name from options
+  onError(handler: (error: unknown) => void): void;
+  use<R>(plugin: (ctx: EffectContext) => R): R;
+}
+```
+
+#### `action(options?)` or `action(handler, options?)`
+
+Creates an action dispatcher for async operations and workflows.
+
+**Naming Convention:**
+
+- Void actions (no handler): Use `on` prefix → `onClick`, `onSubmit`
+- Actions with handlers: Use verbs → `addItem`, `fetchUser`
+
+```typescript
+// Void action (event-like)
+function action<T = void>(options?: ActionOptions): Action<T, void>;
+
+// Action with handler (receives ActionContext)
+function action<T, R>(
+  handler: (payload: T, ctx: ActionContext) => R,
+  options?: ActionOptions
+): Action<T, R>;
+
+interface ActionOptions {
+  sealed?: boolean; // Auto-seal after first dispatch
+  key?: string; // For debugging
+}
+
+interface Action<T, R = void> {
+  (payload: T): R; // Dispatch and return result
+  on(listener: (payload: T) => void | Promise<void>): VoidFunction;
+  sealed(): boolean; // Is the action sealed?
+  fired(): boolean; // Has the action been dispatched?
+  latest(): Promise<T>; // Get last payload or wait for next
+  then(...): Promise<T>; // Thenable - await next dispatch
+}
+```
+
+#### `batch(fn)`
+
+Groups multiple state updates into a single reactive cycle.
+
+```typescript
+function batch<T>(fn: () => T): T;
+```
+
+#### `untrack(fn)`
+
+Reads atoms without creating dependencies.
+
+```typescript
+function untrack<T>(fn: () => T): T;
+```
+
+#### `pick(fn, equals?)`
+
+Fine-grained selector for subscribing to specific properties.
+
+```typescript
+function pick<T>(
+  fn: () => T,
+  equals?: Equality<T> // Default: "strict"
+): T;
+```
+
+**Note:** Only works inside reactive contexts (`effect()`, `useRx()`).
+
+---
+
+### Async Utilities (`rexfect/async`)
+
+#### `loadable(signal)`
+
+Extracts loading state from a Promise-valued signal.
+
+```typescript
+function loadable<T>(
+  signal: Signal<Promise<T> | null | undefined>
+): LoadableResult<T> | null;
+
+interface LoadableResult<T> {
+  loading: boolean;
+  data: T | undefined;
+  error: unknown | undefined;
+}
+```
+
+**Returns:** `null` if signal value is null/undefined, otherwise `LoadableResult`.
+
+#### `read(signal)`
+
+Suspense-compatible reading from a Promise signal. Throws the Promise (suspends) until resolved.
+
+```typescript
+function read<T>(signal: Signal<Promise<T>>): T;
+
+// Combinators
+read.all(signals): { ... }     // Read all, suspend until done
+read.race(signals): ...        // Read first to settle
+read.any(signals): ...         // Read first to succeed
+read.settled(signals): ...     // Read all (no throw on rejection)
+```
+
+**Note:** For use in React components with Suspense only.
+
+#### `wait(input)`
+
+Promise wrapper for any PromiseLike (including Actions).
+
+```typescript
+function wait<T>(input: PromiseLike<T>): Promise<T>;
+
+// Combinators - work with arrays or objects
+wait.all([p1, p2]): Promise<[T1, T2]>
+wait.all({ a: p1, b: p2 }): Promise<{ a: T1, b: T2 }>
+
+wait.race([p1, p2]): Promise<T1 | T2>
+wait.race({ a: p1, b: p2 }): Promise<["a" | "b", T]>  // [winner, value]
+
+wait.any([p1, p2]): Promise<T1 | T2>
+wait.any({ a: p1, b: p2 }): Promise<["a" | "b", T]>
+
+wait.settled([p1, p2]): Promise<PromiseSettledResult[]>
+wait.settled({ a: p1, b: p2 }): Promise<{ a: PromiseSettledResult, ... }>
+```
+
+---
+
+### React Bindings (`rexfect/react`)
+
+#### `useRx(fn)`
+
+React hook for reactive computations. Tracks all atoms read during the callback and re-renders when they change.
+
+```typescript
+function useRx<T>(fn: () => T): T;
+```
+
+**Features:**
+
+- Works with multiple atoms
+- Supports conditional reads
+- StrictMode compatible
+- Works with `pick()` for fine-grained subscriptions
+
+---
+
+### Equality Utilities
+
+Pre-built equality functions for atom configuration:
+
+```typescript
+import {
+  strictEqual, // Object.is (default)
+  shallowEqual, // 1-level object/array compare
+  shallow2Equal, // 2-level compare
+  shallow3Equal, // 3-level compare
+  deepEqual, // Full recursive compare (lodash isEqual)
+} from "rexfect";
+
+// Usage
+const [user, setUser] = atom(userData, { equals: shallowEqual });
+```
+
+## Documentation
+
+For more detailed information, see:
+
+- [API Reference](./docs/API.md) - Complete API documentation
+- [Core Concepts](./docs/CONCEPTS.md) - Deep dive into how rexfect works
+- [Design Document](./docs/DESIGN.md) - Architecture and design decisions
+
+## License
+
+MIT