atomirx 0.0.4 → 0.0.5

package/src/core/onCreateHook.ts

@@ -1,3 +1,4 @@
+import { Effect } from "./effect";
 import { hook } from "./hook";
 import {
   MutableAtomMeta,
@@ -5,12 +6,13 @@ import {
   MutableAtom,
   DerivedAtom,
   ModuleMeta,
+  EffectMeta,
 } from "./types";
 
 /**
  * Information provided when a mutable atom is created.
  */
-export interface MutableAtomCreateInfo {
+export interface MutableInfo {
   /** Discriminator for mutable atoms */
   type: "mutable";
   /** Optional key from atom options (for debugging/devtools) */
@@ -18,13 +20,13 @@ export interface MutableAtomCreateInfo {
   /** Optional metadata from atom options */
   meta: MutableAtomMeta | undefined;
   /** The created mutable atom instance */
-  atom: MutableAtom<unknown>;
+  instance: MutableAtom<unknown>;
 }
 
 /**
  * Information provided when a derived atom is created.
  */
-export interface DerivedAtomCreateInfo {
+export interface DerivedInfo {
   /** Discriminator for derived atoms */
   type: "derived";
   /** Optional key from derived options (for debugging/devtools) */
@@ -32,18 +34,32 @@ export interface DerivedAtomCreateInfo {
   /** Optional metadata from derived options */
   meta: DerivedAtomMeta | undefined;
   /** The created derived atom instance */
-  atom: DerivedAtom<unknown, boolean>;
+  instance: DerivedAtom<unknown, boolean>;
 }
 
 /**
- * Union type for atom creation info (mutable or derived).
+ * Information provided when an effect is created.
  */
-export type AtomCreateInfo = MutableAtomCreateInfo | DerivedAtomCreateInfo;
+export interface EffectInfo {
+  /** Discriminator for effects */
+  type: "effect";
+  /** Optional key from effect options (for debugging/devtools) */
+  key: string | undefined;
+  /** Optional metadata from effect options */
+  meta: EffectMeta | undefined;
+  /** The created effect instance */
+  instance: Effect;
+}
+
+/**
+ * Union type for atom/derived/effect creation info.
+ */
+export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo;
 
 /**
  * Information provided when a module (via define()) is created.
  */
-export interface ModuleCreateInfo {
+export interface ModuleInfo {
   /** Discriminator for modules */
   type: "module";
   /** Optional key from define options (for debugging/devtools) */
@@ -51,7 +67,7 @@ export interface ModuleCreateInfo {
   /** Optional metadata from define options */
   meta: ModuleMeta | undefined;
   /** The created module instance */
-  module: unknown;
+  instance: unknown;
 }
 
 /**
@@ -62,31 +78,30 @@ export interface ModuleCreateInfo {
  * - **Debugging** - log atom creation for troubleshooting
  * - **Testing** - verify expected atoms are created
  *
+ * **IMPORTANT**: Always use `.override()` to preserve the hook chain.
+ * Direct assignment to `.current` will break existing handlers.
+ *
  * @example Basic logging
  * ```ts
- * onCreateHook.current = (info) => {
+ * onCreateHook.override((prev) => (info) => {
+ *   prev?.(info); // call existing handlers first
  *   console.log(`Created ${info.type}: ${info.key ?? "anonymous"}`);
- * };
+ * });
  * ```
  *
  * @example DevTools integration
  * ```ts
- * const atoms = new Map();
- * const modules = new Map();
+ * const registry = new Map();
  *
- * onCreateHook.current = (info) => {
- *   if (info.type === "module") {
- *     modules.set(info.key, info.module);
- *   } else {
- *     atoms.set(info.key, info.atom);
- *   }
- * };
+ * onCreateHook.override((prev) => (info) => {
+ *   prev?.(info); // preserve chain
+ *   registry.set(info.key, info.instance);
+ * });
  * ```
  *
- * @example Cleanup (disable hook)
+ * @example Reset to default (disable all handlers)
  * ```ts
- * onCreateHook.current = undefined;
+ * onCreateHook.reset();
  * ```
  */
-export const onCreateHook =
-  hook<(info: AtomCreateInfo | ModuleCreateInfo) => void>();
+export const onCreateHook = hook<(info: CreateInfo | ModuleInfo) => void>();

package/src/core/onErrorHook.test.ts

@@ -0,0 +1,350 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { atom } from "./atom";
+import { derived } from "./derived";
+import { effect } from "./effect";
+import { onErrorHook, ErrorInfo } from "./onErrorHook";
+
+describe("onErrorHook", () => {
+  beforeEach(() => {
+    onErrorHook.reset();
+  });
+
+  afterEach(() => {
+    onErrorHook.reset();
+  });
+
+  describe("with derived", () => {
+    it("should call onErrorHook when derived throws synchronously", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(0);
+      const derived$ = derived(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) {
+            throw new Error("Derived error");
+          }
+          return val;
+        },
+        { meta: { key: "testDerived" } }
+      );
+
+      await derived$.get();
+      expect(hookFn).not.toHaveBeenCalled();
+
+      // Trigger error
+      source$.set(5);
+      derived$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(hookFn).toHaveBeenCalledTimes(1);
+      const info: ErrorInfo = hookFn.mock.calls[0][0];
+      expect(info.source.type).toBe("derived");
+      expect(info.source.key).toBe("testDerived");
+      expect((info.error as Error).message).toBe("Derived error");
+    });
+
+    it("should call onErrorHook when async dependency rejects", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const asyncSource$ = atom(Promise.reject(new Error("Async error")));
+
+      const derived$ = derived(({ read }) => read(asyncSource$), {
+        meta: { key: "asyncDerived" },
+      });
+
+      derived$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(hookFn).toHaveBeenCalledTimes(1);
+      const info: ErrorInfo = hookFn.mock.calls[0][0];
+      expect(info.source.type).toBe("derived");
+      expect(info.source.key).toBe("asyncDerived");
+      expect((info.error as Error).message).toBe("Async error");
+    });
+
+    it("should include derived atom in source", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(1);
+      const derived$ = derived(({ read }) => {
+        throw new Error("Test");
+        return read(source$);
+      });
+
+      derived$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 0));
+
+      const info: ErrorInfo = hookFn.mock.calls[0][0];
+      expect(info.source.type).toBe("derived");
+      if (info.source.type === "derived") {
+        expect(info.source.instance).toBe(derived$);
+      }
+    });
+
+    it("should call both onError option and onErrorHook", async () => {
+      const hookFn = vi.fn();
+      const onErrorFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(0);
+      const derived$ = derived(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) throw new Error("Error");
+          return val;
+        },
+        { onError: onErrorFn }
+      );
+
+      await derived$.get();
+      source$.set(1);
+      derived$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(onErrorFn).toHaveBeenCalledTimes(1);
+      expect(hookFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("with effect", () => {
+    it("should call onErrorHook with effect source when effect throws", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(0);
+
+      effect(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) {
+            throw new Error("Effect error");
+          }
+        },
+        { meta: { key: "testEffect" } }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      expect(hookFn).not.toHaveBeenCalled();
+
+      // Trigger error
+      source$.set(5);
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(hookFn).toHaveBeenCalledTimes(1);
+      const info: ErrorInfo = hookFn.mock.calls[0][0];
+      expect(info.source.type).toBe("effect"); // Should be effect, not derived!
+      expect(info.source.key).toBe("testEffect");
+      expect((info.error as Error).message).toBe("Effect error");
+    });
+
+    it("should include effect instance in source", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(1);
+      const e = effect(
+        ({ read }) => {
+          read(source$);
+          throw new Error("Test");
+        },
+        { meta: { key: "myEffect" } }
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const info: ErrorInfo = hookFn.mock.calls[0][0];
+      expect(info.source.type).toBe("effect");
+      if (info.source.type === "effect") {
+        expect(info.source.instance).toBe(e);
+      }
+    });
+
+    it("should call both onError option and onErrorHook for effect", async () => {
+      const hookFn = vi.fn();
+      const onErrorFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      const source$ = atom(0);
+
+      effect(
+        ({ read }) => {
+          const val = read(source$);
+          if (val > 0) throw new Error("Error");
+        },
+        { onError: onErrorFn }
+      );
+
+      await new Promise((r) => setTimeout(r, 0));
+      source$.set(1);
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(onErrorFn).toHaveBeenCalledTimes(1);
+      expect(hookFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("hook behavior", () => {
+    it("should not throw when onErrorHook is not set", async () => {
+      // Hook is reset in beforeEach, so no handler is set
+
+      const source$ = atom(1);
+      const derived$ = derived(({ read }) => {
+        throw new Error("Test");
+        return read(source$);
+      });
+
+      // Should not throw
+      derived$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 0));
+    });
+
+    it("should support middleware pattern with override", async () => {
+      const errors: ErrorInfo[] = [];
+
+      // First handler
+      onErrorHook.override(() => (info) => {
+        errors.push({ ...info, error: "first" });
+      });
+
+      // Add middleware - chains with previous
+      onErrorHook.override((prev) => (info) => {
+        prev?.(info);
+        errors.push({ ...info, error: "second" });
+      });
+
+      const source$ = atom(1);
+      derived(({ read }) => {
+        throw new Error("Test");
+        return read(source$);
+      })
+        .get()
+        .catch(() => {});
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(errors.length).toBe(2);
+      expect(errors[0].error).toBe("first");
+      expect(errors[1].error).toBe("second");
+    });
+
+    it("should support reset", async () => {
+      const hookFn = vi.fn();
+      onErrorHook.override(() => hookFn);
+
+      onErrorHook.reset();
+
+      const source$ = atom(1);
+      derived(({ read }) => {
+        throw new Error("Test");
+        return read(source$);
+      })
+        .get()
+        .catch(() => {});
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(hookFn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("real-world scenarios", () => {
+    it("should enable global error logging", async () => {
+      const errorLog: Array<{ type: string; key?: string; error: string }> = [];
+
+      onErrorHook.override(() => (info) => {
+        errorLog.push({
+          type: info.source.type,
+          key: info.source.key,
+          error: String(info.error),
+        });
+      });
+
+      const source$ = atom(0);
+
+      // Create multiple derived/effects that will error
+      const derived1$ = derived(
+        ({ read }) => {
+          if (read(source$) > 0) throw new Error("Derived 1 failed");
+          return read(source$);
+        },
+        { meta: { key: "derived1" } }
+      );
+
+      const derived2$ = derived(
+        ({ read }) => {
+          if (read(source$) > 0) throw new Error("Derived 2 failed");
+          return read(source$);
+        },
+        { meta: { key: "derived2" } }
+      );
+
+      effect(
+        ({ read }) => {
+          if (read(source$) > 0) throw new Error("Effect 1 failed");
+        },
+        { meta: { key: "effect1" } }
+      );
+
+      // Trigger initial computation for derived atoms (they're lazy)
+      await derived1$.get();
+      await derived2$.get();
+      await new Promise((r) => setTimeout(r, 0));
+      expect(errorLog.length).toBe(0);
+
+      // Trigger all errors
+      source$.set(1);
+      derived1$.get().catch(() => {});
+      derived2$.get().catch(() => {});
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(errorLog.length).toBe(3);
+      expect(errorLog.map((e) => e.key).sort()).toEqual([
+        "derived1",
+        "derived2",
+        "effect1",
+      ]);
+    });
+
+    it("should enable error monitoring service integration", async () => {
+      const sentryMock = {
+        captureException: vi.fn(),
+      };
+
+      onErrorHook.override(() => (info) => {
+        sentryMock.captureException(info.error, {
+          tags: {
+            source_type: info.source.type,
+            source_key: info.source.key,
+          },
+        });
+      });
+
+      const source$ = atom(1);
+      derived(
+        ({ read }) => {
+          throw new Error("Critical error");
+          return read(source$);
+        },
+        { meta: { key: "criticalDerived" } }
+      )
+        .get()
+        .catch(() => {});
+
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(sentryMock.captureException).toHaveBeenCalledWith(
+        expect.any(Error),
+        {
+          tags: {
+            source_type: "derived",
+            source_key: "criticalDerived",
+          },
+        }
+      );
+    });
+  });
+});

package/src/core/onErrorHook.ts

@@ -0,0 +1,52 @@
+import { hook } from "./hook";
+import { CreateInfo } from "./onCreateHook";
+
+/**
+ * Information provided when an error occurs in an atom, derived, or effect.
+ */
+export interface ErrorInfo {
+  /** The source that produced the error (atom, derived, or effect) */
+  source: CreateInfo;
+  /** The error that was thrown */
+  error: unknown;
+}
+
+/**
+ * Global hook that fires whenever an error occurs in a derived atom or effect.
+ *
+ * This is useful for:
+ * - **Global error logging** - capture all errors in one place
+ * - **Error monitoring** - send errors to monitoring services (Sentry, etc.)
+ * - **DevTools integration** - show errors in developer tools
+ * - **Debugging** - track which atoms/effects are failing
+ *
+ * **IMPORTANT**: Always use `.override()` to preserve the hook chain.
+ * Direct assignment to `.current` will break existing handlers.
+ *
+ * @example Basic logging
+ * ```ts
+ * onErrorHook.override((prev) => (info) => {
+ *   prev?.(info); // call existing handlers first
+ *   console.error(`Error in ${info.source.type}: ${info.source.key ?? "anonymous"}`, info.error);
+ * });
+ * ```
+ *
+ * @example Send to monitoring service
+ * ```ts
+ * onErrorHook.override((prev) => (info) => {
+ *   prev?.(info); // preserve chain
+ *   Sentry.captureException(info.error, {
+ *     tags: {
+ *       source_type: info.source.type,
+ *       source_key: info.source.key,
+ *     },
+ *   });
+ * });
+ * ```
+ *
+ * @example Reset to default (disable all handlers)
+ * ```ts
+ * onErrorHook.reset();
+ * ```
+ */
+export const onErrorHook = hook<(info: ErrorInfo) => void>();

package/src/core/types.ts

@@ -47,9 +47,8 @@ export interface Pipeable {
 /**
  * Optional metadata for atoms.
  */
-export interface AtomMeta {
+export interface AtomMeta extends AtomirxMeta {
   key?: string;
-  [key: string]: unknown;
 }
 
 /**
@@ -278,13 +277,64 @@ export interface DerivedOptions<T> {
   meta?: DerivedAtomMeta;
   /** Equality strategy for change detection (default: "strict") */
   equals?: Equality<T>;
+  /**
+   * Callback invoked when the derived computation throws an error.
+   * This is called for actual errors, NOT for Promise throws (Suspense).
+   *
+   * @param error - The error thrown during computation
+   *
+   * @example
+   * ```ts
+   * const data$ = derived(
+   *   ({ read }) => {
+   *     const raw = read(source$);
+   *     return JSON.parse(raw); // May throw SyntaxError
+   *   },
+   *   {
+   *     onError: (error) => {
+   *       console.error('Derived computation failed:', error);
+   *       reportToSentry(error);
+   *     }
+   *   }
+   * );
+   * ```
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
  * Configuration options for effects.
  */
 export interface EffectOptions {
-  /** Optional key for debugging */
+  meta?: EffectMeta;
+  /**
+   * Callback invoked when the effect computation throws an error.
+   * This is called for actual errors, NOT for Promise throws (Suspense).
+   *
+   * @param error - The error thrown during effect execution
+   *
+   * @example
+   * ```ts
+   * effect(
+   *   ({ read }) => {
+   *     const data = read(source$);
+   *     riskyOperation(data); // May throw
+   *   },
+   *   {
+   *     onError: (error) => {
+   *       console.error('Effect failed:', error);
+   *       showErrorNotification(error);
+   *     }
+   *   }
+   * );
+   * ```
+   */
+  onError?: (error: unknown) => void;
+}
+
+export interface AtomirxMeta {}
+
+export interface EffectMeta extends AtomirxMeta {
   key?: string;
 }