atomirx 0.0.1

package/src/core/promiseCache.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "vitest";
+import {
+  trackPromise,
+  getPromiseState,
+  isTracked,
+  isPending,
+  isFulfilled,
+  isRejected,
+  unwrap,
+  getAtomState,
+  isDerived,
+} from "./promiseCache";
+import { atom } from "./atom";
+import { derived } from "./derived";
+
+describe("promiseCache", () => {
+  describe("trackPromise", () => {
+    it("should return pending state for unresolved promise", () => {
+      const promise = new Promise<number>(() => {});
+      const state = trackPromise(promise);
+      expect(state.status).toBe("pending");
+      expect((state as { promise: PromiseLike<number> }).promise).toBe(promise);
+    });
+
+    it("should return fulfilled state after promise resolves", async () => {
+      const promise = Promise.resolve(42);
+      await promise;
+      trackPromise(promise); // Start tracking
+      // May still be pending if checked immediately, wait a tick
+      await new Promise((r) => setTimeout(r, 0));
+      const state = trackPromise(promise);
+      expect(state.status).toBe("fulfilled");
+      expect((state as { value: number }).value).toBe(42);
+    });
+
+    it("should return rejected state after promise rejects", async () => {
+      const error = new Error("Test error");
+      const promise = Promise.reject(error);
+      promise.catch(() => {}); // Prevent unhandled rejection
+      trackPromise(promise); // Start tracking
+      await Promise.resolve();
+      await Promise.resolve();
+      const state = trackPromise(promise);
+      expect(state.status).toBe("rejected");
+      expect((state as { error: unknown }).error).toBe(error);
+    });
+
+    it("should return same state for same promise", () => {
+      const promise = new Promise<number>(() => {});
+      const state1 = trackPromise(promise);
+      const state2 = trackPromise(promise);
+      expect(state1).toBe(state2);
+    });
+  });
+
+  describe("getPromiseState", () => {
+    it("should return undefined for untracked promise", () => {
+      const promise = new Promise<number>(() => {});
+      expect(getPromiseState(promise)).toBe(undefined);
+    });
+
+    it("should return state for tracked promise", () => {
+      const promise = new Promise<number>(() => {});
+      trackPromise(promise);
+      expect(getPromiseState(promise)).toBeDefined();
+    });
+  });
+
+  describe("isTracked", () => {
+    it("should return false for untracked promise", () => {
+      const promise = new Promise<number>(() => {});
+      expect(isTracked(promise)).toBe(false);
+    });
+
+    it("should return true for tracked promise", () => {
+      const promise = new Promise<number>(() => {});
+      trackPromise(promise);
+      expect(isTracked(promise)).toBe(true);
+    });
+  });
+
+  describe("isPending", () => {
+    it("should return false for non-promise", () => {
+      expect(isPending(42)).toBe(false);
+      expect(isPending("hello")).toBe(false);
+      expect(isPending(null)).toBe(false);
+    });
+
+    it("should return true for pending promise", () => {
+      const promise = new Promise<number>(() => {});
+      expect(isPending(promise)).toBe(true);
+    });
+
+    it("should return false for fulfilled promise", async () => {
+      const promise = Promise.resolve(42);
+      trackPromise(promise); // Start tracking
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(isPending(promise)).toBe(false);
+    });
+  });
+
+  describe("isFulfilled", () => {
+    it("should return false for non-promise", () => {
+      expect(isFulfilled(42)).toBe(false);
+    });
+
+    it("should return true for fulfilled promise", async () => {
+      const promise = Promise.resolve(42);
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(isFulfilled(promise)).toBe(true);
+    });
+
+    it("should return false for pending promise", () => {
+      const promise = new Promise<number>(() => {});
+      expect(isFulfilled(promise)).toBe(false);
+    });
+  });
+
+  describe("isRejected", () => {
+    it("should return false for non-promise", () => {
+      expect(isRejected(42)).toBe(false);
+    });
+
+    it("should return true for rejected promise", async () => {
+      const promise = Promise.reject(new Error("test"));
+      promise.catch(() => {});
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(isRejected(promise)).toBe(true);
+    });
+
+    it("should return false for fulfilled promise", async () => {
+      const promise = Promise.resolve(42);
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(isRejected(promise)).toBe(false);
+    });
+  });
+
+  describe("unwrap", () => {
+    it("should return value for non-promise", () => {
+      expect(unwrap(42)).toBe(42);
+      expect(unwrap("hello")).toBe("hello");
+      expect(unwrap(null)).toBe(null);
+    });
+
+    it("should return value for fulfilled promise", async () => {
+      const promise = Promise.resolve(42);
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(unwrap(promise)).toBe(42);
+    });
+
+    it("should throw promise for pending promise", () => {
+      const promise = new Promise<number>(() => {});
+      let thrown: unknown;
+      try {
+        unwrap(promise);
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown).toBe(promise);
+    });
+
+    it("should throw error for rejected promise", async () => {
+      const error = new Error("Test error");
+      const promise = Promise.reject(error);
+      promise.catch(() => {});
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(() => unwrap(promise)).toThrow(error);
+    });
+  });
+
+  describe("isDerived", () => {
+    it("should return false for mutable atom", () => {
+      const a$ = atom(0);
+      expect(isDerived(a$)).toBe(false);
+    });
+
+    it("should return true for derived atom", () => {
+      const a$ = atom(0);
+      const d$ = derived(({ get }) => get(a$) * 2);
+      expect(isDerived(d$)).toBe(true);
+    });
+
+    it("should return false for non-atom values", () => {
+      expect(isDerived(null)).toBe(false);
+      expect(isDerived(undefined)).toBe(false);
+      expect(isDerived(42)).toBe(false);
+      expect(isDerived({})).toBe(false);
+    });
+  });
+
+  describe("getAtomState", () => {
+    it("should return ready state for sync mutable atom", () => {
+      const a$ = atom(42);
+      const state = getAtomState(a$);
+      expect(state.status).toBe("ready");
+      expect((state as { value: number }).value).toBe(42);
+    });
+
+    it("should return loading state for atom with pending Promise", () => {
+      const promise = new Promise<number>(() => {});
+      const a$ = atom(promise);
+      const state = getAtomState(a$);
+      expect(state.status).toBe("loading");
+    });
+
+    it("should return ready state for atom with resolved Promise", async () => {
+      const promise = Promise.resolve(42);
+      const a$ = atom(promise);
+      trackPromise(promise);
+      await Promise.resolve();
+      await Promise.resolve();
+      const state = getAtomState(a$);
+      expect(state.status).toBe("ready");
+      expect((state as { value: number }).value).toBe(42);
+    });
+
+    it("should return loading state for derived with fallback during loading", async () => {
+      const asyncValue$ = atom(new Promise<number>(() => {}));
+      const derived$ = derived(({ get }) => get(asyncValue$), { fallback: 0 });
+
+      // Derived atoms return their state directly via state()
+      // State is loading, but staleValue provides the fallback
+      const state = getAtomState(derived$);
+      expect(state.status).toBe("loading");
+      expect(derived$.staleValue).toBe(0);
+    });
+  });
+});

