atomirx 0.0.1 → 0.0.4

package/src/core/effect.test.ts

@@ -8,8 +8,8 @@ describe("effect", () => {
       const effectFn = vi.fn();
       const count$ = atom(0);
 
-      effect(({ get }) => {
-        effectFn(get(count$));
+      effect(({ read }) => {
+        effectFn(read(count$));
       });
 
       // Wait for async execution
@@ -21,8 +21,8 @@ describe("effect", () => {
       const effectFn = vi.fn();
       const count$ = atom(0);
 
-      effect(({ get }) => {
-        effectFn(get(count$));
+      effect(({ read }) => {
+        effectFn(read(count$));
       });
 
       await new Promise((r) => setTimeout(r, 0));
@@ -39,8 +39,8 @@ describe("effect", () => {
       const a$ = atom(1);
       const b$ = atom(2);
 
-      effect(({ get }) => {
-        effectFn(get(a$) + get(b$));
+      effect(({ read }) => {
+        effectFn(read(a$) + read(b$));
       });
 
       await new Promise((r) => setTimeout(r, 0));
@@ -62,8 +62,8 @@ describe("effect", () => {
       const effectFn = vi.fn();
       const count$ = atom(0);
 
-      effect(({ get, onCleanup }) => {
-        effectFn(get(count$));
+      effect(({ read, onCleanup }) => {
+        effectFn(read(count$));
         onCleanup(cleanupFn);
       });
 
@@ -81,8 +81,8 @@ describe("effect", () => {
       const cleanupFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ get, onCleanup }) => {
-        get(count$);
+      const dispose = effect(({ read, onCleanup }) => {
+        read(count$);
         onCleanup(cleanupFn);
       });
 
@@ -99,8 +99,8 @@ describe("effect", () => {
       const effectFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ get }) => {
-        effectFn(get(count$));
+      const dispose = effect(({ read }) => {
+        effectFn(read(count$));
       });
 
       await new Promise((r) => setTimeout(r, 0));
@@ -118,8 +118,8 @@ describe("effect", () => {
       const cleanupFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ get, onCleanup }) => {
-        get(count$);
+      const dispose = effect(({ read, onCleanup }) => {
+        read(count$);
         onCleanup(cleanupFn);
       });
 
@@ -133,16 +133,22 @@ describe("effect", () => {
     });
   });
 
-  describe("error handling", () => {
-    it("should call onError callback when effect throws", async () => {
+  describe("error handling with safe()", () => {
+    it("should catch errors with safe() and return error tuple", async () => {
       const errorHandler = vi.fn();
       const count$ = atom(0);
-      const error = new Error("Effect error");
 
-      effect(({ get, onError }) => {
-        onError(errorHandler);
-        if (get(count$) > 0) {
-          throw error;
+      effect(({ read, safe }) => {
+        const [err] = safe(() => {
+          const count = read(count$);
+          if (count > 0) {
+            throw new Error("Effect error");
+          }
+          return count;
+        });
+
+        if (err) {
+          errorHandler(err);
         }
       });
 
@@ -151,30 +157,55 @@ describe("effect", () => {
 
       count$.set(5);
       await new Promise((r) => setTimeout(r, 10));
-      expect(errorHandler).toHaveBeenCalledWith(error);
+      expect(errorHandler).toHaveBeenCalledWith(expect.any(Error));
+      expect((errorHandler.mock.calls[0][0] as Error).message).toBe(
+        "Effect error"
+      );
     });
 
-    it("should call options.onError for unhandled errors", async () => {
-      const onError = vi.fn();
-      const count$ = atom(0);
-      const error = new Error("Effect error");
+    it("should return success tuple when no error", async () => {
+      const results: number[] = [];
+      const count$ = atom(5);
 
-      effect(
-        ({ get }) => {
-          if (get(count$) > 0) {
-            throw error;
-          }
-        },
-        { onError }
-      );
+      effect(({ read, safe }) => {
+        const [err, value] = safe(() => read(count$) * 2);
+        if (!err && value !== undefined) {
+          results.push(value);
+        }
+      });
 
       await new Promise((r) => setTimeout(r, 0));
-      expect(onError).not.toHaveBeenCalled();
+      expect(results).toEqual([10]);
 
-      count$.set(5);
+      count$.set(10);
       await new Promise((r) => setTimeout(r, 10));
-      // options.onError should be called for unhandled sync errors
-      expect(onError).toHaveBeenCalledWith(error);
+      expect(results).toEqual([10, 20]);
+    });
+
+    it("should preserve Suspense by re-throwing promises in safe()", async () => {
+      const effectFn = vi.fn();
+      let resolvePromise: (value: number) => void;
+      const promise = new Promise<number>((r) => {
+        resolvePromise = r;
+      });
+      const async$ = atom(promise);
+
+      effect(({ read, safe }) => {
+        // safe() should re-throw the promise, not catch it
+        const [err, value] = safe(() => read(async$));
+        if (!err) {
+          effectFn(value);
+        }
+      });
+
+      // Effect should not run yet (waiting for promise)
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Resolve the promise
+      resolvePromise!(42);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith(42);
     });
   });
 
@@ -185,7 +216,7 @@ describe("effect", () => {
       const b$ = atom(2);
 
       effect(({ all }) => {
-        const [a, b] = all(a$, b$);
+        const [a, b] = all([a$, b$]);
         effectFn(a + b);
       });
 
@@ -193,4 +224,193 @@ describe("effect", () => {
       expect(effectFn).toHaveBeenCalledWith(3);
     });
   });
+
+  describe("ready() - reactive suspension", () => {
+    it("should not run effect when ready() value is null", async () => {
+      const effectFn = vi.fn();
+      const id$ = atom<string | null>(null);
+
+      effect(({ ready }) => {
+        const id = ready(id$);
+        effectFn(id);
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      // Effect should not have run because id is null
+      expect(effectFn).not.toHaveBeenCalled();
+    });
+
+    it("should run effect when ready() value becomes non-null", async () => {
+      const effectFn = vi.fn();
+      const id$ = atom<string | null>(null);
+
+      effect(({ ready }) => {
+        const id = ready(id$);
+        effectFn(id);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Set non-null value
+      id$.set("article-123");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith("article-123");
+    });
+
+    it("should re-suspend when ready() value becomes null again", async () => {
+      const effectFn = vi.fn();
+      const id$ = atom<string | null>("initial");
+
+      effect(({ ready }) => {
+        const id = ready(id$);
+        effectFn(id);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).toHaveBeenCalledWith("initial");
+      expect(effectFn).toHaveBeenCalledTimes(1);
+
+      // Set to null - effect should not run
+      id$.set(null);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledTimes(1); // Still 1
+
+      // Set back to non-null
+      id$.set("new-value");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith("new-value");
+      expect(effectFn).toHaveBeenCalledTimes(2);
+    });
+
+    it("should support ready() with selector", async () => {
+      const effectFn = vi.fn();
+      const user$ = atom<{ id: number; email: string | null }>({
+        id: 1,
+        email: null,
+      });
+
+      effect(({ ready }) => {
+        const email = ready(user$, (u) => u.email);
+        effectFn(email);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Set email
+      user$.set({ id: 1, email: "test@example.com" });
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith("test@example.com");
+    });
+
+    it("should run cleanup when transitioning from non-null to null", async () => {
+      const cleanupFn = vi.fn();
+      const effectFn = vi.fn();
+      const id$ = atom<string | null>("initial");
+
+      effect(({ ready, onCleanup }) => {
+        const id = ready(id$);
+        effectFn(id);
+        onCleanup(cleanupFn);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).toHaveBeenCalledWith("initial");
+      expect(cleanupFn).not.toHaveBeenCalled();
+
+      // Set to null - should trigger cleanup from previous run
+      id$.set(null);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(cleanupFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should work with multiple ready() calls", async () => {
+      const effectFn = vi.fn();
+      const firstName$ = atom<string | null>(null);
+      const lastName$ = atom<string | null>(null);
+
+      effect(({ ready }) => {
+        const first = ready(firstName$);
+        const last = ready(lastName$);
+        effectFn(`${first} ${last}`);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Set only firstName - still suspended
+      firstName$.set("John");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Set lastName - effect should run
+      lastName$.set("Doe");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith("John Doe");
+    });
+
+    it("should allow mixing ready() with read()", async () => {
+      const effectFn = vi.fn();
+      const requiredId$ = atom<string | null>(null);
+      const optionalLabel$ = atom("default");
+
+      effect(({ ready, read }) => {
+        const id = ready(requiredId$);
+        const label = read(optionalLabel$);
+        effectFn({ id, label });
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Set required value
+      requiredId$.set("123");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith({ id: "123", label: "default" });
+
+      // Change optional value
+      effectFn.mockClear();
+      optionalLabel$.set("custom");
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith({ id: "123", label: "custom" });
+    });
+
+    it("should handle real-world: sync to localStorage only when user is logged in", async () => {
+      const mockStorage: Record<string, string> = {};
+      const currentUser$ = atom<{ id: string } | null>(null);
+      const preferences$ = atom({ theme: "dark" });
+
+      effect(({ ready, read, onCleanup }) => {
+        const user = ready(currentUser$);
+        const prefs = read(preferences$);
+
+        // Sync preferences to localStorage for logged-in user
+        mockStorage[`prefs:${user.id}`] = JSON.stringify(prefs);
+
+        onCleanup(() => {
+          delete mockStorage[`prefs:${user.id}`];
+        });
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      // No user logged in - nothing in storage
+      expect(Object.keys(mockStorage)).toHaveLength(0);
+
+      // User logs in
+      currentUser$.set({ id: "u1" });
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockStorage["prefs:u1"]).toBe('{"theme":"dark"}');
+
+      // Preferences change
+      preferences$.set({ theme: "light" });
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockStorage["prefs:u1"]).toBe('{"theme":"light"}');
+
+      // User logs out - cleanup runs
+      currentUser$.set(null);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(mockStorage["prefs:u1"]).toBeUndefined();
+    });
+  });
 });

package/src/core/effect.ts

@@ -1,15 +1,15 @@
 import { batch } from "./batch";
 import { derived } from "./derived";
 import { emitter } from "./emitter";
-import { isPromiseLike } from "./isPromiseLike";
-import { SelectContext } from "./select";
+import { ReactiveSelector, SelectContext } from "./select";
 import { EffectOptions } from "./types";
+import { WithReadySelectContext } from "./withReady";
 
 /**
  * Context object passed to effect functions.
- * Extends `SelectContext` with cleanup and error handling utilities.
+ * Extends `SelectContext` with cleanup utilities.
  */
-export interface EffectContext extends SelectContext {
+export interface EffectContext extends SelectContext, WithReadySelectContext {
   /**
    * Register a cleanup function that runs before the next execution or on dispose.
    * Multiple cleanup functions can be registered; they run in FIFO order.
@@ -18,44 +18,22 @@ export interface EffectContext extends SelectContext {
    *
    * @example
    * ```ts
-   * effect(({ get, onCleanup }) => {
+   * effect(({ read, onCleanup }) => {
    *   const id = setInterval(() => console.log('tick'), 1000);
    *   onCleanup(() => clearInterval(id));
    * });
    * ```
    */
   onCleanup: (cleanup: VoidFunction) => void;
-
-  /**
-   * Register an error handler for synchronous errors thrown in the effect.
-   * If registered, prevents errors from propagating to `options.onError`.
-   *
-   * @param handler - Function to handle errors
-   *
-   * @example
-   * ```ts
-   * effect(({ get, onError }) => {
-   *   onError((e) => console.error('Effect failed:', e));
-   *   riskyOperation();
-   * });
-   * ```
-   */
-  onError: (handler: (error: unknown) => void) => void;
 }
 
-/**
- * Callback function for effects.
- * Receives the effect context with `{ get, all, any, race, settled, onCleanup, onError }` utilities.
- */
-export type EffectFn = (context: EffectContext) => void;
-
 /**
  * Creates a side-effect that runs when accessed atom(s) change.
  *
  * Effects are similar to derived atoms but for side-effects rather than computed values.
  * They inherit derived's behavior:
  * - **Suspense-like async**: Waits for async atoms to resolve before running
- * - **Conditional dependencies**: Only tracks atoms actually accessed via `get()`
+ * - **Conditional dependencies**: Only tracks atoms actually accessed via `read()`
  * - **Automatic cleanup**: Previous cleanup runs before next execution
  * - **Batched updates**: Atom updates within the effect are batched
  *
@@ -65,23 +43,23 @@ export type EffectFn = (context: EffectContext) => void;
  *
  * ```ts
  * // ❌ WRONG - Don't use async function
- * effect(async ({ get }) => {
+ * effect(async ({ read }) => {
  *   const data = await fetch('/api');
  *   console.log(data);
  * });
  *
- * // ✅ CORRECT - Create async atom and read with get()
+ * // ✅ CORRECT - Create async atom and read with read()
  * const data$ = atom(fetch('/api').then(r => r.json()));
- * effect(({ get }) => {
- *   console.log(get(data$)); // Suspends until resolved
+ * effect(({ read }) => {
+ *   console.log(read(data$)); // Suspends until resolved
  * });
  * ```
  *
  * ## Basic Usage
  *
  * ```ts
- * const dispose = effect(({ get }) => {
- *   localStorage.setItem('count', String(get(countAtom)));
+ * const dispose = effect(({ read }) => {
+ *   localStorage.setItem('count', String(read(countAtom)));
  * });
  * ```
  *
@@ -90,85 +68,85 @@ export type EffectFn = (context: EffectContext) => void;
  * Use `onCleanup` to register cleanup functions that run before the next execution or on dispose:
  *
  * ```ts
- * const dispose = effect(({ get, onCleanup }) => {
- *   const interval = get(intervalAtom);
+ * const dispose = effect(({ read, onCleanup }) => {
+ *   const interval = read(intervalAtom);
  *   const id = setInterval(() => console.log('tick'), interval);
  *   onCleanup(() => clearInterval(id));
  * });
  * ```
  *
- * ## Error Handling
+ * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
  *
- * Use `onError` callback to handle errors within the effect, or `options.onError` for unhandled errors:
+ * **Never wrap `read()` calls in try/catch blocks.** The `read()` function throws
+ * Promises when atoms are loading (Suspense pattern). A try/catch will catch
+ * these Promises and break the Suspense mechanism.
  *
  * ```ts
- * // Callback-based error handling
- * const dispose = effect(({ get, onError }) => {
- *   onError((e) => console.error('Effect failed:', e));
- *   const data = get(dataAtom);
- *   riskyOperation(data);
+ * // ❌ WRONG - Catches Suspense Promise, breaks loading state
+ * effect(({ read }) => {
+ *   try {
+ *     const data = read(asyncAtom$);
+ *     riskyOperation(data);
+ *   } catch (e) {
+ *     console.error(e); // Catches BOTH errors AND loading promises!
+ *   }
  * });
  *
- * // Option-based error handling (for unhandled errors)
- * const dispose = effect(
- *   ({ get }) => {
- *     const data = get(dataAtom);
- *     riskyOperation(data);
- *   },
- *   { onError: (e) => console.error('Effect failed:', e) }
- * );
+ * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
+ * effect(({ read, safe }) => {
+ *   const [err, data] = safe(() => {
+ *     const raw = read(asyncAtom$);    // Can throw Promise (Suspense)
+ *     return riskyOperation(raw);      // Can throw Error
+ *   });
+ *
+ *   if (err) {
+ *     console.error('Operation failed:', err);
+ *     return;
+ *   }
+ *   // Use data safely
+ * });
  * ```
  *
- * @param fn - Effect callback receiving context with `{ get, all, any, race, settled, onCleanup, onError }`.
+ * The `safe()` utility:
+ * - **Catches errors** and returns `[error, undefined]`
+ * - **Re-throws Promises** to preserve Suspense behavior
+ * - Returns `[undefined, result]` on success
+ *
+ * @param fn - Effect callback receiving context with `{ read, all, any, race, settled, safe, onCleanup }`.
  *             Must be synchronous (not async).
- * @param options - Optional configuration (key, onError for unhandled errors)
+ * @param options - Optional configuration (key)
  * @returns Dispose function to stop the effect and run final cleanup
  * @throws Error if effect function returns a Promise
  */
-export function effect(fn: EffectFn, options?: EffectOptions): VoidFunction {
+export function effect(
+  fn: ReactiveSelector<void, EffectContext>,
+  _options?: EffectOptions
+): VoidFunction {
   let disposed = false;
   const cleanupEmitter = emitter();
-  const errorEmitter = emitter<unknown>();
 
   // Create a derived atom that runs the effect on each recomputation.
   const derivedAtom = derived((context) => {
     // Run previous cleanup before next execution
-    errorEmitter.clear();
     cleanupEmitter.emitAndClear();
 
     // Skip effect execution if disposed
     if (disposed) return;
 
-    try {
-      // Run effect in a batch - multiple atom updates will only notify once
-      batch(() =>
-        fn({
-          ...context,
-          onCleanup: cleanupEmitter.on,
-          onError: errorEmitter.on,
-        })
-      );
-    } catch (error) {
-      if (isPromiseLike(error)) {
-        // let derived atom handle the promise
-        throw error;
-      }
-      // Emit to registered handlers, or fall back to options.onError
-      if (errorEmitter.size() > 0) {
-        errorEmitter.emitAndClear(error);
-      } else if (options?.onError && error instanceof Error) {
-        options.onError(error);
-      }
-    }
+    // Run effect in a batch - multiple atom updates will only notify once
+    // Cast to EffectContext since we're adding onCleanup to the DerivedContext
+    const effectContext = {
+      ...context,
+      something: true,
+      onCleanup: cleanupEmitter.on,
+    } as unknown as EffectContext;
+    batch(() => fn(effectContext));
   });
 
-  // Access .value to trigger initial computation (derived is lazy)
-  // Handle the promise
-  derivedAtom.value.catch((error) => {
-    if (options?.onError && error instanceof Error) {
-      options.onError(error);
-    }
-    // Silently ignore if no error handler
+  // Access .get() to trigger initial computation (derived is lazy)
+  // Ignore promise rejection - errors should be handled via safe()
+  derivedAtom.get().catch(() => {
+    // Silently ignore - use safe() for error handling
   });
 
   return () => {
@@ -177,7 +155,6 @@ export function effect(fn: EffectFn, options?: EffectOptions): VoidFunction {
 
     // Mark as disposed
     disposed = true;
-    errorEmitter.clear();
     // Run final cleanup
     cleanupEmitter.emitAndClear();
   };

package/src/core/getAtomState.ts

@@ -0,0 +1,69 @@
+import { isDerived } from "./isAtom";
+import { isPromiseLike } from "./isPromiseLike";
+import { trackPromise } from "./promiseCache";
+import { Atom, AtomState, DerivedAtom } from "./types";
+
+/**
+ * Returns the current state of an atom as a discriminated union.
+ *
+ * For any atom (mutable or derived):
+ * - If value is not a Promise: returns ready state
+ * - If value is a Promise: tracks and returns its state (ready/error/loading)
+ *
+ * @param atom - The atom to get state from
+ * @returns AtomState discriminated union (ready | error | loading)
+ *
+ * @example
+ * ```ts
+ * const state = getAtomState(myAtom$);
+ *
+ * switch (state.status) {
+ *   case "ready":
+ *     console.log(state.value); // T
+ *     break;
+ *   case "error":
+ *     console.log(state.error);
+ *     break;
+ *   case "loading":
+ *     console.log(state.promise);
+ *     break;
+ * }
+ * ```
+ */
+export function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>> {
+  if (isDerived(atom)) {
+    return (atom as DerivedAtom<Awaited<T>>).state();
+  }
+  const value = atom.get();
+
+  // 1. Sync value - ready
+  if (!isPromiseLike(value)) {
+    return {
+      status: "ready",
+      value: value as Awaited<T>,
+    };
+  }
+
+  // 2. Promise value - check state via promiseCache
+  const state = trackPromise(value);
+
+  switch (state.status) {
+    case "fulfilled":
+      return {
+        status: "ready",
+        value: state.value as Awaited<T>,
+      };
+
+    case "rejected":
+      return {
+        status: "error",
+        error: state.error,
+      };
+
+    case "pending":
+      return {
+        status: "loading",
+        promise: state.promise as Promise<Awaited<T>>,
+      };
+  }
+}