atomirx 0.0.1 → 0.0.4

package/src/core/types.ts

@@ -28,8 +28,8 @@ export const SYMBOL_DERIVED = Symbol.for("atomirx.derived");
  * @example
  * ```ts
  * const enhanced = atom(0)
- *   .use(source => ({ ...source, double: () => source.value * 2 }))
- *   .use(source => ({ ...source, triple: () => source.value * 3 }));
+ *   .use(source => ({ ...source, double: () => source.get() * 2 }))
+ *   .use(source => ({ ...source, triple: () => source.get() * 3 }));
  * ```
  */
 export interface Pipeable {
@@ -61,10 +61,13 @@ export interface AtomMeta {
 export interface Atom<T> {
   /** Symbol marker to identify atom instances */
   readonly [SYMBOL_ATOM]: true;
-  /** The current value */
-  readonly value: T;
+
   /** Optional metadata for the atom */
   readonly meta?: AtomMeta;
+
+  /** Get the current value */
+  get(): T;
+
   /**
    * Subscribe to value changes.
    * @param listener - Callback invoked when value changes
@@ -91,7 +94,7 @@ export interface Atom<T> {
  *
  * // Async value (stores Promise as-is)
  * const posts = atom(fetchPosts());
- * posts.value; // Promise<Post[]>
+ * posts.get(); // Promise<Post[]>
  * posts.set(fetchPosts()); // Store new Promise
  * ```
  */
@@ -132,7 +135,7 @@ export interface MutableAtom<T> extends Atom<T>, Pipeable {
  * A derived (computed) atom that always returns Promise<T> for its value.
  *
  * DerivedAtom computes its value from other atoms. The computation is
- * re-run whenever dependencies change. The `.value` always returns a Promise,
+ * re-run whenever dependencies change. The `.get()` always returns a Promise,
  * even for synchronous computations.
  *
  * @template T - The resolved type of the computed value
@@ -141,13 +144,13 @@ export interface MutableAtom<T> extends Atom<T>, Pipeable {
  * @example
  * ```ts
  * // Without fallback
- * const double$ = derived(({ get }) => get(count$) * 2);
- * await double$.value; // number
+ * const double$ = derived(({ read }) => read(count$) * 2);
+ * await double$.get(); // number
  * double$.staleValue;  // number | undefined
  * double$.state();     // { status: "ready", value: 10 }
  *
  * // With fallback - during loading
- * const double$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+ * const double$ = derived(({ read }) => read(count$) * 2, { fallback: 0 });
  * double$.staleValue;  // number (guaranteed)
  * double$.state();     // { status: "loading", promise } during loading
  * ```
@@ -199,9 +202,48 @@ export type AtomValue<A> =
  * @template T - The type of the atom's value
  */
 export type AtomState<T> =
-  | { status: "ready"; value: T }
-  | { status: "error"; error: unknown }
-  | { status: "loading"; promise: Promise<T> };
+  | { status: "ready"; value: T; error?: undefined; promise?: undefined }
+  | { status: "error"; error: unknown; value?: undefined; promise?: undefined }
+  | {
+      status: "loading";
+      promise: Promise<T>;
+      value?: undefined;
+      error?: undefined;
+    };
+
+/**
+ * Result type for SelectContext.state() - simplified AtomState without promise.
+ *
+ * All properties (`status`, `value`, `error`) are always present:
+ * - `value` is `T` when ready, `undefined` otherwise
+ * - `error` is the error when errored, `undefined` otherwise
+ *
+ * This enables easy destructuring without type narrowing:
+ * ```ts
+ * const { status, value, error } = state(atom$);
+ * ```
+ *
+ * Equality comparisons work correctly (no promise reference issues).
+ */
+export type SelectStateResult<T> =
+  | { status: "ready"; value: T; error: undefined }
+  | { status: "error"; value: undefined; error: unknown }
+  | { status: "loading"; value: undefined; error: undefined };
+
+/**
+ * Result type for race() and any() - includes winning key.
+ *
+ * @template K - The key type (string literal union)
+ * @template V - The value type
+ */
+export type KeyedResult<K extends string, V> = {
+  /** The key that won the race/any */
+  key: K;
+  /** The resolved value */
+  value: V;
+};
+
+export type AtomPlugin = <T extends Atom<any>>(atom: T) => T | void;
 
 /**
  * Result type for settled operations.
@@ -244,8 +286,6 @@ export interface DerivedOptions<T> {
 export interface EffectOptions {
   /** Optional key for debugging */
   key?: string;
-  /** Error handler for uncaught errors in the effect */
-  onError?: (error: Error) => void;
 }
 
 /**
@@ -297,15 +337,3 @@ export interface ModuleMeta {}
 export type Listener<T> = (value: T) => void;
 
 export type SingleOrMultipleListeners<T> = Listener<T> | Listener<T>[];
-
-/**
- * Type guard to check if a value is an Atom.
- */
-export declare function isAtom<T>(value: unknown): value is Atom<T>;
-
-/**
- * Type guard to check if a value is a DerivedAtom.
- */
-export declare function isDerived<T>(
-  value: unknown
-): value is DerivedAtom<T, boolean>;

package/src/core/withReady.test.ts

@@ -0,0 +1,360 @@
+import { describe, it, expect } from "vitest";
+import { withReady } from "./withReady";
+import { atom } from "./atom";
+import { select } from "./select";
+describe("withReady", () => {
+  describe("basic functionality", () => {
+    it("should add ready method to context", () => {
+      select((context) => {
+        const enhanced = context.use(withReady());
+        expect(typeof enhanced.ready).toBe("function");
+        return null;
+      });
+    });
+
+    it("should preserve original context methods", () => {
+      select((context) => {
+        const enhanced = context.use(withReady());
+        expect(typeof enhanced.read).toBe("function");
+        expect(typeof enhanced.all).toBe("function");
+        expect(typeof enhanced.any).toBe("function");
+        expect(typeof enhanced.race).toBe("function");
+        expect(typeof enhanced.settled).toBe("function");
+        expect(typeof enhanced.safe).toBe("function");
+        expect(typeof enhanced.use).toBe("function");
+        return null;
+      });
+    });
+  });
+
+  describe("ready() with non-null values", () => {
+    it("should return value when atom has non-null value", () => {
+      const count$ = atom(42);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(count$);
+      });
+
+      expect(result.value).toBe(42);
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeUndefined();
+    });
+
+    it("should return value when atom has zero", () => {
+      const count$ = atom(0);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(count$);
+      });
+
+      expect(result.value).toBe(0);
+    });
+
+    it("should return value when atom has empty string", () => {
+      const str$ = atom("");
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(str$);
+      });
+
+      expect(result.value).toBe("");
+    });
+
+    it("should return value when atom has false", () => {
+      const bool$ = atom(false);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(bool$);
+      });
+
+      expect(result.value).toBe(false);
+    });
+
+    it("should return value when atom has object", () => {
+      const obj$ = atom({ name: "test" });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(obj$);
+      });
+
+      expect(result.value).toEqual({ name: "test" });
+    });
+  });
+
+  describe("ready() with null/undefined values", () => {
+    it("should throw never-resolve promise when atom value is null", () => {
+      const nullable$ = atom<string | null>(null);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(nullable$);
+      });
+
+      expect(result.value).toBeUndefined();
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeInstanceOf(Promise);
+    });
+
+    it("should throw never-resolve promise when atom value is undefined", () => {
+      const undefinedAtom$ = atom<string | undefined>(undefined);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(undefinedAtom$);
+      });
+
+      expect(result.value).toBeUndefined();
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeInstanceOf(Promise);
+    });
+  });
+
+  describe("ready() with selector", () => {
+    it("should apply selector and return result when non-null", () => {
+      const user$ = atom({ id: 1, name: "John" });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(user$, (user) => user.name);
+      });
+
+      expect(result.value).toBe("John");
+    });
+
+    it("should throw never-resolve promise when selector returns null", () => {
+      const user$ = atom<{ id: number; email: string | null }>({
+        id: 1,
+        email: null,
+      });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(user$, (user) => user.email);
+      });
+
+      expect(result.value).toBeUndefined();
+      expect(result.promise).toBeInstanceOf(Promise);
+    });
+
+    it("should throw never-resolve promise when selector returns undefined", () => {
+      const data$ = atom<{ value?: string }>({});
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, (data) => data.value);
+      });
+
+      expect(result.value).toBeUndefined();
+      expect(result.promise).toBeInstanceOf(Promise);
+    });
+
+    it("should return zero from selector", () => {
+      const data$ = atom({ count: 0 });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, (data) => data.count);
+      });
+
+      expect(result.value).toBe(0);
+    });
+
+    it("should return empty string from selector", () => {
+      const data$ = atom({ name: "" });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, (data) => data.name);
+      });
+
+      expect(result.value).toBe("");
+    });
+  });
+
+  describe("dependency tracking", () => {
+    it("should track atom as dependency", () => {
+      const count$ = atom(42);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(count$);
+      });
+
+      expect(result.dependencies.has(count$)).toBe(true);
+    });
+
+    it("should track atom as dependency even when throwing promise", () => {
+      const nullable$ = atom<string | null>(null);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(nullable$);
+      });
+
+      expect(result.dependencies.has(nullable$)).toBe(true);
+    });
+  });
+
+  describe("never-resolve promise behavior", () => {
+    it("should return a promise that never resolves", async () => {
+      const nullable$ = atom<string | null>(null);
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(nullable$);
+      });
+
+      // The promise should never resolve
+      // We test this by racing with a timeout
+      const timeoutPromise = new Promise<"timeout">((resolve) =>
+        setTimeout(() => resolve("timeout"), 50)
+      );
+
+      const raceResult = await Promise.race([result.promise, timeoutPromise]);
+      expect(raceResult).toBe("timeout");
+    });
+  });
+
+  describe("ready() with async selector", () => {
+    it("should suspend when selector returns a pending promise", () => {
+      const data$ = atom({ id: 1 });
+      const pendingPromise = new Promise<string>(() => {
+        // Never resolves - stays pending
+      });
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => pendingPromise);
+      });
+
+      // Should suspend with the tracked promise
+      expect(result.value).toBeUndefined();
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeInstanceOf(Promise);
+    });
+
+    it("should return value when selector returns a resolved promise", async () => {
+      const data$ = atom({ id: 1 });
+      const resolvedPromise = Promise.resolve("async result");
+
+      // First call to track the promise and trigger state tracking
+      select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedPromise);
+      });
+
+      // Wait for the promise .then() handlers to run and update cache
+      await resolvedPromise;
+      await new Promise<void>((r) => queueMicrotask(() => r()));
+
+      // Second call - promise should now be fulfilled in cache
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedPromise);
+      });
+
+      expect(result.value).toBe("async result");
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeUndefined();
+    });
+
+    it("should throw error when selector returns a rejected promise", async () => {
+      const data$ = atom({ id: 1 });
+      const testError = new Error("async error");
+      const rejectedPromise = Promise.reject(testError);
+
+      // Prevent unhandled rejection warning
+      rejectedPromise.catch(() => {});
+
+      // First call to track the promise
+      select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => rejectedPromise);
+      });
+
+      // Wait for the promise rejection handlers to run
+      await new Promise<void>((r) => queueMicrotask(() => r()));
+      await new Promise<void>((r) => queueMicrotask(() => r()));
+
+      // Second call - promise should now be rejected in cache
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => rejectedPromise);
+      });
+
+      expect(result.value).toBeUndefined();
+      expect(result.error).toBe(testError);
+      expect(result.promise).toBeUndefined();
+    });
+
+    it("should return null when async selector resolves to null (bypasses null check)", async () => {
+      const data$ = atom({ id: 1 });
+      const resolvedToNull = Promise.resolve(null);
+
+      // First call to track the promise
+      select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedToNull);
+      });
+
+      // Wait for the promise to be tracked as fulfilled
+      await resolvedToNull;
+      await new Promise<void>((r) => queueMicrotask(() => r()));
+
+      // Second call - promise should now be fulfilled in cache
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedToNull);
+      });
+
+      // Async selectors bypass null/undefined checking - value is returned as-is
+      expect(result.value).toBe(null);
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeUndefined();
+    });
+
+    it("should return undefined when async selector resolves to undefined (bypasses undefined check)", async () => {
+      const data$ = atom({ id: 1 });
+      const resolvedToUndefined = Promise.resolve(undefined);
+
+      // First call to track the promise
+      select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedToUndefined);
+      });
+
+      // Wait for the promise to be tracked as fulfilled
+      await resolvedToUndefined;
+      await new Promise<void>((r) => queueMicrotask(() => r()));
+
+      // Second call - promise should now be fulfilled in cache
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => resolvedToUndefined);
+      });
+
+      // Async selectors bypass null/undefined checking - value is returned as-is
+      expect(result.value).toBe(undefined);
+      expect(result.error).toBeUndefined();
+      expect(result.promise).toBeUndefined();
+    });
+
+    it("should track atom as dependency when using async selector", () => {
+      const data$ = atom({ id: 1 });
+      const pendingPromise = new Promise<string>(() => {});
+
+      const result = select((context) => {
+        const ctx = context.use(withReady());
+        return ctx.ready(data$, () => pendingPromise);
+      });
+
+      // Dependency is tracked even when suspending
+      expect(result.dependencies.has(data$)).toBe(true);
+    });
+  });
+});

package/src/core/withReady.ts

@@ -0,0 +1,127 @@
+import { isPromiseLike } from "./isPromiseLike";
+import { trackPromise } from "./promiseCache";
+import { SelectContext } from "./select";
+import { 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>;
+}
+
+/**
+ * Internal helper that suspends computation if value is null/undefined.
+ */
+function waitForValue<T>(value: T): Exclude<T, null | undefined> {
+  if (value === undefined || value === null) {
+    throw new Promise(() => {});
+  }
+  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: (atom: Atom<any>, selector?: (current: any) => any): any => {
+        const value = context.read(atom);
+        // we allow selector to return a promise, and wait for that promise if it is not resolved yet
+        const selected = selector ? selector(value) : value;
+        // Handle async selectors: when the selector returns a Promise,
+        // we track its state and handle suspension/resolution accordingly
+        if (isPromiseLike(selected)) {
+          const p = trackPromise(selected);
+
+          // 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 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);
   });