package/src/core/promiseCache.ts

@@ -0,0 +1,279 @@
+import { isPromiseLike } from "./isPromiseLike";
+import { Atom, AtomState, DerivedAtom, SYMBOL_DERIVED } from "./types";
+
+/**
+ * Represents the state of a tracked Promise.
+ */
+export type PromiseState<T> =
+  | { status: "pending"; promise: PromiseLike<T> }
+  | { status: "fulfilled"; value: T }
+  | { status: "rejected"; error: unknown };
+
+/**
+ * WeakMap cache for Promise states.
+ * Using WeakMap allows Promises to be garbage collected when no longer referenced.
+ */
+const promiseCache = new WeakMap<PromiseLike<unknown>, PromiseState<unknown>>();
+
+/**
+ * Tracks a Promise and caches its state.
+ * If the Promise is already tracked, returns the existing state.
+ * Otherwise, starts tracking and returns the initial pending state.
+ *
+ * @param promise - The Promise to track
+ * @returns The current state of the Promise
+ *
+ * @example
+ * ```ts
+ * const promise = fetchData();
+ * const state = trackPromise(promise);
+ * // state.status === 'pending'
+ *
+ * await promise;
+ * const state2 = trackPromise(promise);
+ * // state2.status === 'fulfilled'
+ * ```
+ */
+export function trackPromise<T>(promise: PromiseLike<T>): PromiseState<T> {
+  const existing = promiseCache.get(promise);
+  if (existing) {
+    return existing as PromiseState<T>;
+  }
+
+  const state: PromiseState<T> = { status: "pending", promise };
+  promiseCache.set(promise, state as PromiseState<unknown>);
+
+  promise.then(
+    (value) => {
+      // Only update if still pending (not replaced by another state)
+      const current = promiseCache.get(promise);
+      if (current?.status === "pending") {
+        promiseCache.set(promise, { status: "fulfilled", value });
+      }
+    },
+    (error) => {
+      // Only update if still pending
+      const current = promiseCache.get(promise);
+      if (current?.status === "pending") {
+        promiseCache.set(promise, { status: "rejected", error });
+      }
+    }
+  );
+
+  return state;
+}
+
+/**
+ * Gets the current state of a Promise without tracking it.
+ * Returns undefined if the Promise is not being tracked.
+ *
+ * @param promise - The Promise to check
+ * @returns The current state or undefined if not tracked
+ */
+export function getPromiseState<T>(
+  promise: PromiseLike<T>
+): PromiseState<T> | undefined {
+  return promiseCache.get(promise) as PromiseState<T> | undefined;
+}
+
+/**
+ * Checks if a Promise is being tracked.
+ *
+ * @param promise - The Promise to check
+ * @returns true if the Promise is tracked
+ */
+export function isTracked(promise: PromiseLike<unknown>): boolean {
+  return promiseCache.has(promise);
+}
+
+/**
+ * Type guard to check if a value is a DerivedAtom.
+ */
+export function isDerived<T>(value: unknown): value is DerivedAtom<T, boolean> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    SYMBOL_DERIVED in value &&
+    (value as DerivedAtom<T, boolean>)[SYMBOL_DERIVED] === true
+  );
+}
+
+/**
+ * Returns the current state of an atom as a discriminated union.
+ *
+ * For DerivedAtom:
+ * - Returns atom.state() directly (derived atoms track their own state)
+ *
+ * For MutableAtom:
+ * - 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>> {
+  // For derived atoms, use their own state method
+  if (isDerived<T>(atom)) {
+    return atom.state() as AtomState<Awaited<T>>;
+  }
+
+  const value = atom.value;
+
+  // 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>>,
+      };
+  }
+}
+
+/**
+ * Unwraps a value that may be a Promise.
+ * - If not a Promise, returns the value directly.
+ * - If a resolved Promise, returns the resolved value.
+ * - If a loading Promise, throws the Promise (for Suspense).
+ * - If a rejected Promise, throws the error.
+ *
+ * This follows the React Suspense pattern where throwing a Promise
+ * signals that the component should suspend until the Promise resolves.
+ *
+ * @param value - The value to unwrap (may be a Promise)
+ * @returns The unwrapped value
+ * @throws Promise if loading, Error if rejected
+ */
+export function unwrap<T>(value: T | PromiseLike<T>): T {
+  if (!isPromiseLike(value)) {
+    return value;
+  }
+
+  const promise = value as PromiseLike<T>;
+  const state = trackPromise(promise);
+
+  switch (state.status) {
+    case "pending":
+      throw state.promise;
+    case "rejected":
+      throw state.error;
+    case "fulfilled":
+      return state.value;
+  }
+}
+
+/**
+ * Checks if a value is a pending Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in pending state
+ */
+export function isPending<T>(value: T | PromiseLike<T>): boolean {
+  if (!isPromiseLike(value)) {
+    return false;
+  }
+  const state = trackPromise(value as PromiseLike<T>);
+  return state.status === "pending";
+}
+
+/**
+ * Checks if a value is a fulfilled Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in fulfilled state
+ */
+export function isFulfilled<T>(value: T | PromiseLike<T>): boolean {
+  if (!isPromiseLike(value)) {
+    return false;
+  }
+  const state = trackPromise(value as PromiseLike<T>);
+  return state.status === "fulfilled";
+}
+
+/**
+ * Checks if a value is a rejected Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in rejected state
+ */
+export function isRejected<T>(value: T | PromiseLike<T>): boolean {
+  if (!isPromiseLike(value)) {
+    return false;
+  }
+  const state = trackPromise(value as PromiseLike<T>);
+  return state.status === "rejected";
+}
+
+/**
+ * Gets the resolved value of a Promise if fulfilled, otherwise undefined.
+ *
+ * @param value - The value to check
+ * @returns The resolved value or undefined
+ */
+export function getResolvedValue<T>(value: T | PromiseLike<T>): T | undefined {
+  if (!isPromiseLike(value)) {
+    return value;
+  }
+  const state = getPromiseState(value as PromiseLike<T>);
+  if (state?.status === "fulfilled") {
+    return state.value;
+  }
+  return undefined;
+}
+
+/**
+ * Gets the error of a Promise if rejected, otherwise undefined.
+ *
+ * @param value - The value to check
+ * @returns The error or undefined
+ */
+export function getRejectedError<T>(
+  value: T | PromiseLike<T>
+): unknown | undefined {
+  if (!isPromiseLike(value)) {
+    return undefined;
+  }
+  const state = getPromiseState(value as PromiseLike<T>);
+  if (state?.status === "rejected") {
+    return state.error;
+  }
+  return undefined;
+}

