atomirx 0.0.7 → 0.1.0

package/src/core/atomState.ts

@@ -1,256 +0,0 @@
-import { emitter, Emitter } from "./emitter";
-import { resolveEquality } from "./equality";
-import { scheduleNotifyHook } from "./scheduleNotifyHook";
-import { Equality } from "./types";
-
-/**
- * Options for creating an atomState.
- */
-export interface AtomStateOptions<T, TFallback = undefined> {
-  /** Equality strategy for change detection (default: "strict") */
-  equals?: Equality<T>;
-  /**
-   * Fallback value to use during loading or error states.
-   * When set, enables "stale" mode where value is never undefined.
-   */
-  fallback?: TFallback;
-  /**
-   * Whether fallback mode is enabled.
-   * When true, getValue() returns fallback/lastResolved during loading/error.
-   */
-  hasFallback?: boolean;
-}
-
-/**
- * API for managing atom state with async support.
- */
-export interface AtomStateAPI<T, TFallback = undefined> {
-  /** Get the current value (undefined if loading or error, unless fallback mode) */
-  getValue(): TFallback extends undefined ? T | undefined : T | TFallback;
-  /** Get the loading state */
-  getLoading(): boolean;
-  /** Get the error (undefined if no error) */
-  getError(): any;
-  /** Get the current promise */
-  getPromise(): PromiseLike<T>;
-
-  /** Set the value (clears loading and error, notifies if changed) */
-  setValue(value: T, silent?: boolean): void;
-  /** Set loading state with a promise (clears value and error, notifies) */
-  setLoading(promise: PromiseLike<T>, silent?: boolean): void;
-  /** Set error state (clears value and loading, notifies if changed) */
-  setError(error: any, silent?: boolean): void;
-  /** Reset to initial state (notifies if was not already initial) */
-  reset(): void;
-
-  /** Get current version (for race condition handling) */
-  getVersion(): number;
-  /** Check if a version is stale (older than current) */
-  isVersionStale(version: number): boolean;
-
-  /**
-   * Returns true if fallback mode is enabled AND (loading OR error).
-   * When true, getValue() returns fallback or last resolved value.
-   */
-  stale(): boolean;
-
-  /**
-   * Returns true if value has been changed by setValue() (not during init).
-   */
-  isDirty(): boolean;
-
-  /**
-   * Marks the state as dirty (called when set() is used).
-   */
-  markDirty(): void;
-
-  /**
-   * Clears the dirty flag (called on reset).
-   */
-  clearDirty(): void;
-
-  /** Subscribe to state changes */
-  on: Emitter["on"];
-}
-
-/**
- * Creates a state container for atoms with async support.
- *
- * Handles:
- * - Value, loading, and error states
- * - Version tracking for race condition handling
- * - Equality checking for change detection
- * - Notification scheduling
- * - Fallback mode for stale-while-revalidate pattern
- *
- * @template T - The type of value stored
- * @template TFallback - The type of fallback value (default: undefined)
- * @param options - Configuration options
- * @returns AtomStateAPI for managing the state
- *
- * @example
- * ```ts
- * const state = atomState<number>();
- *
- * state.setValue(42);
- * console.log(state.getValue()); // 42
- *
- * state.setLoading(fetchData());
- * console.log(state.getLoading()); // true
- *
- * state.on(() => console.log('State changed!'));
- * ```
- *
- * @example With fallback
- * ```ts
- * const state = atomState<User, User>({
- *   fallback: { name: 'Guest' },
- *   hasFallback: true
- * });
- *
- * state.setLoading(fetchUser());
- * console.log(state.getValue()); // { name: 'Guest' }
- * console.log(state.isStale()); // true
- * ```
- */
-export function atomState<T, TFallback = undefined>(
-  options: AtomStateOptions<T, TFallback> = {}
-): AtomStateAPI<T, TFallback> {
-  const changeEmitter = emitter();
-  const eq = resolveEquality(options.equals as Equality<unknown>);
-
-  // Fallback configuration
-  const hasFallback = options.hasFallback ?? false;
-  const fallbackValue = options.fallback as TFallback;
-
-  // Internal state
-  let value: T | undefined = undefined;
-  let loading = false;
-  let error: any = undefined;
-  let promise: PromiseLike<T> = Promise.resolve(undefined as T);
-  let version = 0;
-
-  // Track last resolved value for stale-while-revalidate
-  let lastResolvedValue: T | undefined = undefined;
-
-  // Track if value has been modified by set()
-  let dirty = false;
-
-  /**
-   * Schedules notification to all subscribers.
-   * Each listener is scheduled individually to enable deduping in batch().
-   */
-  const notify = () => {
-    changeEmitter.forEach((listener) => {
-      scheduleNotifyHook.current(listener);
-    });
-  };
-
-  /**
-   * Checks if state is in initial state (no value, not loading, no error).
-   */
-  const isInitialState = () => {
-    return value === undefined && !loading && error === undefined;
-  };
-
-  const api: AtomStateAPI<T, TFallback> = {
-    getValue: () => {
-      // If fallback mode enabled and in loading/error state
-      if (hasFallback && (loading || error !== undefined)) {
-        // Return last resolved value if available, otherwise fallback
-        return (lastResolvedValue ?? fallbackValue) as any;
-      }
-      return value as any;
-    },
-    getLoading: () => loading,
-    getError: () => error,
-    getPromise: () => promise,
-    getVersion: () => version,
-
-    isVersionStale: (v: number) => v !== version,
-
-    stale: () => {
-      // Returns true if fallback mode enabled AND (loading OR error)
-      return hasFallback && (loading || error !== undefined);
-    },
-
-    isDirty: () => dirty,
-
-    markDirty: () => {
-      dirty = true;
-    },
-
-    clearDirty: () => {
-      dirty = false;
-    },
-
-    setValue: (newValue: T, silent = false) => {
-      // Check equality before updating (only if we have a previous value)
-      if (
-        value !== undefined &&
-        eq(newValue, value) &&
-        !loading &&
-        error === undefined
-      ) {
-        return;
-      }
-
-      value = newValue;
-      loading = false;
-      error = undefined;
-      promise = Promise.resolve(newValue);
-      version++;
-
-      // Track last resolved value for fallback mode
-      lastResolvedValue = newValue;
-
-      if (!silent) notify();
-    },
-
-    setLoading: (newPromise: PromiseLike<T>, silent = false) => {
-      // In fallback mode, don't clear value - it will be returned via getValue()
-      // But internally we track that we're loading
-      value = undefined;
-      loading = true;
-      error = undefined;
-      promise = newPromise;
-      version++;
-      if (!silent) notify();
-    },
-
-    setError: (newError: any, silent = false) => {
-      // Check if error is the same
-      if (Object.is(error, newError) && !loading && value === undefined) {
-        return;
-      }
-
-      value = undefined;
-      loading = false;
-      error = newError;
-      version++;
-      if (!silent) notify();
-    },
-
-    reset: () => {
-      // Don't notify if already in initial state
-      if (isInitialState() && lastResolvedValue === undefined && !dirty) {
-        return;
-      }
-
-      value = undefined;
-      loading = false;
-      error = undefined;
-      promise = Promise.resolve(undefined as T);
-      version++;
-      // Clear last resolved value on reset
-      lastResolvedValue = undefined;
-      // Clear dirty flag on reset
-      dirty = false;
-      notify();
-    },
-
-    on: changeEmitter.on,
-  };
-
-  return api;
-}

