atomirx 0.0.8 → 0.1.1

package/src/core/effect.ts

@@ -1,188 +0,0 @@
-import { batch } from "./batch";
-import { derived } from "./derived";
-import { emitter } from "./emitter";
-import { EffectInfo, onCreateHook } from "./onCreateHook";
-import { ReactiveSelector, SelectContext } from "./select";
-import { EffectMeta, EffectOptions } from "./types";
-import { WithReadySelectContext } from "./withReady";
-
-/**
- * Context object passed to effect functions.
- * Extends `SelectContext` with cleanup utilities.
- */
-export interface EffectContext extends SelectContext, WithReadySelectContext {
-  /**
-   * Register a cleanup function that runs before the next execution or on dispose.
-   * Multiple cleanup functions can be registered; they run in FIFO order.
-   *
-   * @param cleanup - Function to run during cleanup
-   *
-   * @example
-   * ```ts
-   * effect(({ read, onCleanup }) => {
-   *   const id = setInterval(() => console.log('tick'), 1000);
-   *   onCleanup(() => clearInterval(id));
-   * });
-   * ```
-   */
-  onCleanup: (cleanup: VoidFunction) => void;
-}
-
-export interface Effect {
-  dispose: VoidFunction;
-  meta?: EffectMeta;
-}
-
-/**
- * Creates a side-effect that runs when accessed atom(s) change.
- *
- * Effects are similar to derived atoms but for side-effects rather than computed values.
- * They inherit derived's behavior:
- * - **Suspense-like async**: Waits for async atoms to resolve before running
- * - **Conditional dependencies**: Only tracks atoms actually accessed via `read()`
- * - **Automatic cleanup**: Previous cleanup runs before next execution
- * - **Batched updates**: Atom updates within the effect are batched
- *
- * ## IMPORTANT: Effect Function Must Be Synchronous
- *
- * **The effect function MUST NOT be async or return a Promise.**
- *
- * ```ts
- * // ❌ WRONG - Don't use async function
- * effect(async ({ read }) => {
- *   const data = await fetch('/api');
- *   console.log(data);
- * });
- *
- * // ✅ CORRECT - Create async atom and read with read()
- * const data$ = atom(fetch('/api').then(r => r.json()));
- * effect(({ read }) => {
- *   console.log(read(data$)); // Suspends until resolved
- * });
- * ```
- *
- * ## Basic Usage
- *
- * ```ts
- * const dispose = effect(({ read }) => {
- *   localStorage.setItem('count', String(read(countAtom)));
- * });
- * ```
- *
- * ## With Cleanup
- *
- * Use `onCleanup` to register cleanup functions that run before the next execution or on dispose:
- *
- * ```ts
- * const dispose = effect(({ read, onCleanup }) => {
- *   const interval = read(intervalAtom);
- *   const id = setInterval(() => console.log('tick'), interval);
- *   onCleanup(() => clearInterval(id));
- * });
- * ```
- *
- * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
- *
- * **Never wrap `read()` calls in try/catch blocks.** The `read()` function throws
- * Promises when atoms are loading (Suspense pattern). A try/catch will catch
- * these Promises and break the Suspense mechanism.
- *
- * ```ts
- * // ❌ WRONG - Catches Suspense Promise, breaks loading state
- * effect(({ read }) => {
- *   try {
- *     const data = read(asyncAtom$);
- *     riskyOperation(data);
- *   } catch (e) {
- *     console.error(e); // Catches BOTH errors AND loading promises!
- *   }
- * });
- *
- * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
- * effect(({ read, safe }) => {
- *   const [err, data] = safe(() => {
- *     const raw = read(asyncAtom$);    // Can throw Promise (Suspense)
- *     return riskyOperation(raw);      // Can throw Error
- *   });
- *
- *   if (err) {
- *     console.error('Operation failed:', err);
- *     return;
- *   }
- *   // Use data safely
- * });
- * ```
- *
- * The `safe()` utility:
- * - **Catches errors** and returns `[error, undefined]`
- * - **Re-throws Promises** to preserve Suspense behavior
- * - Returns `[undefined, result]` on success
- *
- * @param fn - Effect callback receiving context with `{ read, all, any, race, settled, safe, onCleanup }`.
- *             Must be synchronous (not async).
- * @param options - Optional configuration (key)
- * @returns Dispose function to stop the effect and run final cleanup
- * @throws Error if effect function returns a Promise
- */
-export function effect(
-  fn: ReactiveSelector<void, EffectContext>,
-  options?: EffectOptions
-): Effect {
-  let disposed = false;
-  const cleanupEmitter = emitter();
-
-  // Create the Effect object early so we can build EffectInfo
-  const e: Effect = {
-    meta: options?.meta,
-    dispose: () => {
-      // Guard against multiple dispose calls
-      if (disposed) return;
-
-      // Mark as disposed
-      disposed = true;
-      // Run final cleanup
-      cleanupEmitter.emitAndClear();
-    },
-  };
-
-  // Create EffectInfo to pass to derived for error attribution
-  const effectInfo: EffectInfo = {
-    type: "effect",
-    key: options?.meta?.key,
-    meta: options?.meta,
-    instance: e,
-  };
-
-  // Create a derived atom that runs the effect on each recomputation.
-  // Pass _errorSource so errors are attributed to the effect, not the internal derived
-  const derivedAtom = derived(
-    (context) => {
-      // Run previous cleanup before next execution
-      cleanupEmitter.emitAndClear();
-
-      // Skip effect execution if disposed
-      if (disposed) return;
-
-      // Run effect in a batch - multiple atom updates will only notify once
-      // Cast to EffectContext since we're adding onCleanup to the DerivedContext
-      const effectContext = {
-        ...context,
-        onCleanup: cleanupEmitter.on,
-      } as unknown as EffectContext;
-      batch(() => fn(effectContext));
-    },
-    {
-      onError: options?.onError,
-      _errorSource: effectInfo,
-    }
-  );
-
-  // Access .get() to trigger initial computation (derived is lazy)
-  // Errors are handled via onError callback or safe() in the effect function
-  derivedAtom.get();
-
-  // Notify devtools/plugins of effect creation
-  onCreateHook.current?.(effectInfo);
-
-  return e;
-}

