atomirx 0.0.2 → 0.0.5

package/src/core/withReady.ts

@@ -0,0 +1,191 @@
+import { isPromiseLike } from "./isPromiseLike";
+import { trackPromise } from "./promiseCache";
+import { SelectContext } from "./select";
+import { AnyFunc, Atom } from "./types";
+
+/**
+ * Extension interface that adds `ready()` method to SelectContext.
+ * Used in derived atoms and effects to wait for non-null values.
+ */
+export interface WithReadySelectContext {
+  /**
+   * Wait for an atom to have a non-null/non-undefined value.
+   *
+   * If the value is null/undefined, the computation suspends until the atom
+   * changes to a non-null value, then automatically resumes.
+   *
+   * **IMPORTANT: Only use in `derived()` or `effect()` context**
+   *
+   * @param atom - The atom to read and wait for
+   * @returns The non-null value (type excludes null | undefined)
+   *
+   * @example
+   * ```ts
+   * // Wait for currentArticleId to be set before computing
+   * const currentArticle$ = derived(({ ready, read }) => {
+   *   const id = ready(currentArticleId$); // Suspends if null
+   *   const cache = read(articleCache$);
+   *   return cache[id];
+   * });
+   * ```
+   */
+  ready<T>(
+    atom: Atom<T>
+  ): T extends PromiseLike<any> ? never : Exclude<T, null | undefined>;
+
+  /**
+   * Wait for a selected value from an atom to be non-null/non-undefined.
+   *
+   * If the selected value is null/undefined, the computation suspends until the
+   * selected value changes to a non-null value, then automatically resumes.
+   *
+   * **IMPORTANT: Only use in `derived()` or `effect()` context**
+   *
+   * @param atom - The atom to read
+   * @param selector - Function to extract/transform the value
+   * @returns The non-null selected value
+   *
+   * @example
+   * ```ts
+   * // Wait for user's email to be set
+   * const emailDerived$ = derived(({ ready }) => {
+   *   const email = ready(user$, u => u.email); // Suspends if email is null
+   *   return `Contact: ${email}`;
+   * });
+   * ```
+   */
+  ready<T, R>(
+    atom: Atom<T>,
+    selector: (current: Awaited<T>) => R
+  ): R extends PromiseLike<any> ? never : Exclude<R, null | undefined>;
+
+  /**
+   * Execute a function and wait for its result to be non-null/non-undefined.
+   *
+   * If the function returns null/undefined, the computation suspends until
+   * re-executed with a non-null result.
+   *
+   * **IMPORTANT: Only use in `derived()` or `effect()` context**
+   *
+   * **NOTE:** This overload is designed for use with async combinators like
+   * `all()`, `race()`, `any()`, `settled()` where promises come from stable
+   * atom sources. It does NOT support dynamic promise creation (returning a
+   * new Promise from the callback). For async selectors that return promises,
+   * use `ready(atom$, selector?)` instead.
+   *
+   * @param fn - Synchronous function to execute and wait for
+   * @returns The non-null result (excludes null | undefined)
+   * @throws {Error} If the callback returns a Promise
+   *
+   * @example
+   * ```ts
+   * // Wait for a computed value to be ready
+   * const result$ = derived(({ ready, read }) => {
+   *   const value = ready(() => computeExpensiveValue(read(input$)));
+   *   return `Result: ${value}`;
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Use with async combinators (all, race, any, settled)
+   * const combined$ = derived(({ ready, all }) => {
+   *   const [user, posts] = ready(() => all(user$, posts$));
+   *   return { user, posts };
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // For async selectors, use ready(atom$, selector?) instead:
+   * const data$ = derived(({ ready }) => {
+   *   const data = ready(source$, (val) => fetchData(val.id));
+   *   return data;
+   * });
+   * ```
+   */
+  ready<T>(
+    fn: () => T
+  ): T extends PromiseLike<any> ? never : Exclude<Awaited<T>, null | undefined>;
+}
+
+/**
+ * Internal helper that suspends computation if value is null/undefined.
+ */
+function waitForValue<T>(value: T): any {
+  if (value === undefined || value === null) {
+    throw new Promise(() => {});
+  }
+
+  // Handle async selectors: when the selector returns a Promise,
+  // we track its state and handle suspension/resolution accordingly
+  if (isPromiseLike(value)) {
+    const p = trackPromise(value);
+
+    // Promise is still pending - suspend computation by throwing
+    // the tracked promise. This enables React Suspense integration.
+    if (p.status === "pending") {
+      throw p.promise;
+    }
+
+    // Promise resolved successfully - return the resolved value.
+    // Note: This bypasses null/undefined checking for async results,
+    // allowing async selectors to return any value including null.
+    if (p.status === "fulfilled") {
+      return p.value;
+    }
+
+    // Promise rejected - propagate the error
+    throw p.error;
+  }
+
+  // For sync values (no selector, or selector returned sync value),
+  // check for null/undefined and suspend if not ready
+
+  return value as Exclude<T, null | undefined>;
+}
+
+/**
+ * Plugin that adds `ready()` method to a SelectContext.
+ *
+ * `ready()` enables a "reactive suspension" pattern where derived atoms
+ * wait for required values before computing. This is useful for:
+ *
+ * - Route-based entity loading (`/article/:id` - wait for ID to be set)
+ * - Authentication-gated content (wait for user to be logged in)
+ * - Conditional data dependencies (wait for prerequisite data)
+ *
+ * @example
+ * ```ts
+ * // Used internally by derived() - you don't need to call this directly
+ * const result = select((context) => fn(context.use(withReady())));
+ * ```
+ */
+export function withReady() {
+  return <TContext extends SelectContext>(
+    context: TContext
+  ): TContext & WithReadySelectContext => {
+    return {
+      ...context,
+      ready: (
+        atomOrFn: Atom<any> | AnyFunc,
+        selector?: (current: any) => any
+      ): any => {
+        if (typeof atomOrFn === "function") {
+          const value = atomOrFn();
+          if (isPromiseLike(value)) {
+            throw new Error(
+              "ready(callback) overload does not support async callbacks. Use ready(atom, selector?) instead."
+            );
+          }
+          return waitForValue(value);
+        }
+        const value = context.read(atomOrFn);
+        // we allow selector to return a promise, and wait for that promise if it is not resolved yet
+        const selected = selector ? selector(value) : value;
+
+        return waitForValue(selected);
+      },
+    };
+  };
+}