package/src/core/batch.test.ts

@@ -1,257 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { batch } from "./batch";
-import { atom } from "./atom";
-
-describe("batch", () => {
-  describe("basic batching", () => {
-    it("should batch multiple updates into single notification", () => {
-      const count = atom(0);
-      const listener = vi.fn();
-      count.on(listener);
-
-      batch(() => {
-        count.set(1);
-        count.set(2);
-        count.set(3);
-      });
-
-      // All updates batched - listener called once at the end
-      expect(count.get()).toBe(3);
-      expect(listener).toHaveBeenCalledTimes(1);
-    });
-
-    it("should return the function result", () => {
-      const result = batch(() => {
-        return "hello";
-      });
-
-      expect(result).toBe("hello");
-    });
-
-    it("should return complex values", () => {
-      const result = batch(() => {
-        return { value: 42, items: [1, 2, 3] };
-      });
-
-      expect(result).toEqual({ value: 42, items: [1, 2, 3] });
-    });
-  });
-
-  describe("nested batching", () => {
-    it("should support nested batch calls", () => {
-      const count = atom(0);
-      const listener = vi.fn();
-      count.on(listener);
-
-      batch(() => {
-        count.set(1);
-
-        batch(() => {
-          count.set(2);
-          count.set(3);
-        });
-
-        count.set(4);
-      });
-
-      expect(count.get()).toBe(4);
-      // All updates batched together
-      expect(listener).toHaveBeenCalledTimes(1);
-    });
-
-    it("should return value from nested batch", () => {
-      const result = batch(() => {
-        const inner = batch(() => {
-          return "inner";
-        });
-        return `outer-${inner}`;
-      });
-
-      expect(result).toBe("outer-inner");
-    });
-  });
-
-  describe("multiple atoms", () => {
-    it("should batch updates across multiple atoms", () => {
-      const a = atom(0);
-      const b = atom(0);
-      const listenerA = vi.fn();
-      const listenerB = vi.fn();
-      a.on(listenerA);
-      b.on(listenerB);
-
-      batch(() => {
-        a.set(1);
-        b.set(1);
-        a.set(2);
-        b.set(2);
-      });
-
-      expect(a.get()).toBe(2);
-      expect(b.get()).toBe(2);
-      expect(listenerA).toHaveBeenCalledTimes(1);
-      expect(listenerB).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe("error handling", () => {
-    it("should propagate errors", () => {
-      expect(() => {
-        batch(() => {
-          throw new Error("test error");
-        });
-      }).toThrow("test error");
-    });
-
-    it("should still process notifications after error in nested batch", () => {
-      const count = atom(0);
-      const listener = vi.fn();
-      count.on(listener);
-
-      expect(() => {
-        batch(() => {
-          count.set(1);
-
-          try {
-            batch(() => {
-              count.set(2);
-              throw new Error("inner error");
-            });
-          } catch {
-            // Catch inner error
-          }
-
-          count.set(3);
-        });
-      }).not.toThrow();
-
-      expect(count.get()).toBe(3);
-    });
-  });
-
-  describe("cascading updates", () => {
-    it("should handle cascading updates within batch", () => {
-      const a = atom(0);
-      const b = atom(0);
-      const listenerA = vi.fn();
-      const listenerB = vi.fn();
-
-      // When a changes, update b
-      a.on(() => {
-        if (a.get() !== undefined && a.get() > 0) {
-          b.set(a.get() * 2);
-        }
-      });
-
-      a.on(listenerA);
-      b.on(listenerB);
-
-      batch(() => {
-        a.set(5);
-      });
-
-      expect(a.get()).toBe(5);
-      expect(b.get()).toBe(10);
-    });
-  });
-
-  describe("without batch", () => {
-    it("should notify immediately without batch", () => {
-      const count = atom(0);
-      const listener = vi.fn();
-      count.on(listener);
-
-      count.set(1);
-      expect(listener).toHaveBeenCalledTimes(1);
-
-      count.set(2);
-      expect(listener).toHaveBeenCalledTimes(2);
-
-      count.set(3);
-      expect(listener).toHaveBeenCalledTimes(3);
-    });
-  });
-
-  describe("listener deduping", () => {
-    it("should dedupe same listener subscribed to multiple atoms", () => {
-      const a = atom(0);
-      const b = atom(0);
-      const c = atom(0);
-
-      // Same listener subscribed to all three atoms
-      const sharedListener = vi.fn();
-      a.on(sharedListener);
-      b.on(sharedListener);
-      c.on(sharedListener);
-
-      batch(() => {
-        a.set(1);
-        b.set(1);
-        c.set(1);
-      });
-
-      // Listener should only be called once (deduped), not 3 times
-      expect(sharedListener).toHaveBeenCalledTimes(1);
-    });
-
-    it("should call different listeners separately", () => {
-      const a = atom(0);
-      const b = atom(0);
-
-      const listenerA = vi.fn();
-      const listenerB = vi.fn();
-      a.on(listenerA);
-      b.on(listenerB);
-
-      batch(() => {
-        a.set(1);
-        b.set(1);
-      });
-
-      // Different listeners should each be called once
-      expect(listenerA).toHaveBeenCalledTimes(1);
-      expect(listenerB).toHaveBeenCalledTimes(1);
-    });
-
-    it("should dedupe listener when same atom updated multiple times", () => {
-      const count = atom(0);
-      const listener = vi.fn();
-      count.on(listener);
-
-      batch(() => {
-        count.set(1);
-        count.set(2);
-        count.set(3);
-      });
-
-      // Listener called once at the end with final value
-      expect(listener).toHaveBeenCalledTimes(1);
-      expect(count.get()).toBe(3);
-    });
-
-    it("should handle mixed scenario with shared and unique listeners", () => {
-      const a = atom(0);
-      const b = atom(0);
-
-      const sharedListener = vi.fn();
-      const uniqueListenerA = vi.fn();
-      const uniqueListenerB = vi.fn();
-
-      a.on(sharedListener);
-      a.on(uniqueListenerA);
-      b.on(sharedListener);
-      b.on(uniqueListenerB);
-
-      batch(() => {
-        a.set(1);
-        b.set(1);
-      });
-
-      // Shared listener deduped to 1 call
-      expect(sharedListener).toHaveBeenCalledTimes(1);
-      // Unique listeners called once each
-      expect(uniqueListenerA).toHaveBeenCalledTimes(1);
-      expect(uniqueListenerB).toHaveBeenCalledTimes(1);
-    });
-  });
-});

package/src/core/batch.ts

@@ -1,172 +0,0 @@
-import { hook } from "./hook";
-import { scheduleNotifyHook } from "./scheduleNotifyHook";
-
-let batchDepth = 0;
-
-/**
- * Batches multiple state updates into a single reactive update cycle.
- *
- * Without batching, each `atom.set()` call triggers immediate notifications to all
- * subscribers. With `batch()`, all updates are collected and subscribers are notified
- * once at the end with the final values.
- *
- * ## Key Behavior
- *
- * 1. **Multiple updates to same atom**: Only 1 notification with final value
- * 2. **Listener deduplication**: Same listener subscribed to multiple atoms = 1 call
- * 3. **Nested batches**: Inner batches are merged into outer batch
- * 4. **Cascading updates**: Updates triggered by listeners are also batched
- *
- * ## When to Use
- *
- * - Updating multiple related atoms together
- * - Preventing intermediate render states
- * - Performance optimization for bulk updates
- * - Ensuring consistent state during complex operations
- *
- * ## How It Works
- *
- * ```
- * batch(() => {
- *   a.set(1);  // Queued, no notification yet
- *   b.set(2);  // Queued, no notification yet
- *   c.set(3);  // Queued, no notification yet
- * });
- * // All listeners notified once here (deduped)
- * ```
- *
- * @template T - Return type of the batched function
- * @param fn - Function containing multiple state updates
- * @returns The return value of fn
- *
- * @example Basic batching - prevent intermediate states
- * ```ts
- * const firstName = atom("John");
- * const lastName = atom("Doe");
- *
- * // Without batch: component renders twice (once per set)
- * firstName.set("Jane");
- * lastName.set("Smith");
- *
- * // With batch: component renders once with final state
- * batch(() => {
- *   firstName.set("Jane");
- *   lastName.set("Smith");
- * });
- * ```
- *
- * @example Multiple updates to same atom
- * ```ts
- * const counter = atom(0);
- *
- * counter.on(() => console.log("Counter:", counter.get()));
- *
- * batch(() => {
- *   counter.set(1);
- *   counter.set(2);
- *   counter.set(3);
- * });
- * // Logs once: "Counter: 3"
- * ```
- *
- * @example Listener deduplication
- * ```ts
- * const a = atom(0);
- * const b = atom(0);
- *
- * // Same listener subscribed to both atoms
- * const listener = () => console.log("Changed!", a.get(), b.get());
- * a.on(listener);
- * b.on(listener);
- *
- * batch(() => {
- *   a.set(1);
- *   b.set(2);
- * });
- * // Logs once: "Changed! 1 2" (not twice)
- * ```
- *
- * @example Nested batches
- * ```ts
- * batch(() => {
- *   a.set(1);
- *   batch(() => {
- *     b.set(2);
- *     c.set(3);
- *   });
- *   d.set(4);
- * });
- * // All updates batched together, listeners notified once at outer batch end
- * ```
- *
- * @example Return value
- * ```ts
- * const result = batch(() => {
- *   counter.set(10);
- *   return counter.get() * 2;
- * });
- * console.log(result); // 20
- * ```
- *
- * @example With async operations (be careful!)
- * ```ts
- * // ❌ Wrong: async operations escape the batch
- * batch(async () => {
- *   a.set(1);
- *   await delay(100);
- *   b.set(2); // This is OUTSIDE the batch!
- * });
- *
- * // ✅ Correct: batch sync operations only
- * batch(() => {
- *   a.set(1);
- *   b.set(2);
- * });
- * await delay(100);
- * batch(() => {
- *   c.set(3);
- * });
- * ```
- */
-export function batch<T>(fn: () => T): T {
-  batchDepth++;
-
-  // First batch - set up the notification hook with deduping
-  if (batchDepth === 1) {
-    // Use Set to dedupe listeners - if same listener is scheduled multiple times,
-    // it only gets called once (e.g., component subscribed to multiple atoms)
-    let pendingListeners = new Set<VoidFunction>();
-
-    // Schedule listener to be called at batch end (deduped by Set)
-    const scheduleListener = (listener: VoidFunction) => {
-      pendingListeners.add(listener);
-    };
-
-    try {
-      return hook.use([scheduleNotifyHook(() => scheduleListener)], fn);
-    } finally {
-      batchDepth--;
-
-      // Process pending listeners, handling cascading updates
-      // Keep the hook active so any updates triggered by listeners are also batched
-      hook.use([scheduleNotifyHook(() => scheduleListener)], () => {
-        while (pendingListeners.size > 0) {
-          // Snapshot and clear before calling to handle re-entrancy
-          const listeners = pendingListeners;
-          pendingListeners = new Set();
-
-          for (const listener of listeners) {
-            listener();
-          }
-        }
-      });
-    }
-  }
-
-  // Nested batch - just run the function (outer batch handles notifications)
-  try {
-    return fn();
-  } finally {
-    batchDepth--;
-  }
-}