package/src/core/emitter.test.ts

@@ -1,364 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { emitter } from "./emitter";
-
-describe("emitter", () => {
-  describe("basic functionality", () => {
-    it("should emit to listeners in order", () => {
-      const e = emitter<number>();
-      const order: number[] = [];
-
-      e.on(() => order.push(1));
-      e.on(() => order.push(2));
-      e.on(() => order.push(3));
-
-      e.emit(42);
-
-      expect(order).toEqual([1, 2, 3]);
-    });
-
-    it("should support array of listeners in on()", () => {
-      const e = emitter<number>();
-      const calls: number[] = [];
-
-      e.on([
-        (n) => calls.push(n),
-        (n) => calls.push(n * 2),
-        (n) => calls.push(n * 3),
-      ]);
-
-      e.emit(10);
-
-      expect(calls).toEqual([10, 20, 30]);
-    });
-
-    it("should return size of listeners", () => {
-      const e = emitter<number>();
-
-      expect(e.size()).toBe(0);
-
-      e.on(() => {});
-      expect(e.size()).toBe(1);
-
-      e.on(() => {});
-      expect(e.size()).toBe(2);
-    });
-
-    it("should unsubscribe listener", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      const unsub = e.on(listener);
-      e.emit(1);
-      expect(listener).toHaveBeenCalledTimes(1);
-
-      unsub();
-      e.emit(2);
-      expect(listener).toHaveBeenCalledTimes(1);
-    });
-
-    it("should support initial listeners", () => {
-      const listener1 = vi.fn();
-      const listener2 = vi.fn();
-
-      const e = emitter<number>([listener1, listener2]);
-      e.emit(42);
-
-      expect(listener1).toHaveBeenCalledWith(42);
-      expect(listener2).toHaveBeenCalledWith(42);
-    });
-  });
-
-  describe("on() with map function", () => {
-    it("should transform values with map function", () => {
-      const e = emitter<{ type: string; data: number }>();
-      const listener = vi.fn();
-
-      e.on((event) => ({ value: event.data * 2 }), listener);
-
-      e.emit({ type: "test", data: 5 });
-
-      expect(listener).toHaveBeenCalledWith(10);
-    });
-
-    it("should filter events when map returns undefined", () => {
-      const e = emitter<{ type: string; data: number }>();
-      const listener = vi.fn();
-
-      e.on(
-        (event) =>
-          event.type === "success" ? { value: event.data } : undefined,
-        listener
-      );
-
-      e.emit({ type: "error", data: 1 });
-      expect(listener).not.toHaveBeenCalled();
-
-      e.emit({ type: "success", data: 2 });
-      expect(listener).toHaveBeenCalledWith(2);
-    });
-
-    it("should support array of listeners with map function", () => {
-      const e = emitter<number>();
-      const listener1 = vi.fn();
-      const listener2 = vi.fn();
-
-      e.on((n) => ({ value: n * 10 }), [listener1, listener2]);
-
-      e.emit(5);
-
-      expect(listener1).toHaveBeenCalledWith(50);
-      expect(listener2).toHaveBeenCalledWith(50);
-    });
-
-    it("should unsubscribe mapped listeners correctly", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      const unsub = e.on((n) => ({ value: n }), listener);
-
-      e.emit(1);
-      expect(listener).toHaveBeenCalledTimes(1);
-
-      unsub();
-
-      e.emit(2);
-      expect(listener).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe("emitLifo", () => {
-    it("should emit in reverse order (LIFO)", () => {
-      const e = emitter<number>();
-      const order: number[] = [];
-
-      e.on(() => order.push(1));
-      e.on(() => order.push(2));
-      e.on(() => order.push(3));
-
-      e.emitLifo(42);
-
-      expect(order).toEqual([3, 2, 1]);
-    });
-
-    it("should be no-op when settled", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.on(listener);
-      e.settle(1);
-      listener.mockClear();
-
-      e.emitLifo(2);
-
-      expect(listener).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("clear", () => {
-    it("should remove all listeners", () => {
-      const e = emitter<number>();
-      const listener1 = vi.fn();
-      const listener2 = vi.fn();
-
-      e.on(listener1);
-      e.on(listener2);
-
-      expect(e.size()).toBe(2);
-
-      e.clear();
-
-      expect(e.size()).toBe(0);
-      e.emit(1);
-      expect(listener1).not.toHaveBeenCalled();
-      expect(listener2).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("emitAndClear", () => {
-    it("should emit to all listeners then clear", () => {
-      const e = emitter<number>();
-      const listener1 = vi.fn();
-      const listener2 = vi.fn();
-
-      e.on(listener1);
-      e.on(listener2);
-
-      e.emitAndClear(42);
-
-      expect(listener1).toHaveBeenCalledTimes(1);
-      expect(listener2).toHaveBeenCalledTimes(1);
-      expect(listener1).toHaveBeenCalledWith(42);
-      expect(listener2).toHaveBeenCalledWith(42);
-      expect(e.size()).toBe(0);
-    });
-
-    it("should be no-op when settled", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.on(listener);
-      e.settle(1);
-      listener.mockClear();
-
-      e.emitAndClear(2);
-
-      expect(listener).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("emitAndClearLifo", () => {
-    it("should emit in reverse order then clear", () => {
-      const e = emitter<number>();
-      const order: number[] = [];
-
-      e.on(() => order.push(1));
-      e.on(() => order.push(2));
-      e.on(() => order.push(3));
-
-      e.emitAndClearLifo(42);
-
-      expect(order).toEqual([3, 2, 1]);
-      expect(e.size()).toBe(0);
-    });
-
-    it("should be no-op when settled", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.on(listener);
-      e.settle(1);
-      listener.mockClear();
-
-      e.emitAndClearLifo(2);
-
-      expect(listener).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("settle", () => {
-    it("should emit to all listeners and clear", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.on(listener);
-
-      e.settle(99);
-
-      expect(listener).toHaveBeenCalledWith(99);
-      expect(e.size()).toBe(0);
-    });
-
-    it("should mark emitter as settled", () => {
-      const e = emitter<number>();
-
-      expect(e.settled()).toBe(false);
-
-      e.settle(1);
-
-      expect(e.settled()).toBe(true);
-    });
-
-    it("should be no-op if already settled", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.settle(1);
-
-      e.on(listener);
-      listener.mockClear();
-
-      e.settle(2);
-
-      expect(listener).not.toHaveBeenCalled();
-    });
-
-    it("should call new subscribers immediately with settled value", () => {
-      const e = emitter<number>();
-
-      e.settle(42);
-
-      const listener = vi.fn();
-      const unsub = e.on(listener);
-
-      expect(listener).toHaveBeenCalledWith(42);
-      expect(unsub).toBeDefined();
-      // Unsub should be no-op for settled emitters
-      unsub();
-    });
-
-    it("should call new mapped subscribers immediately with settled value", () => {
-      const e = emitter<number>();
-
-      e.settle(10);
-
-      const listener = vi.fn();
-      e.on((n) => ({ value: n * 2 }), listener);
-
-      expect(listener).toHaveBeenCalledWith(20);
-    });
-
-    it("should call multiple new subscribers immediately when settled", () => {
-      const e = emitter<number>();
-
-      e.settle(5);
-
-      const listener1 = vi.fn();
-      const listener2 = vi.fn();
-      e.on([listener1, listener2]);
-
-      expect(listener1).toHaveBeenCalledWith(5);
-      expect(listener2).toHaveBeenCalledWith(5);
-    });
-  });
-
-  describe("emit when settled", () => {
-    it("should be no-op", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      e.on(listener);
-      e.settle(1);
-      listener.mockClear();
-
-      e.emit(2);
-
-      expect(listener).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("edge cases", () => {
-    it("should handle emit with no listeners", () => {
-      const e = emitter<number>();
-
-      // Should not throw
-      expect(() => e.emit(1)).not.toThrow();
-      expect(() => e.emitLifo(1)).not.toThrow();
-      expect(() => e.emitAndClear(1)).not.toThrow();
-      expect(() => e.emitAndClearLifo(1)).not.toThrow();
-      expect(() => e.settle(1)).not.toThrow();
-    });
-
-    it("should handle void emitter", () => {
-      const e = emitter();
-      const listener = vi.fn();
-
-      e.on(listener);
-      e.emit();
-
-      expect(listener).toHaveBeenCalledWith(undefined);
-    });
-
-    it("should pass on() as a callback without losing context", () => {
-      const e = emitter<number>();
-      const listener = vi.fn();
-
-      // Use the bound 'on' method
-      const { on } = e;
-      on(listener);
-
-      e.emit(42);
-
-      expect(listener).toHaveBeenCalledWith(42);
-    });
-  });
-});