package/src/core/withUse.ts

@@ -38,7 +38,7 @@ import type { Pipeable } from "./types";
  */
 export function withUse<TSource extends object>(source: TSource) {
   return Object.assign(source, {
-    use<TNew = void>(plugin: (source: TSource) => TNew): any {
+    use<TNew = void>(plugin: (source: NoInfer<TSource>) => TNew): any {
       const result = plugin(source);
       // Void/falsy: return original source (side-effect only plugins)
       if (!result) return source;

package/src/index.test.ts

@@ -17,7 +17,7 @@ describe("atomirx exports", () => {
   it("should export atom", () => {
     expect(typeof atom).toBe("function");
     const count = atom(0);
-    expect(count.value).toBe(0);
+    expect(count.get()).toBe(0);
   });
 
   it("should export batch", () => {
@@ -31,8 +31,8 @@ describe("atomirx exports", () => {
   it("should export derived", async () => {
     expect(typeof derived).toBe("function");
     const count = atom(5);
-    const doubled = derived(({ get }) => get(count) * 2);
-    expect(await doubled.value).toBe(10);
+    const doubled = derived(({ read }) => read(count) * 2);
+    expect(await doubled.get()).toBe(10);
   });
 
   it("should export effect", () => {
@@ -53,7 +53,7 @@ describe("atomirx exports", () => {
   it("should export isDerived", () => {
     expect(typeof isDerived).toBe("function");
     const count = atom(0);
-    const doubled = derived(({ get }) => get(count) * 2);
+    const doubled = derived(({ read }) => read(count) * 2);
     expect(isDerived(count)).toBe(false);
     expect(isDerived(doubled)).toBe(true);
   });

package/src/index.ts

@@ -1,16 +1,16 @@
 // Core
-export { atom } from "./core/atom";
+export { atom, readonly } from "./core/atom";
 export { batch } from "./core/batch";
 export { define } from "./core/define";
-export { derived } from "./core/derived";
-export { effect } from "./core/effect";
+export { derived, type DerivedContext } from "./core/derived";
+export { effect, type EffectContext } from "./core/effect";
 export { emitter } from "./core/emitter";
 export { isAtom, isDerived } from "./core/isAtom";
 export { select, AllAtomsRejectedError } from "./core/select";
 
 // Promise utilities
+export { getAtomState } from "./core/getAtomState";
 export {
-  getAtomState,
   isPending,
   isFulfilled,
   isRejected,
@@ -33,19 +33,33 @@ export type {
   Equality,
   EqualityShorthand,
   Getter,
+  KeyedResult,
   MutableAtom,
   MutableAtomMeta,
   Pipeable,
+  SelectStateResult,
   SettledResult,
 } from "./core/types";
 
 export { onCreateHook } from "./core/onCreateHook";
-export type { AtomCreateInfo, ModuleCreateInfo } from "./core/onCreateHook";
+export type {
+  CreateInfo,
+  MutableInfo,
+  DerivedInfo,
+  EffectInfo,
+  ModuleInfo,
+} from "./core/onCreateHook";
+
+export { onErrorHook } from "./core/onErrorHook";
+export type { ErrorInfo } from "./core/onErrorHook";
 
 export type {
   SelectContext,
   SelectResult,
-  ContextSelectorFn,
+  ReactiveSelector as ContextSelectorFn,
+  SafeResult,
 } from "./core/select";
 
-export type { PromiseState } from "./core/promiseCache";
+export type { PromiseState, CombinedPromiseMeta } from "./core/promiseCache";
+
+export { promisesEqual } from "./core/promiseCache";

package/src/react/index.ts

@@ -1,8 +1,9 @@
-export { useValue } from "./useValue";
+export { useSelector } from "./useSelector";
 export { useStable } from "./useStable";
 export type { UseStableResult } from "./useStable";
 export { useAction } from "./useAction";
 export { rx } from "./rx";
+export type { RxOptions } from "./rx";
 
 export type {
   ActionState,

package/src/react/rx.test.tsx

@@ -24,7 +24,9 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
     it("should render derived value with context selector", () => {
       const count = atom(5);
 
-      render(<div data-testid="result">{rx(({ get }) => get(count) * 2)}</div>);
+      render(
+        <div data-testid="result">{rx(({ read }) => read(count) * 2)}</div>
+      );
 
       expect(screen.getByTestId("result").textContent).toBe("10");
     });
@@ -61,7 +63,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
 
       render(
         <div data-testid="result">
-          {rx(({ get }) => `${get(firstName)} ${get(lastName)}`)}
+          {rx(({ read }) => `${read(firstName)} ${read(lastName)}`)}
         </div>
       );
 
@@ -75,7 +77,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
 
       render(
         <div data-testid="result">
-          {rx(({ get }) => get(a) + get(b) + get(c))}
+          {rx(({ read }) => read(a) + read(b) + read(c))}
         </div>
       );
 
@@ -101,7 +103,9 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
     it("should update when source atom changes (context selector)", () => {
       const count = atom(5);
 
-      render(<div data-testid="result">{rx(({ get }) => get(count) * 2)}</div>);
+      render(
+        <div data-testid="result">{rx(({ read }) => read(count) * 2)}</div>
+      );
 
       expect(screen.getByTestId("result").textContent).toBe("10");
 
@@ -117,7 +121,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const b = atom(2);
 
       render(
-        <div data-testid="result">{rx(({ get }) => get(a) + get(b))}</div>
+        <div data-testid="result">{rx(({ read }) => read(a) + read(b))}</div>
       );
 
       expect(screen.getByTestId("result").textContent).toBe("3");
@@ -142,8 +146,8 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const a = atom(1);
       const b = atom(2);
 
-      const selectorFn = vi.fn(({ get }: SelectContext) =>
-        get(flag) ? get(a) : get(b)
+      const selectorFn = vi.fn(({ read }: SelectContext) =>
+        read(flag) ? read(a) : read(b)
       );
 
       render(<div data-testid="result">{rx(selectorFn)}</div>);
@@ -168,7 +172,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
 
       render(
         <div data-testid="result">
-          {rx(({ get }) => (get(flag) ? get(a) : get(b)))}
+          {rx(({ read }) => (read(flag) ? read(a) : read(b)))}
         </div>
       );
 
@@ -199,7 +203,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
         renderCount.current++;
         return (
           <div data-testid="result">
-            {rx(({ get }) => JSON.stringify(get(user)))}
+            {rx(({ read }) => JSON.stringify(read(user)))}
           </div>
         );
       };
@@ -223,9 +227,9 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const user = atom({ name: "John", age: 30 });
       const selectorCallCount = { current: 0 };
 
-      const selector = ({ get }: SelectContext) => {
+      const selector = ({ read }: SelectContext) => {
         selectorCallCount.current++;
-        return JSON.stringify(get(user));
+        return JSON.stringify(read(user));
       };
 
       render(<div data-testid="result">{rx(selector, "strict")}</div>);
@@ -254,7 +258,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
         return (
           <div data-testid="result">
             {rx(
-              ({ get }) => JSON.stringify(get(user)),
+              ({ read }) => JSON.stringify(read(user)),
               (a, b) => a === b // Compare stringified values
             )}
           </div>
@@ -285,7 +289,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const Parent = () => {
         parentRenderCount.current++;
         return (
-          <div data-testid="result">{rx(({ get }) => get(count) * 2)}</div>
+          <div data-testid="result">{rx(({ read }) => read(count) * 2)}</div>
         );
       };
 
@@ -317,7 +321,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const flag = atom(false);
 
       render(
-        <div data-testid="result">{rx(({ get }) => String(get(flag)))}</div>
+        <div data-testid="result">{rx(({ read }) => String(read(flag)))}</div>
       );
 
       expect(screen.getByTestId("result").textContent).toBe("false");
@@ -352,9 +356,9 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
 
       render(
         <div data-testid="result">
-          {rx(({ get }) => {
+          {rx(({ read }) => {
             try {
-              return get(asyncAtom) * 2;
+              return read(asyncAtom) * 2;
             } catch {
               return "loading";
             }
@@ -372,7 +376,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       const sourceAtom = atom(5);
 
       render(
-        <div data-testid="result">{rx(({ get }) => get(sourceAtom) * 2)}</div>
+        <div data-testid="result">{rx(({ read }) => read(sourceAtom) * 2)}</div>
       );
 
       expect(screen.getByTestId("result").textContent).toBe("10");
@@ -396,7 +400,7 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       render(
         <div data-testid="result">
           {rx(({ all }) => {
-            const [valA, valB] = all(a, b);
+            const [valA, valB] = all([a, b]);
             return valA + valB;
           })}
         </div>
@@ -413,4 +417,155 @@ describe.each(wrappers)("rx - $mode", ({ render }) => {
       expect(screen.getByTestId("result").textContent).toBe("12");
     });
   });
+
+  describe("loading/error options", () => {
+    it("should render loading fallback when atom is pending", () => {
+      const asyncAtom = atom(new Promise<string>(() => {}));
+
+      render(
+        <div data-testid="result">
+          {rx(asyncAtom, { loading: () => <span>Loading...</span> })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("Loading...");
+    });
+
+    it("should render error fallback when atom has error", async () => {
+      const error = new Error("Test error");
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {}); // Prevent unhandled rejection
+      const asyncAtom = atom(rejectedPromise);
+
+      // Wait for promise to be tracked
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      render(
+        <div data-testid="result">
+          {rx(asyncAtom, {
+            error: ({ error: e }) => <span>Error: {(e as Error).message}</span>,
+          })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe(
+        "Error: Test error"
+      );
+    });
+
+    it("should render value when atom resolves with loading option", async () => {
+      let resolve: (value: string) => void;
+      const promise = new Promise<string>((r) => {
+        resolve = r;
+      });
+      const asyncAtom = atom(promise);
+
+      const { rerender } = render(
+        <div data-testid="result">
+          {rx(asyncAtom, {
+            loading: () => <span>Loading...</span>,
+          })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("Loading...");
+
+      await act(async () => {
+        resolve!("Hello");
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      rerender(
+        <div data-testid="result">
+          {rx(asyncAtom, {
+            loading: () => <span>Loading...</span>,
+          })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("Hello");
+    });
+
+    it("should work with selector function and loading option", () => {
+      const asyncAtom = atom(new Promise<number>(() => {}));
+
+      render(
+        <div data-testid="result">
+          {rx(({ read }) => read(asyncAtom) * 2, {
+            loading: () => <span>Computing...</span>,
+          })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("Computing...");
+    });
+
+    it("should support both loading and error options", async () => {
+      const error = new Error("Failed");
+      const rejectedPromise = Promise.reject(error);
+      rejectedPromise.catch(() => {});
+      const asyncAtom = atom(rejectedPromise);
+
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      render(
+        <div data-testid="result">
+          {rx(asyncAtom, {
+            loading: () => <span>Loading...</span>,
+            error: ({ error: e }) => (
+              <span>Failed: {(e as Error).message}</span>
+            ),
+          })}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("Failed: Failed");
+    });
+
+    it("should pass equality in options object", () => {
+      const user = atom({ id: 1, name: "John" });
+      const renderSpy = vi.fn();
+
+      function TestComponent() {
+        renderSpy();
+        return (
+          <div data-testid="result">
+            {rx(({ read }) => read(user).name, {
+              equals: (a, b) => a === b,
+            })}
+          </div>
+        );
+      }
+
+      render(<TestComponent />);
+      expect(screen.getByTestId("result").textContent).toBe("John");
+
+      // Update with same name
+      act(() => {
+        user.set({ id: 2, name: "John" });
+      });
+
+      // Name didn't change, so rx content should be same
+      expect(screen.getByTestId("result").textContent).toBe("John");
+    });
+
+    it("should still work with legacy equality parameter", () => {
+      const count = atom(5);
+
+      render(
+        <div data-testid="result">
+          {rx(({ read }) => read(count) * 2, "strict")}
+        </div>
+      );
+
+      expect(screen.getByTestId("result").textContent).toBe("10");
+    });
+  });
 });