atomirx 0.0.2 → 0.0.5

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/promiseCache.test.ts

@@ -7,9 +7,9 @@ import {
   isFulfilled,
   isRejected,
   unwrap,
-  getAtomState,
   isDerived,
 } from "./promiseCache";
+import { getAtomState } from "./getAtomState";
 import { atom } from "./atom";
 import { derived } from "./derived";
 
@@ -187,7 +187,7 @@ describe("promiseCache", () => {
 
     it("should return true for derived atom", () => {
       const a$ = atom(0);
-      const d$ = derived(({ get }) => get(a$) * 2);
+      const d$ = derived(({ read }) => read(a$) * 2);
       expect(isDerived(d$)).toBe(true);
     });
 
@@ -227,7 +227,9 @@ describe("promiseCache", () => {
 
     it("should return loading state for derived with fallback during loading", async () => {
       const asyncValue$ = atom(new Promise<number>(() => {}));
-      const derived$ = derived(({ get }) => get(asyncValue$), { fallback: 0 });
+      const derived$ = derived(({ read }) => read(asyncValue$), {
+        fallback: 0,
+      });
 
       // Derived atoms return their state directly via state()
       // State is loading, but staleValue provides the fallback

package/src/core/promiseCache.ts

@@ -1,5 +1,80 @@
+import { shallow2Equal } from "./equality";
 import { isPromiseLike } from "./isPromiseLike";
-import { Atom, AtomState, DerivedAtom, SYMBOL_DERIVED } from "./types";
+import { AnyFunc, DerivedAtom, SYMBOL_DERIVED } from "./types";
+
+/**
+ * Metadata attached to combined promises for comparison.
+ */
+export interface CombinedPromiseMeta {
+  type: "all" | "race" | "allSettled";
+  promises: Promise<unknown>[];
+}
+
+/**
+ * WeakMap cache for combined promise metadata.
+ * Using WeakMap allows promises to be garbage collected when no longer referenced.
+ */
+const combinedPromiseCache = new WeakMap<
+  PromiseLike<unknown>,
+  CombinedPromiseMeta
+>();
+
+/**
+ * Gets the metadata for a combined promise, if any.
+ * Used internally by promisesEqual for comparison.
+ */
+export function getCombinedPromiseMetadata(
+  promise: PromiseLike<unknown>
+): CombinedPromiseMeta | undefined {
+  return combinedPromiseCache.get(promise);
+}
+
+/**
+ * Create a combined promise with metadata for comparison.
+ * If only one promise, returns it directly (no metadata needed).
+ */
+export function createCombinedPromise(
+  type: "all" | "race" | "allSettled",
+  promises: Promise<unknown>[]
+): PromiseLike<unknown> {
+  if (promises.length === 1) {
+    // Single promise - no need for metadata, just return it
+    // For allSettled, we still need to wrap to prevent rejection propagation
+    if (type === "allSettled") {
+      const combined = Promise.allSettled(promises).then(() => undefined);
+      combinedPromiseCache.set(combined, { type, promises });
+      return combined;
+    }
+    return promises[0];
+  }
+
+  const combined = (Promise[type] as AnyFunc)(promises);
+  // Attach no-op catch to prevent unhandled rejection warnings
+  combined.catch(() => {});
+  combinedPromiseCache.set(combined, { type, promises });
+  return combined;
+}
+
+/**
+ * Compare two promises, considering combined promise metadata.
+ * Returns true if promises are considered equal.
+ */
+export function promisesEqual(
+  a: PromiseLike<unknown> | undefined,
+  b: PromiseLike<unknown> | undefined
+): boolean {
+  // Same reference
+  if (a === b) return true;
+
+  // One is undefined
+  if (!a || !b) return false;
+
+  // Compare by metadata (type + source promises array)
+  const metaA = getCombinedPromiseMetadata(a);
+  const metaB = getCombinedPromiseMetadata(b);
+
+  return !!metaA && !!metaB && shallow2Equal(metaA, metaB);
+}
 
 /**
  * Represents the state of a tracked Promise.
@@ -98,76 +173,6 @@ export function isDerived<T>(value: unknown): value is DerivedAtom<T, boolean> {
   );
 }
 
-/**
- * Returns the current state of an atom as a discriminated union.
- *
- * For DerivedAtom:
- * - Returns atom.state() directly (derived atoms track their own state)
- *
- * For MutableAtom:
- * - If value is not a Promise: returns ready state
- * - If value is a Promise: tracks and returns its state (ready/error/loading)
- *
- * @param atom - The atom to get state from
- * @returns AtomState discriminated union (ready | error | loading)
- *
- * @example
- * ```ts
- * const state = getAtomState(myAtom$);
- *
- * switch (state.status) {
- *   case "ready":
- *     console.log(state.value); // T
- *     break;
- *   case "error":
- *     console.log(state.error);
- *     break;
- *   case "loading":
- *     console.log(state.promise);
- *     break;
- * }
- * ```
- */
-export function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>> {
-  // For derived atoms, use their own state method
-  if (isDerived<T>(atom)) {
-    return atom.state() as AtomState<Awaited<T>>;
-  }
-
-  const value = atom.value;
-
-  // 1. Sync value - ready
-  if (!isPromiseLike(value)) {
-    return {
-      status: "ready",
-      value: value as Awaited<T>,
-    };
-  }
-
-  // 2. Promise value - check state via promiseCache
-  const state = trackPromise(value);
-
-  switch (state.status) {
-    case "fulfilled":
-      return {
-        status: "ready",
-        value: state.value as Awaited<T>,
-      };
-
-    case "rejected":
-      return {
-        status: "error",
-        error: state.error,
-      };
-
-    case "pending":
-      return {
-        status: "loading",
-        promise: state.promise as Promise<Awaited<T>>,
-      };
-  }
-}
-
 /**
  * Unwraps a value that may be a Promise.
  * - If not a Promise, returns the value directly.