atomirx 0.0.4 → 0.0.6

package/src/core/effect.test.ts

@@ -1,6 +1,7 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { atom } from "./atom";
-import { effect } from "./effect";
+import { effect, Effect } from "./effect";
+import { onCreateHook } from "./onCreateHook";
 
 describe("effect", () => {
   describe("basic functionality", () => {
@@ -81,7 +82,7 @@ describe("effect", () => {
       const cleanupFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ read, onCleanup }) => {
+      const e = effect(({ read, onCleanup }) => {
         read(count$);
         onCleanup(cleanupFn);
       });
@@ -89,7 +90,7 @@ describe("effect", () => {
       await new Promise((r) => setTimeout(r, 0));
       expect(cleanupFn).not.toHaveBeenCalled();
 
-      dispose();
+      e.dispose();
       expect(cleanupFn).toHaveBeenCalledTimes(1);
     });
   });
@@ -99,14 +100,14 @@ describe("effect", () => {
       const effectFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ read }) => {
+      const e = effect(({ read }) => {
         effectFn(read(count$));
       });
 
       await new Promise((r) => setTimeout(r, 0));
       expect(effectFn).toHaveBeenCalledTimes(1);
 
-      dispose();
+      e.dispose();
 
       count$.set(5);
       await new Promise((r) => setTimeout(r, 10));
@@ -118,17 +119,17 @@ describe("effect", () => {
       const cleanupFn = vi.fn();
       const count$ = atom(0);
 
-      const dispose = effect(({ read, onCleanup }) => {
+      const e = effect(({ read, onCleanup }) => {
         read(count$);
         onCleanup(cleanupFn);
       });
 
       await new Promise((r) => setTimeout(r, 0));
 
-      dispose();
+      e.dispose();
       expect(cleanupFn).toHaveBeenCalledTimes(1);
 
-      dispose(); // Second call should be no-op
+      e.dispose(); // Second call should be no-op
       expect(cleanupFn).toHaveBeenCalledTimes(1);
     });
   });
@@ -413,4 +414,389 @@ describe("effect", () => {
       expect(mockStorage["prefs:u1"]).toBeUndefined();
     });
   });
+
+  describe("Effect return type", () => {
+    it("should return Effect object with dispose function", () => {
+      const e = effect(() => {});
+
+      expect(e).toHaveProperty("dispose");
+      expect(typeof e.dispose).toBe("function");
+    });
+
+    it("should return Effect object with meta when provided", () => {
+      const e = effect(() => {}, {
+        meta: { key: "myEffect" },
+      });
+
+      expect(e.meta).toEqual({ key: "myEffect" });
+    });
+
+    it("should return Effect object with undefined meta when not provided", () => {
+      const e = effect(() => {});
+
+      expect(e.meta).toBeUndefined();
+    });
+
+    it("should return Effect object that satisfies Effect interface", () => {
+      const e: Effect = effect(() => {}, {
+        meta: { key: "typedEffect" },
+      });
+
+      // Type check - this should compile
+      const dispose: VoidFunction = e.dispose;
+      expect(dispose).toBeDefined();
+    });
+  });
+
+  describe("onCreateHook", () => {
+    beforeEach(() => {
+      onCreateHook.reset();
+    });
+
+    afterEach(() => {
+      onCreateHook.reset();
+    });
+
+    it("should call onCreateHook when effect is created", () => {
+      const hookFn = vi.fn();
+      onCreateHook.override(() => hookFn);
+
+      const e = effect(() => {}, { meta: { key: "testEffect" } });
+
+      // effect() internally creates a derived atom, so hook is called twice:
+      // 1. for the internal derived atom
+      // 2. for the effect itself
+      const effectCall = hookFn.mock.calls.find(
+        (call) => call[0].type === "effect"
+      );
+      expect(effectCall).toBeDefined();
+      expect(effectCall![0]).toEqual({
+        type: "effect",
+        key: "testEffect",
+        meta: { key: "testEffect" },
+        instance: e,
+      });
+    });
+
+    it("should call onCreateHook with undefined key when not provided", () => {
+      const hookFn = vi.fn();
+      onCreateHook.override(() => hookFn);
+
+      const e = effect(() => {});
+
+      const effectCall = hookFn.mock.calls.find(
+        (call) => call[0].type === "effect"
+      );
+      expect(effectCall).toBeDefined();
+      expect(effectCall![0]).toEqual({
+        type: "effect",
+        key: undefined,
+        meta: undefined,
+        instance: e,
+      });
+    });
+
+    it("should not throw when onCreateHook is undefined", () => {
+      onCreateHook.reset();
+
+      expect(() => effect(() => {})).not.toThrow();
+    });
+
+    it("should call onCreateHook with effect instance that has working dispose", async () => {
+      const hookFn = vi.fn();
+      onCreateHook.override(() => hookFn);
+
+      const cleanupFn = vi.fn();
+      const count$ = atom(0);
+
+      effect(({ read, onCleanup }) => {
+        read(count$);
+        onCleanup(cleanupFn);
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Get the effect from the hook call (filter out the internal derived atom call)
+      const effectCall = hookFn.mock.calls.find(
+        (call) => call[0].type === "effect"
+      );
+      expect(effectCall).toBeDefined();
+      const capturedEffect = effectCall![0].instance as Effect;
+
+      // Dispose should work
+      capturedEffect.dispose();
+      expect(cleanupFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should pass correct type discriminator for effects", () => {
+      const hookFn = vi.fn();
+      onCreateHook.override(() => hookFn);
+
+      effect(() => {});
+
+      // Find the effect call (not the internal derived call)
+      const effectCall = hookFn.mock.calls.find(
+        (call) => call[0].type === "effect"
+      );
+      expect(effectCall).toBeDefined();
+      expect(effectCall![0].type).toBe("effect");
+    });
+
+    it("should allow tracking effects in devtools-like scenario", () => {
+      const effects = new Map<string, Effect>();
+      onCreateHook.override(() => (info) => {
+        if (info.type === "effect" && info.key) {
+          effects.set(info.key, info.instance);
+        }
+      });
+
+      const e1 = effect(() => {}, { meta: { key: "effect1" } });
+      const e2 = effect(() => {}, { meta: { key: "effect2" } });
+      effect(() => {}); // Anonymous - should not be tracked
+
+      expect(effects.size).toBe(2);
+      expect(effects.get("effect1")).toBe(e1);
+      expect(effects.get("effect2")).toBe(e2);
+    });
+
+    it("should support disposing all tracked effects", async () => {
+      const effects: Effect[] = [];
+      onCreateHook.override(() => (info) => {
+        if (info.type === "effect") {
+          effects.push(info.instance);
+        }
+      });
+
+      const cleanupFns = [vi.fn(), vi.fn(), vi.fn()];
+      const count$ = atom(0);
+
+      cleanupFns.forEach((cleanup) => {
+        effect(({ read, onCleanup }) => {
+          read(count$);
+          onCleanup(cleanup);
+        });
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Dispose all tracked effects
+      effects.forEach((e) => e.dispose());
+
+      cleanupFns.forEach((cleanup) => {
+        expect(cleanup).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("onError callback", () => {
+    it("should call onError when effect throws synchronously", async () => {
+      const onError = vi.fn();
+      const source$ = atom(0);
+
+      effect(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) {
+            throw new Error("Effect error");
+          }
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(onError).not.toHaveBeenCalled();
+
+      // Trigger error
+      source$.set(5);
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect((onError.mock.calls[0][0] as Error).message).toBe("Effect error");
+    });
+
+    it("should call onError when async atom dependency rejects", async () => {
+      const onError = vi.fn();
+
+      // Create an atom with a rejecting Promise
+      const asyncSource$ = atom(Promise.reject(new Error("Async error")));
+
+      effect(
+        ({ read }) => {
+          read(asyncSource$);
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect((onError.mock.calls[0][0] as Error).message).toBe("Async error");
+    });
+
+    it("should call onError on each recomputation that throws", async () => {
+      const onError = vi.fn();
+      const source$ = atom(0);
+
+      effect(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) {
+            throw new Error(`Error for ${val}`);
+          }
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(onError).not.toHaveBeenCalled();
+
+      // First error
+      source$.set(1);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(onError).toHaveBeenCalledTimes(1);
+
+      // Second error
+      source$.set(2);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(onError).toHaveBeenCalledTimes(2);
+      expect((onError.mock.calls[1][0] as Error).message).toBe("Error for 2");
+    });
+
+    it("should not call onError when effect succeeds", async () => {
+      const onError = vi.fn();
+      const effectFn = vi.fn();
+      const source$ = atom(5);
+
+      effect(
+        ({ read }) => {
+          effectFn(read(source$));
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      source$.set(10);
+      await new Promise((r) => setTimeout(r, 10));
+      source$.set(15);
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(effectFn).toHaveBeenCalledTimes(3);
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it("should not call onError for Promise throws (Suspense)", async () => {
+      const onError = vi.fn();
+      const effectFn = vi.fn();
+      let resolvePromise: (value: number) => void;
+      const asyncSource$ = atom(
+        new Promise<number>((resolve) => {
+          resolvePromise = resolve;
+        })
+      );
+
+      effect(
+        ({ read }) => {
+          effectFn(read(asyncSource$));
+        },
+        { onError }
+      );
+
+      // Still loading - onError should NOT be called
+      await new Promise((r) => setTimeout(r, 10));
+      expect(onError).not.toHaveBeenCalled();
+      expect(effectFn).not.toHaveBeenCalled();
+
+      // Resolve successfully
+      resolvePromise!(5);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledWith(5);
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it("should work without onError callback", async () => {
+      const source$ = atom(0);
+
+      // Should not throw even without onError
+      effect(({ read }) => {
+        const val = read(source$);
+        if (val > 0) {
+          throw new Error("Error");
+        }
+      });
+
+      await new Promise((r) => setTimeout(r, 0));
+      source$.set(5);
+      await new Promise((r) => setTimeout(r, 10));
+      // No crash - test passes
+    });
+
+    it("should allow combining onError with safe() for different error handling strategies", async () => {
+      const onError = vi.fn();
+      const handledErrors: unknown[] = [];
+      const source$ = atom(0);
+
+      effect(
+        ({ read, safe }) => {
+          const val = read(source$);
+
+          // Use safe() for recoverable errors
+          const [err] = safe(() => {
+            if (val === 1) {
+              throw new Error("Handled error");
+            }
+            return val;
+          });
+
+          if (err) {
+            handledErrors.push(err);
+            return;
+          }
+
+          // Unhandled errors go to onError
+          if (val === 2) {
+            throw new Error("Unhandled error");
+          }
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      // Handled error via safe()
+      source$.set(1);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(handledErrors.length).toBe(1);
+      expect(onError).not.toHaveBeenCalled();
+
+      // Unhandled error goes to onError
+      source$.set(2);
+      await new Promise((r) => setTimeout(r, 10));
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect((onError.mock.calls[0][0] as Error).message).toBe(
+        "Unhandled error"
+      );
+    });
+
+    it("should pass onError to internal derived atom", async () => {
+      // This test verifies the implementation detail that effect passes
+      // onError to the internal derived atom
+      const onError = vi.fn();
+      const source$ = atom(0);
+
+      effect(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) throw new Error("Test");
+        },
+        { onError }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      source$.set(1);
+      await new Promise((r) => setTimeout(r, 10));
+
+      // onError was called, proving it was passed to derived
+      expect(onError).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/core/effect.ts

@@ -1,8 +1,9 @@
 import { batch } from "./batch";
 import { derived } from "./derived";
 import { emitter } from "./emitter";
+import { EffectInfo, onCreateHook } from "./onCreateHook";
 import { ReactiveSelector, SelectContext } from "./select";
-import { EffectOptions } from "./types";
+import { EffectMeta, EffectOptions } from "./types";
 import { WithReadySelectContext } from "./withReady";
 
 /**
@@ -27,6 +28,11 @@ export interface EffectContext extends SelectContext, WithReadySelectContext {
   onCleanup: (cleanup: VoidFunction) => void;
 }
 
+export interface Effect {
+  dispose: VoidFunction;
+  meta?: EffectMeta;
+}
+
 /**
  * Creates a side-effect that runs when accessed atom(s) change.
  *
@@ -120,42 +126,63 @@ export interface EffectContext extends SelectContext, WithReadySelectContext {
  */
 export function effect(
   fn: ReactiveSelector<void, EffectContext>,
-  _options?: EffectOptions
-): VoidFunction {
+  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.
-  const derivedAtom = derived((context) => {
-    // Run previous cleanup before next execution
-    cleanupEmitter.emitAndClear();
+  // 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;
+      // 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,
-      something: true,
-      onCleanup: cleanupEmitter.on,
-    } as unknown as EffectContext;
-    batch(() => fn(effectContext));
-  });
+      // 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)
-  // Ignore promise rejection - errors should be handled via safe()
-  derivedAtom.get().catch(() => {
-    // Silently ignore - use safe() for error handling
-  });
+  // Errors are handled via onError callback or safe() in the effect function
+  derivedAtom.get();
 
-  return () => {
-    // Guard against multiple dispose calls
-    if (disposed) return;
+  // Notify devtools/plugins of effect creation
+  onCreateHook.current?.(effectInfo);
 
-    // Mark as disposed
-    disposed = true;
-    // Run final cleanup
-    cleanupEmitter.emitAndClear();
-  };
+  return e;
 }

package/src/core/hook.test.ts

@@ -176,20 +176,20 @@ describe("hook", () => {
       const hookA = hook<string | undefined>();
       const hookB = hook<string | undefined>();
 
-      // Create custom setups that track release order
+      // Create custom setups that track release order using override/reset
       const setupA = () => {
-        hookA.current = "A";
+        hookA.override(() => "A");
         return () => {
           order.push("release A");
-          hookA.current = undefined;
+          hookA.reset();
         };
       };
 
       const setupB = () => {
-        hookB.current = "B";
+        hookB.override(() => "B");
         return () => {
           order.push("release B");
-          hookB.current = undefined;
+          hookB.reset();
         };
       };
 

package/src/core/hook.ts

@@ -56,7 +56,7 @@ export interface Hook<T> {
   /**
    * Current value of the hook. Direct property access for fast reads.
    */
-  current: T;
+  readonly current: T;
 
   /**
    * Override the current value using a reducer.