atomirx 0.0.1 → 0.0.4

package/src/core/derived.test.ts

@@ -7,56 +7,56 @@ describe("derived", () => {
   describe("basic functionality", () => {
     it("should create a derived atom from a source atom", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
 
-      expect(await doubled$.value).toBe(10);
+      expect(await doubled$.get()).toBe(10);
     });
 
     it("should have SYMBOL_ATOM and SYMBOL_DERIVED markers", () => {
       const count$ = atom(0);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
 
       expect(doubled$[SYMBOL_ATOM]).toBe(true);
       expect(doubled$[SYMBOL_DERIVED]).toBe(true);
     });
 
-    it("should always return a Promise from .value", () => {
+    it("should always return a Promise from .get()", () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
 
-      expect(doubled$.value).toBeInstanceOf(Promise);
+      expect(doubled$.get()).toBeInstanceOf(Promise);
     });
 
     it("should update when source atom changes", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
 
-      expect(await doubled$.value).toBe(10);
+      expect(await doubled$.get()).toBe(10);
       count$.set(10);
-      expect(await doubled$.value).toBe(20);
+      expect(await doubled$.get()).toBe(20);
     });
 
     it("should derive from multiple atoms", async () => {
       const a$ = atom(2);
       const b$ = atom(3);
-      const sum$ = derived(({ get }) => get(a$) + get(b$));
+      const sum$ = derived(({ read }) => read(a$) + read(b$));
 
-      expect(await sum$.value).toBe(5);
+      expect(await sum$.get()).toBe(5);
       a$.set(10);
-      expect(await sum$.value).toBe(13);
+      expect(await sum$.get()).toBe(13);
       b$.set(7);
-      expect(await sum$.value).toBe(17);
+      expect(await sum$.get()).toBe(17);
     });
   });
 
   describe("staleValue", () => {
     it("should return undefined initially without fallback", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
 
       // Before resolution, staleValue is undefined (no fallback)
       // After resolution, it becomes the resolved value
-      await doubled$.value;
+      await doubled$.get();
       expect(doubled$.staleValue).toBe(10);
     });
 
@@ -64,7 +64,7 @@ describe("derived", () => {
       // For sync atoms, computation is immediate so staleValue is already resolved
       // Test with async dependency to verify fallback behavior
       const asyncValue$ = atom(new Promise<number>(() => {})); // Never resolves
-      const derived$ = derived(({ get }) => get(asyncValue$) * 2, {
+      const derived$ = derived(({ read }) => read(asyncValue$) * 2, {
         fallback: 0,
       });
 
@@ -75,23 +75,23 @@ describe("derived", () => {
 
     it("should return resolved value for sync computation", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+      const doubled$ = derived(({ read }) => read(count$) * 2, { fallback: 0 });
 
       // Sync computation resolves immediately
-      await doubled$.value;
+      await doubled$.get();
       expect(doubled$.staleValue).toBe(10);
     });
 
     it("should update staleValue after resolution", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+      const doubled$ = derived(({ read }) => read(count$) * 2, { fallback: 0 });
 
-      await doubled$.value;
+      await doubled$.get();
       expect(doubled$.staleValue).toBe(10);
 
       count$.set(20);
       // After recomputation
-      await doubled$.value;
+      await doubled$.get();
       expect(doubled$.staleValue).toBe(40);
     });
   });
@@ -99,7 +99,7 @@ describe("derived", () => {
   describe("state", () => {
     it("should return loading status during loading", async () => {
       const asyncValue$ = atom(new Promise<number>(() => {})); // Never resolves
-      const doubled$ = derived(({ get }) => get(asyncValue$) * 2);
+      const doubled$ = derived(({ read }) => read(asyncValue$) * 2);
 
       const state = doubled$.state();
       expect(state.status).toBe("loading");
@@ -107,7 +107,7 @@ describe("derived", () => {
 
     it("should return loading status with fallback during loading", async () => {
       const asyncValue$ = atom(new Promise<number>(() => {})); // Never resolves
-      const doubled$ = derived(({ get }) => get(asyncValue$) * 2, {
+      const doubled$ = derived(({ read }) => read(asyncValue$) * 2, {
         fallback: 0,
       });
 
@@ -119,10 +119,10 @@ describe("derived", () => {
 
     it("should return ready status after resolved", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+      const doubled$ = derived(({ read }) => read(count$) * 2, { fallback: 0 });
 
       // Sync computation resolves immediately
-      await doubled$.value;
+      await doubled$.get();
 
       const state = doubled$.state();
       expect(state.status).toBe("ready");
@@ -134,16 +134,16 @@ describe("derived", () => {
     it("should return error status on error", async () => {
       const error = new Error("Test error");
       const count$ = atom(5);
-      const willThrow$ = derived(({ get }) => {
-        if (get(count$) > 3) {
+      const willThrow$ = derived(({ read }) => {
+        if (read(count$) > 3) {
           throw error;
         }
-        return get(count$);
+        return read(count$);
       });
 
       // Wait for computation to complete
       try {
-        await willThrow$.value;
+        await willThrow$.get();
       } catch {
         // Expected to throw
       }
@@ -162,7 +162,7 @@ describe("derived", () => {
           resolvePromise = resolve;
         })
       );
-      const doubled$ = derived(({ get }) => get(asyncValue$) * 2, {
+      const doubled$ = derived(({ read }) => read(asyncValue$) * 2, {
         fallback: 0,
       });
 
@@ -172,7 +172,7 @@ describe("derived", () => {
 
       // Resolve the promise
       resolvePromise!(5);
-      await doubled$.value;
+      await doubled$.get();
 
       // Now ready
       const state = doubled$.state();
@@ -188,17 +188,17 @@ describe("derived", () => {
     it("should re-run computation on refresh", async () => {
       let callCount = 0;
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => {
+      const doubled$ = derived(({ read }) => {
         callCount++;
-        return get(count$) * 2;
+        return read(count$) * 2;
       });
 
-      await doubled$.value;
+      await doubled$.get();
       expect(callCount).toBeGreaterThanOrEqual(1);
 
       const countBefore = callCount;
       doubled$.refresh();
-      await doubled$.value;
+      await doubled$.get();
       expect(callCount).toBeGreaterThan(countBefore);
     });
   });
@@ -206,29 +206,29 @@ describe("derived", () => {
   describe("subscriptions", () => {
     it("should notify subscribers when derived value changes", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
       const listener = vi.fn();
 
-      await doubled$.value; // Initialize
+      await doubled$.get(); // Initialize
       doubled$.on(listener);
 
       count$.set(10);
-      await doubled$.value; // Wait for recomputation
+      await doubled$.get(); // Wait for recomputation
 
       expect(listener).toHaveBeenCalled();
     });
 
     it("should not notify if derived value is the same", async () => {
       const count$ = atom(5);
-      const clamped$ = derived(({ get }) => Math.min(get(count$), 10));
+      const clamped$ = derived(({ read }) => Math.min(read(count$), 10));
       const listener = vi.fn();
 
-      await clamped$.value;
+      await clamped$.get();
       clamped$.on(listener);
 
       // Value is already clamped to 10
       count$.set(15); // Still clamps to 10
-      await clamped$.value;
+      await clamped$.get();
 
       // Should still notify because we can't detect same output without full tracking
       // This depends on implementation - adjust expectation as needed
@@ -236,20 +236,20 @@ describe("derived", () => {
 
     it("should allow unsubscribing", async () => {
       const count$ = atom(5);
-      const doubled$ = derived(({ get }) => get(count$) * 2);
+      const doubled$ = derived(({ read }) => read(count$) * 2);
       const listener = vi.fn();
 
-      await doubled$.value;
+      await doubled$.get();
       const unsub = doubled$.on(listener);
 
       count$.set(10);
-      await doubled$.value;
+      await doubled$.get();
       const callCount = listener.mock.calls.length;
 
       unsub();
 
       count$.set(20);
-      await doubled$.value;
+      await doubled$.get();
 
       // Should not receive more calls after unsubscribe
       expect(listener.mock.calls.length).toBe(callCount);
@@ -262,38 +262,38 @@ describe("derived", () => {
       const summary$ = atom("Brief");
       const details$ = atom("Detailed");
 
-      const content$ = derived(({ get }) =>
-        get(showDetails$) ? get(details$) : get(summary$)
+      const content$ = derived(({ read }) =>
+        read(showDetails$) ? read(details$) : read(summary$)
       );
 
       const listener = vi.fn();
-      await content$.value;
+      await content$.get();
       content$.on(listener);
 
       // Initially showing summary, so details changes shouldn't trigger
       // (This depends on implementation - conditional deps may or may not
       // unsubscribe from unaccessed atoms)
 
-      expect(await content$.value).toBe("Brief");
+      expect(await content$.get()).toBe("Brief");
 
       showDetails$.set(true);
-      expect(await content$.value).toBe("Detailed");
+      expect(await content$.get()).toBe("Detailed");
     });
   });
 
   describe("async dependencies", () => {
     it("should handle atoms storing Promises", async () => {
       const asyncValue$ = atom(Promise.resolve(42));
-      const doubled$ = derived(({ get }) => {
-        const value = get(asyncValue$);
-        // At this point, get() will throw the Promise if pending
+      const doubled$ = derived(({ read }) => {
+        const value = read(asyncValue$);
+        // At this point, read() will throw the Promise if pending
         // which is handled by derived's internal retry mechanism
         return value;
       });
 
       // The derived computation handles the async dependency
       // This test verifies the basic wiring works
-      await doubled$.value;
+      await doubled$.get();
       // Result depends on how promiseCache tracks the Promise
       expect(true).toBe(true); // Test passes if no error thrown
     });
@@ -302,17 +302,17 @@ describe("derived", () => {
   describe("error handling", () => {
     it("should propagate errors from computation", async () => {
       const count$ = atom(5);
-      const willThrow$ = derived(({ get }) => {
-        if (get(count$) > 10) {
+      const willThrow$ = derived(({ read }) => {
+        if (read(count$) > 10) {
           throw new Error("Value too high");
         }
-        return get(count$);
+        return read(count$);
       });
 
-      expect(await willThrow$.value).toBe(5);
+      expect(await willThrow$.get()).toBe(5);
 
       count$.set(15);
-      await expect(willThrow$.value).rejects.toThrow("Value too high");
+      await expect(willThrow$.get()).rejects.toThrow("Value too high");
     });
   });
 
@@ -323,38 +323,38 @@ describe("derived", () => {
       const c$ = atom(3);
 
       const sum$ = derived(({ all }) => {
-        const [a, b, c] = all(a$, b$, c$);
+        const [a, b, c] = all([a$, b$, c$]);
         return a + b + c;
       });
 
-      expect(await sum$.value).toBe(6);
+      expect(await sum$.get()).toBe(6);
     });
 
-    it("should support get() chaining", async () => {
+    it("should support read() chaining", async () => {
       const a$ = atom(2);
       const b$ = atom(3);
 
-      const result$ = derived(({ get }) => {
-        const a = get(a$);
-        const b = get(b$);
+      const result$ = derived(({ read }) => {
+        const a = read(a$);
+        const b = read(b$);
         return a * b;
       });
 
-      expect(await result$.value).toBe(6);
+      expect(await result$.get()).toBe(6);
     });
   });
 
   describe("equality options", () => {
     it("should use strict equality by default", async () => {
       const source$ = atom({ a: 1 });
-      const derived$ = derived(({ get }) => ({ ...get(source$) }));
+      const derived$ = derived(({ read }) => ({ ...read(source$) }));
       const listener = vi.fn();
 
-      await derived$.value;
+      await derived$.get();
       derived$.on(listener);
 
       source$.set({ a: 1 }); // Same content, different reference
-      await derived$.value;
+      await derived$.get();
 
       // With strict equality on derived output, listener should be called
       // because we return a new object each time
@@ -363,19 +363,674 @@ describe("derived", () => {
 
     it("should support shallow equality option", async () => {
       const source$ = atom({ a: 1 });
-      const derived$ = derived(({ get }) => ({ ...get(source$) }), {
+      const derived$ = derived(({ read }) => ({ ...read(source$) }), {
         equals: "shallow",
       });
       const listener = vi.fn();
 
-      await derived$.value;
+      await derived$.get();
       derived$.on(listener);
 
       source$.set({ a: 1 }); // Same content
-      await derived$.value;
+      await derived$.get();
 
       // With shallow equality, same content should not notify
       // (depends on whether source triggers derived recomputation)
     });
   });
+
+  describe("bug fixes", () => {
+    describe("notify on loading state (Bug #1)", () => {
+      it("should notify downstream derived atoms when entering loading state", async () => {
+        // Bug: When a derived atom's dependency starts loading,
+        // it didn't notify subscribers, causing downstream atoms
+        // and useSelector to not suspend properly
+        let resolveFirst: (value: number) => void;
+        const firstPromise = new Promise<number>((r) => {
+          resolveFirst = r;
+        });
+        const base$ = atom(firstPromise);
+
+        // Create a chain: base$ -> derived1$ -> derived2$
+        const derived1$ = derived(({ read }) => read(base$) * 2);
+        const derived2$ = derived(({ read }) => read(derived1$) + 1);
+
+        const listener = vi.fn();
+        derived2$.on(listener);
+
+        // Initially loading
+        expect(derived2$.state().status).toBe("loading");
+
+        // Resolve and trigger recompute
+        resolveFirst!(5);
+        await derived2$.get();
+
+        expect(derived2$.state().status).toBe("ready");
+        // Listener should have been called when state changed
+        expect(listener).toHaveBeenCalled();
+      });
+
+      it("should propagate loading state through derived chain", async () => {
+        let resolvePromise: (value: number) => void;
+        const asyncAtom$ = atom(
+          new Promise<number>((r) => {
+            resolvePromise = r;
+          })
+        );
+
+        const level1$ = derived(({ read }) => read(asyncAtom$) * 2);
+        const level2$ = derived(({ read }) => read(level1$) + 10);
+        const level3$ = derived(({ read }) => read(level2$) * 3);
+
+        // All should be loading
+        expect(level1$.state().status).toBe("loading");
+        expect(level2$.state().status).toBe("loading");
+        expect(level3$.state().status).toBe("loading");
+
+        // Resolve
+        resolvePromise!(5);
+        await level3$.get();
+
+        // All should be ready with correct values
+        expect(level1$.state().status).toBe("ready");
+        expect(level2$.state().status).toBe("ready");
+        expect(level3$.state().status).toBe("ready");
+        expect(await level3$.get()).toBe((5 * 2 + 10) * 3); // 60
+      });
+    });
+
+    describe("no orphaned promises (Bug #2)", () => {
+      it("should not create orphaned promises when already loading", async () => {
+        // Bug: When compute() was called while already loading,
+        // it created a new Promise, orphaning the one React was waiting on
+        let resolvePromise: (value: number) => void;
+        const asyncAtom$ = atom(
+          new Promise<number>((r) => {
+            resolvePromise = r;
+          })
+        );
+
+        const derived$ = derived(({ read }) => read(asyncAtom$) * 2);
+
+        // Get the promise that would be thrown for Suspense
+        const state1 = derived$.state();
+        expect(state1.status).toBe("loading");
+        const promise1 = state1.status === "loading" ? state1.promise : null;
+
+        // Trigger another computation while still loading
+        derived$.refresh();
+
+        // Should return the SAME promise (not orphan the first one)
+        const state2 = derived$.state();
+        expect(state2.status).toBe("loading");
+        const promise2 = state2.status === "loading" ? state2.promise : null;
+
+        expect(promise1).toBe(promise2);
+
+        // Resolve and verify completion
+        resolvePromise!(21);
+        const result = await derived$.get();
+        expect(result).toBe(42);
+      });
+
+      it("should complete properly when dependency changes during loading", async () => {
+        let resolveFirst: (value: number) => void;
+        const firstPromise = new Promise<number>((r) => {
+          resolveFirst = r;
+        });
+
+        const base$ = atom(firstPromise);
+        const derived$ = derived(({ read }) => read(base$) * 2);
+
+        // Start loading
+        expect(derived$.state().status).toBe("loading");
+
+        // Simulate setting a new promise (like refetch)
+        let resolveSecond: (value: number) => void;
+        const secondPromise = new Promise<number>((r) => {
+          resolveSecond = r;
+        });
+        base$.set(secondPromise);
+
+        // The derived atom's existing computation is waiting on firstPromise
+        // When firstPromise resolves, it will retry and pick up secondPromise
+        // So we need to resolve BOTH promises
+
+        // Resolve first to trigger retry
+        resolveFirst!(5);
+
+        // Wait a tick for retry to happen
+        await new Promise((r) => setTimeout(r, 0));
+
+        // Now resolve the second promise
+        resolveSecond!(10);
+
+        // Should eventually resolve with the second value
+        const result = await derived$.get();
+        expect(result).toBe(20);
+      });
+    });
+
+    describe("notify on first resolve even when silent (Bug #3)", () => {
+      it("should notify subscribers when transitioning from loading to ready", async () => {
+        // Bug: When derived atoms were initialized with silent=true,
+        // they never called notify() even after promise resolved
+        let resolvePromise: (value: number) => void;
+        const asyncAtom$ = atom(
+          new Promise<number>((r) => {
+            resolvePromise = r;
+          })
+        );
+
+        const derived$ = derived(({ read }) => read(asyncAtom$) * 2);
+        const listener = vi.fn();
+
+        // Subscribe before resolution
+        derived$.on(listener);
+        expect(derived$.state().status).toBe("loading");
+
+        // Resolve the promise
+        resolvePromise!(5);
+        await derived$.get();
+
+        // Listener MUST be called when transitioning loading → ready
+        expect(listener).toHaveBeenCalled();
+        expect(derived$.state().status).toBe("ready");
+      });
+
+      it("should notify subscribers when transitioning from loading to error", async () => {
+        let rejectPromise: (error: Error) => void;
+        const asyncAtom$ = atom(
+          new Promise<number>((_, reject) => {
+            rejectPromise = reject;
+          })
+        );
+
+        const derived$ = derived(({ read }) => read(asyncAtom$) * 2);
+        const listener = vi.fn();
+
+        // Subscribe before rejection
+        derived$.on(listener);
+        expect(derived$.state().status).toBe("loading");
+
+        // Reject the promise
+        rejectPromise!(new Error("Test error"));
+
+        // Wait for rejection to be processed
+        try {
+          await derived$.get();
+        } catch {
+          // Expected
+        }
+
+        // Listener MUST be called when transitioning loading → error
+        expect(listener).toHaveBeenCalled();
+        expect(derived$.state().status).toBe("error");
+      });
+
+      it("should update state() correctly after async resolution", async () => {
+        // This tests the demo scenario where atoms show "Loading" forever
+        let resolvePromise: (value: number) => void;
+        const asyncAtom$ = atom(
+          new Promise<number>((r) => {
+            resolvePromise = r;
+          })
+        );
+
+        // Wrapper derived (like in the Async Utils demo)
+        const wrapper$ = derived(({ read }) => read(asyncAtom$));
+
+        // Initially loading
+        const initialState = wrapper$.state();
+        expect(initialState.status).toBe("loading");
+
+        // Resolve
+        resolvePromise!(42);
+        await wrapper$.get();
+
+        // State MUST reflect the resolved value
+        const finalState = wrapper$.state();
+        expect(finalState.status).toBe("ready");
+        if (finalState.status === "ready") {
+          expect(finalState.value).toBe(42);
+        }
+      });
+
+      it("should work with multiple wrapper derived atoms", async () => {
+        // Simulates the Async Utils demo with multiple atoms
+        const createAsyncAtom = (delayMs: number, value: number) => {
+          return atom(
+            new Promise<number>((resolve) => {
+              setTimeout(() => resolve(value), delayMs);
+            })
+          );
+        };
+
+        const atom1$ = createAsyncAtom(10, 1);
+        const atom2$ = createAsyncAtom(20, 2);
+        const atom3$ = createAsyncAtom(30, 3);
+
+        const wrapper1$ = derived(({ read }) => read(atom1$));
+        const wrapper2$ = derived(({ read }) => read(atom2$));
+        const wrapper3$ = derived(({ read }) => read(atom3$));
+
+        const listener1 = vi.fn();
+        const listener2 = vi.fn();
+        const listener3 = vi.fn();
+
+        wrapper1$.on(listener1);
+        wrapper2$.on(listener2);
+        wrapper3$.on(listener3);
+
+        // Wait for all to resolve
+        await Promise.all([wrapper1$.get(), wrapper2$.get(), wrapper3$.get()]);
+
+        // All listeners should have been called
+        expect(listener1).toHaveBeenCalled();
+        expect(listener2).toHaveBeenCalled();
+        expect(listener3).toHaveBeenCalled();
+
+        // All states should be ready
+        expect(wrapper1$.state().status).toBe("ready");
+        expect(wrapper2$.state().status).toBe("ready");
+        expect(wrapper3$.state().status).toBe("ready");
+      });
+    });
+  });
+
+  describe("ready() - reactive suspension", () => {
+    describe("basic functionality", () => {
+      it("should return non-null value immediately", async () => {
+        const id$ = atom("article-123");
+        const derived$ = derived(({ ready }) => {
+          const id = ready(id$);
+          return `loaded: ${id}`;
+        });
+
+        expect(await derived$.get()).toBe("loaded: article-123");
+      });
+
+      it("should suspend when value is null", async () => {
+        const id$ = atom<string | null>(null);
+        const derived$ = derived(({ ready }) => {
+          const id = ready(id$);
+          return `loaded: ${id}`;
+        });
+
+        // Should be in loading state (suspended)
+        expect(derived$.state().status).toBe("loading");
+      });
+
+      it("should suspend when value is undefined", async () => {
+        const id$ = atom<string | undefined>(undefined);
+        const derived$ = derived(({ ready }) => {
+          const id = ready(id$);
+          return `loaded: ${id}`;
+        });
+
+        expect(derived$.state().status).toBe("loading");
+      });
+
+      it("should NOT suspend for falsy but valid values (0, false, empty string)", async () => {
+        const zero$ = atom(0);
+        const false$ = atom(false);
+        const empty$ = atom("");
+
+        const zeroResult$ = derived(({ ready }) => ready(zero$));
+        const falseResult$ = derived(({ ready }) => ready(false$));
+        const emptyResult$ = derived(({ ready }) => ready(empty$));
+
+        expect(await zeroResult$.get()).toBe(0);
+        expect(await falseResult$.get()).toBe(false);
+        expect(await emptyResult$.get()).toBe("");
+      });
+    });
+
+    describe("reactive resumption", () => {
+      it("should resume when null value becomes non-null", async () => {
+        const id$ = atom<string | null>(null);
+        const computeCount = vi.fn();
+
+        const derived$ = derived(({ ready }) => {
+          computeCount();
+          const id = ready(id$);
+          return `loaded: ${id}`;
+        });
+
+        // Initially suspended
+        expect(derived$.state().status).toBe("loading");
+
+        // Set non-null value - should trigger recomputation
+        id$.set("article-123");
+
+        // Wait for recomputation
+        const result = await derived$.get();
+
+        expect(result).toBe("loaded: article-123");
+        expect(derived$.state().status).toBe("ready");
+        // Should have computed at least twice (once null, once with value)
+        expect(computeCount).toHaveBeenCalled();
+      });
+
+      it("should resume and compute with new value when dependency changes", async () => {
+        const id$ = atom<string | null>(null);
+        const derived$ = derived(({ ready }) => {
+          const id = ready(id$);
+          return id.toUpperCase();
+        });
+
+        // Set to first value
+        id$.set("hello");
+        expect(await derived$.get()).toBe("HELLO");
+
+        // Change to another value
+        id$.set("world");
+        expect(await derived$.get()).toBe("WORLD");
+
+        // Set back to null - should suspend again
+        id$.set(null);
+        expect(derived$.state().status).toBe("loading");
+
+        // Set to new value - should resume
+        id$.set("test");
+        expect(await derived$.get()).toBe("TEST");
+      });
+    });
+
+    describe("ready() with selector", () => {
+      it("should extract and return non-null property", async () => {
+        const user$ = atom({ id: 1, name: "John" });
+
+        const derived$ = derived(({ ready }) => {
+          const name = ready(user$, (u) => u.name);
+          return `Hello, ${name}!`;
+        });
+
+        expect(await derived$.get()).toBe("Hello, John!");
+      });
+
+      it("should suspend when selector returns null", async () => {
+        const user$ = atom<{ id: number; email: string | null }>({
+          id: 1,
+          email: null,
+        });
+
+        const derived$ = derived(({ ready }) => {
+          const email = ready(user$, (u) => u.email);
+          return `Email: ${email}`;
+        });
+
+        expect(derived$.state().status).toBe("loading");
+      });
+
+      it("should resume when selector result becomes non-null", async () => {
+        const user$ = atom<{ id: number; email: string | null }>({
+          id: 1,
+          email: null,
+        });
+
+        const derived$ = derived(({ ready }) => {
+          const email = ready(user$, (u) => u.email);
+          return `Email: ${email}`;
+        });
+
+        // Initially suspended
+        expect(derived$.state().status).toBe("loading");
+
+        // Update user with email
+        user$.set({ id: 1, email: "john@example.com" });
+
+        expect(await derived$.get()).toBe("Email: john@example.com");
+      });
+
+      it("should suspend when selector returns undefined", async () => {
+        const data$ = atom<{ value?: number }>({});
+
+        const derived$ = derived(({ ready }) => {
+          const value = ready(data$, (d) => d.value);
+          return value * 2;
+        });
+
+        expect(derived$.state().status).toBe("loading");
+
+        // Set the value
+        data$.set({ value: 21 });
+        expect(await derived$.get()).toBe(42);
+      });
+    });
+
+    describe("multiple ready() calls", () => {
+      it("should suspend until all ready() calls have non-null values", async () => {
+        const firstName$ = atom<string | null>(null);
+        const lastName$ = atom<string | null>(null);
+
+        const derived$ = derived(({ ready }) => {
+          const first = ready(firstName$);
+          const last = ready(lastName$);
+          return `${first} ${last}`;
+        });
+
+        // Both null - suspended
+        expect(derived$.state().status).toBe("loading");
+
+        // Set first name only - still suspended (lastName is null)
+        firstName$.set("John");
+        // Need to wait a tick for recomputation
+        await new Promise((r) => setTimeout(r, 0));
+        expect(derived$.state().status).toBe("loading");
+
+        // Set last name - should resolve
+        lastName$.set("Doe");
+        expect(await derived$.get()).toBe("John Doe");
+      });
+
+      it("should track all atoms from ready() calls as dependencies", async () => {
+        const a$ = atom<number | null>(null);
+        const b$ = atom<number | null>(null);
+        const listener = vi.fn();
+
+        const derived$ = derived(({ ready }) => {
+          const a = ready(a$);
+          const b = ready(b$);
+          return a + b;
+        });
+
+        derived$.on(listener);
+
+        // Set both values
+        a$.set(1);
+        b$.set(2);
+        await derived$.get();
+
+        // Should have been notified when resolved
+        expect(listener).toHaveBeenCalled();
+        expect(await derived$.get()).toBe(3);
+
+        // Clear listener calls
+        listener.mockClear();
+
+        // Change one value - should trigger recomputation
+        a$.set(10);
+        await derived$.get();
+        expect(listener).toHaveBeenCalled();
+        expect(await derived$.get()).toBe(12);
+      });
+    });
+
+    describe("combining ready() with read()", () => {
+      it("should allow mixing ready() and read() in same derived", async () => {
+        const requiredId$ = atom<string | null>(null);
+        const optionalName$ = atom("default");
+
+        const derived$ = derived(({ ready, read }) => {
+          const id = ready(requiredId$);
+          const name = read(optionalName$);
+          return { id, name };
+        });
+
+        // Suspended because requiredId is null
+        expect(derived$.state().status).toBe("loading");
+
+        // Set required value
+        requiredId$.set("123");
+        expect(await derived$.get()).toEqual({ id: "123", name: "default" });
+
+        // Change optional value
+        optionalName$.set("custom");
+        expect(await derived$.get()).toEqual({ id: "123", name: "custom" });
+      });
+
+      it("should suspend on ready() even if read() would succeed", async () => {
+        const readValue$ = atom(42);
+        const readyValue$ = atom<number | null>(null);
+
+        const derived$ = derived(({ ready, read }) => {
+          const readResult = read(readValue$);
+          const readyResult = ready(readyValue$);
+          return readResult + readyResult;
+        });
+
+        expect(derived$.state().status).toBe("loading");
+
+        readyValue$.set(8);
+        expect(await derived$.get()).toBe(50);
+      });
+    });
+
+    describe("real-world use case: current entity loading", () => {
+      it("should handle route-based entity loading pattern", async () => {
+        // Simulates /article/:id route pattern
+        const currentArticleId$ = atom<string | null>(null);
+
+        // Article cache
+        const articleCache$ = atom<Record<string, { title: string }>>({});
+
+        // Current article derived - waits for ID to be set
+        const currentArticle$ = derived(({ ready, read }) => {
+          const id = ready(currentArticleId$);
+          const cache = read(articleCache$);
+          return cache[id] ?? { title: "Not found" };
+        });
+
+        // Initially suspended (no article selected)
+        expect(currentArticle$.state().status).toBe("loading");
+
+        // User navigates to /article/123
+        currentArticleId$.set("123");
+        articleCache$.set({ "123": { title: "Hello World" } });
+
+        expect(await currentArticle$.get()).toEqual({ title: "Hello World" });
+
+        // User navigates away (deselects article)
+        currentArticleId$.set(null);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(currentArticle$.state().status).toBe("loading");
+
+        // User navigates to /article/456
+        articleCache$.set({
+          "123": { title: "Hello World" },
+          "456": { title: "Another Article" },
+        });
+        currentArticleId$.set("456");
+
+        expect(await currentArticle$.get()).toEqual({
+          title: "Another Article",
+        });
+      });
+
+      it("should handle authentication-gated content", async () => {
+        const currentUser$ = atom<{ id: string; name: string } | null>(null);
+
+        const userDashboard$ = derived(({ ready }) => {
+          const user = ready(currentUser$);
+          return {
+            greeting: `Welcome back, ${user.name}!`,
+            userId: user.id,
+          };
+        });
+
+        // Not logged in - suspended
+        expect(userDashboard$.state().status).toBe("loading");
+
+        // User logs in
+        currentUser$.set({ id: "u1", name: "Alice" });
+
+        expect(await userDashboard$.get()).toEqual({
+          greeting: "Welcome back, Alice!",
+          userId: "u1",
+        });
+
+        // User logs out
+        currentUser$.set(null);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(userDashboard$.state().status).toBe("loading");
+      });
+    });
+
+    describe("error handling", () => {
+      it("should propagate errors thrown after ready() succeeds", async () => {
+        const value$ = atom<number | null>(10);
+
+        const derived$ = derived(({ ready }) => {
+          const value = ready(value$);
+          if (value > 5) {
+            throw new Error("Value too high");
+          }
+          return value;
+        });
+
+        await expect(derived$.get()).rejects.toThrow("Value too high");
+        expect(derived$.state().status).toBe("error");
+      });
+
+      it("should recover from error when value changes to valid", async () => {
+        const value$ = atom<number | null>(10);
+
+        const derived$ = derived(({ ready }) => {
+          const value = ready(value$);
+          if (value > 5) {
+            throw new Error("Value too high");
+          }
+          return value * 2;
+        });
+
+        // First: error
+        await expect(derived$.get()).rejects.toThrow();
+
+        // Change to valid value
+        value$.set(3);
+        expect(await derived$.get()).toBe(6);
+      });
+    });
+
+    describe("with async dependencies", () => {
+      it("should wait for async atom AND ready() condition", async () => {
+        let resolveAsync: (value: number) => void;
+        const asyncValue$ = atom(
+          new Promise<number>((r) => {
+            resolveAsync = r;
+          })
+        );
+        const readyValue$ = atom<string | null>(null);
+
+        const derived$ = derived(({ read, ready }) => {
+          const asyncVal = read(asyncValue$);
+          const readyVal = ready(readyValue$);
+          return `${asyncVal}-${readyVal}`;
+        });
+
+        // Both loading/null - suspended
+        expect(derived$.state().status).toBe("loading");
+
+        // Resolve async - still suspended (ready is null)
+        resolveAsync!(42);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(derived$.state().status).toBe("loading");
+
+        // Set ready value - should resolve
+        readyValue$.set("test");
+        expect(await derived$.get()).toBe("42-test");
+      });
+    });
+  });
 });