atomirx 0.0.1

package/src/core/atomState.test.ts

@@ -0,0 +1,342 @@
+import { describe, it, expect, vi } from "vitest";
+import { atomState } from "./atomState";
+
+describe("atomState", () => {
+  describe("initial state", () => {
+    it("should start with undefined value", () => {
+      const state = atomState<number>();
+      expect(state.getValue()).toBeUndefined();
+    });
+
+    it("should start with loading false", () => {
+      const state = atomState<number>();
+      expect(state.getLoading()).toBe(false);
+    });
+
+    it("should start with undefined error", () => {
+      const state = atomState<number>();
+      expect(state.getError()).toBeUndefined();
+    });
+
+    it("should start with version 0", () => {
+      const state = atomState<number>();
+      expect(state.getVersion()).toBe(0);
+    });
+  });
+
+  describe("setValue", () => {
+    it("should set the value", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+      expect(state.getValue()).toBe(42);
+    });
+
+    it("should clear loading state", () => {
+      const state = atomState<number>();
+      state.setLoading(Promise.resolve(1));
+      expect(state.getLoading()).toBe(true);
+
+      state.setValue(42);
+      expect(state.getLoading()).toBe(false);
+    });
+
+    it("should clear error state", () => {
+      const state = atomState<number>();
+      state.setError(new Error("test"));
+      expect(state.getError()).toBeDefined();
+
+      state.setValue(42);
+      expect(state.getError()).toBeUndefined();
+    });
+
+    it("should bump version", () => {
+      const state = atomState<number>();
+      const v1 = state.getVersion();
+      state.setValue(42);
+      expect(state.getVersion()).toBe(v1 + 1);
+    });
+
+    it("should notify listeners", () => {
+      const state = atomState<number>();
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.setValue(42);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not notify if value is equal (strict equality)", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.setValue(42);
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it("should use custom equality function", () => {
+      const state = atomState<{ id: number; name: string }>({
+        equals: (a, b) => a?.id === b?.id,
+      });
+      state.setValue({ id: 1, name: "John" });
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      // Same id, different name - should not notify
+      state.setValue({ id: 1, name: "Jane" });
+      expect(listener).not.toHaveBeenCalled();
+
+      // Different id - should notify
+      state.setValue({ id: 2, name: "Jane" });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should create a resolved promise", async () => {
+      const state = atomState<number>();
+      state.setValue(42);
+
+      const value = await state.getPromise();
+      expect(value).toBe(42);
+    });
+  });
+
+  describe("setLoading", () => {
+    it("should set loading to true", () => {
+      const state = atomState<number>();
+      state.setLoading(Promise.resolve(1));
+      expect(state.getLoading()).toBe(true);
+    });
+
+    it("should clear value", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+      state.setLoading(Promise.resolve(1));
+      expect(state.getValue()).toBeUndefined();
+    });
+
+    it("should clear error", () => {
+      const state = atomState<number>();
+      state.setError(new Error("test"));
+      state.setLoading(Promise.resolve(1));
+      expect(state.getError()).toBeUndefined();
+    });
+
+    it("should bump version", () => {
+      const state = atomState<number>();
+      const v1 = state.getVersion();
+      state.setLoading(Promise.resolve(1));
+      expect(state.getVersion()).toBe(v1 + 1);
+    });
+
+    it("should notify listeners", () => {
+      const state = atomState<number>();
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.setLoading(Promise.resolve(1));
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should store the promise", () => {
+      const state = atomState<number>();
+      const promise = Promise.resolve(42);
+      state.setLoading(promise);
+      expect(state.getPromise()).toBe(promise);
+    });
+  });
+
+  describe("setError", () => {
+    it("should set the error", () => {
+      const state = atomState<number>();
+      const error = new Error("test");
+      state.setError(error);
+      expect(state.getError()).toBe(error);
+    });
+
+    it("should set loading to false", () => {
+      const state = atomState<number>();
+      state.setLoading(Promise.resolve(1));
+      state.setError(new Error("test"));
+      expect(state.getLoading()).toBe(false);
+    });
+
+    it("should clear value", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+      state.setError(new Error("test"));
+      expect(state.getValue()).toBeUndefined();
+    });
+
+    it("should bump version", () => {
+      const state = atomState<number>();
+      const v1 = state.getVersion();
+      state.setError(new Error("test"));
+      expect(state.getVersion()).toBe(v1 + 1);
+    });
+
+    it("should notify listeners", () => {
+      const state = atomState<number>();
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.setError(new Error("test"));
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not notify if same error", () => {
+      const state = atomState<number>();
+      const error = new Error("test");
+      state.setError(error);
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.setError(error);
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("race condition handling", () => {
+    it("should detect stale versions", () => {
+      const state = atomState<number>();
+      const v1 = state.getVersion();
+
+      state.setValue(1);
+      expect(state.isVersionStale(v1)).toBe(true);
+      expect(state.isVersionStale(state.getVersion())).toBe(false);
+    });
+
+    it("should ignore stale promise resolution", async () => {
+      const state = atomState<number>();
+
+      let resolve1: (value: number) => void;
+      const promise1 = new Promise<number>((r) => {
+        resolve1 = r;
+      });
+
+      state.setLoading(promise1);
+      const v1 = state.getVersion();
+
+      // Set a new value before promise resolves
+      state.setValue(100);
+
+      // Now resolve the old promise
+      resolve1!(42);
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Value should still be 100, not 42
+      expect(state.getValue()).toBe(100);
+      expect(state.isVersionStale(v1)).toBe(true);
+    });
+  });
+
+  describe("subscriptions", () => {
+    it("should return unsubscribe function", () => {
+      const state = atomState<number>();
+      const listener = vi.fn();
+
+      const unsubscribe = state.on(listener);
+      state.setValue(1);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      state.setValue(2);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should support multiple listeners", () => {
+      const state = atomState<number>();
+      const listener1 = vi.fn();
+      const listener2 = vi.fn();
+
+      state.on(listener1);
+      state.on(listener2);
+
+      state.setValue(1);
+
+      expect(listener1).toHaveBeenCalledTimes(1);
+      expect(listener2).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("reset", () => {
+    it("should reset to initial state", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+
+      state.reset();
+
+      expect(state.getValue()).toBeUndefined();
+      expect(state.getLoading()).toBe(false);
+      expect(state.getError()).toBeUndefined();
+    });
+
+    it("should bump version on reset", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+      const v1 = state.getVersion();
+
+      state.reset();
+      expect(state.getVersion()).toBe(v1 + 1);
+    });
+
+    it("should notify listeners on reset", () => {
+      const state = atomState<number>();
+      state.setValue(42);
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.reset();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not notify if already in initial state", () => {
+      const state = atomState<number>();
+      const listener = vi.fn();
+      state.on(listener);
+
+      state.reset();
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("equals options", () => {
+    it("should use shallow equality when specified", () => {
+      const state = atomState<{ a: number }>({ equals: "shallow" });
+      state.setValue({ a: 1 });
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      // Same content - no notification
+      state.setValue({ a: 1 });
+      expect(listener).not.toHaveBeenCalled();
+
+      // Different content - should notify
+      state.setValue({ a: 2 });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should use deep equality when specified", () => {
+      const state = atomState<{ nested: { value: number } }>({
+        equals: "deep",
+      });
+      state.setValue({ nested: { value: 1 } });
+
+      const listener = vi.fn();
+      state.on(listener);
+
+      // Same deep content - no notification
+      state.setValue({ nested: { value: 1 } });
+      expect(listener).not.toHaveBeenCalled();
+
+      // Different deep content - should notify
+      state.setValue({ nested: { value: 2 } });
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/core/atomState.ts

@@ -0,0 +1,256 @@
+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;
+}