package/src/core/scheduleNotifyHook.ts

@@ -0,0 +1,53 @@
+import { hook } from "./hook";
+
+/**
+ * Hook that controls how atom change notifications are scheduled.
+ *
+ * ## Default Behavior
+ *
+ * By default, notifications are **synchronous** - listeners are called immediately
+ * when an atom's value changes:
+ *
+ * ```ts
+ * // Default: (fn) => fn() - immediate execution
+ * atom.set(newValue);  // Listeners called immediately here
+ * ```
+ *
+ * ## Used by `batch()`
+ *
+ * The `batch()` function temporarily overrides this hook to defer notifications
+ * until all updates complete:
+ *
+ * ```ts
+ * batch(() => {
+ *   a.set(1);  // Notification deferred
+ *   b.set(2);  // Notification deferred
+ * });
+ * // All listeners called here (deduped)
+ * ```
+ *
+ * ## Custom Scheduling
+ *
+ * Can be overridden for custom scheduling strategies (e.g., microtask, RAF):
+ *
+ * ```ts
+ * // Schedule notifications as microtasks
+ * scheduleNotifyHook.override(() => (fn) => queueMicrotask(fn));
+ *
+ * // Schedule notifications on next animation frame
+ * scheduleNotifyHook.override(() => (fn) => requestAnimationFrame(fn));
+ *
+ * // Reset to default synchronous behavior
+ * scheduleNotifyHook.reset();
+ * ```
+ *
+ * ## API
+ *
+ * - `scheduleNotifyHook.current` - Get/set the current scheduler function
+ * - `scheduleNotifyHook.override(reducer)` - Override with custom scheduler (reducer receives previous)
+ * - `scheduleNotifyHook.reset()` - Reset to default synchronous behavior
+ * - `scheduleNotifyHook(reducer)` - Create a HookSetup for use with `hook.use()`
+ *
+ * @internal Used internally by atomState and batch. Not typically needed by users.
+ */
+export const scheduleNotifyHook = hook((fn: VoidFunction) => fn());