atomirx 0.0.2 → 0.0.5

package/src/core/derived.ts

@@ -1,8 +1,9 @@
-import { onCreateHook } from "./onCreateHook";
+import { CreateInfo, DerivedInfo, onCreateHook } from "./onCreateHook";
 import { emitter } from "./emitter";
 import { resolveEquality } from "./equality";
+import { onErrorHook } from "./onErrorHook";
 import { scheduleNotifyHook } from "./scheduleNotifyHook";
-import { select, SelectContext } from "./select";
+import { ReactiveSelector, select, SelectContext } from "./select";
 import {
   Atom,
   AtomState,
@@ -12,21 +13,35 @@ import {
   SYMBOL_ATOM,
   SYMBOL_DERIVED,
 } from "./types";
+import { withReady, WithReadySelectContext } from "./withReady";
+
+/**
+ * Internal options for derived atoms.
+ * These are not part of the public API.
+ * @internal
+ */
+export interface DerivedInternalOptions {
+  /**
+   * Override the error source for onErrorHook.
+   * Used by effect() to attribute errors to the effect instead of the internal derived.
+   */
+  _errorSource?: CreateInfo;
+}
 
 /**
  * Context object passed to derived atom selector functions.
- * Provides utilities for reading atoms: `{ get, all, any, race, settled }`.
+ * Provides utilities for reading atoms: `{ read, all, any, race, settled }`.
  *
  * Currently identical to `SelectContext`, but defined separately to allow
  * future derived-specific extensions without breaking changes.
  */
-export interface DerivedContext extends SelectContext {}
+export interface DerivedContext extends SelectContext, WithReadySelectContext {}
 
 /**
  * Creates a derived (computed) atom from source atom(s).
  *
  * Derived atoms are **read-only** and automatically recompute when their
- * source atoms change. The `.value` property always returns a `Promise<T>`,
+ * source atoms change. The `.get()` method always returns a `Promise<T>`,
  * even for synchronous computations.
  *
  * ## IMPORTANT: Selector Must Return Synchronous Value
@@ -35,35 +50,68 @@ export interface DerivedContext extends SelectContext {}
  *
  * ```ts
  * // ❌ WRONG - Don't use async function
- * derived(async ({ get }) => {
+ * derived(async ({ read }) => {
  *   const data = await fetch('/api');
  *   return data;
  * });
  *
  * // ❌ WRONG - Don't return a Promise
- * derived(({ get }) => fetch('/api').then(r => r.json()));
+ * derived(({ read }) => fetch('/api').then(r => r.json()));
  *
- * // ✅ CORRECT - Create async atom and read with get()
+ * // ✅ CORRECT - Create async atom and read with read()
  * const data$ = atom(fetch('/api').then(r => r.json()));
- * derived(({ get }) => get(data$)); // Suspends until resolved
+ * derived(({ read }) => read(data$)); // Suspends until resolved
  * ```
  *
+ * ## 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
+ * derived(({ read }) => {
+ *   try {
+ *     return read(asyncAtom$);
+ *   } catch (e) {
+ *     return 'fallback'; // This catches BOTH errors AND loading promises!
+ *   }
+ * });
+ *
+ * // ✅ CORRECT - Use safe() to catch errors but preserve Suspense
+ * derived(({ read, safe }) => {
+ *   const [err, data] = safe(() => {
+ *     const raw = read(asyncAtom$);    // Can throw Promise (Suspense)
+ *     return JSON.parse(raw);          // Can throw Error
+ *   });
+ *
+ *   if (err) return { error: err.message };
+ *   return { data };
+ * });
+ * ```
+ *
+ * The `safe()` utility:
+ * - **Catches errors** and returns `[error, undefined]`
+ * - **Re-throws Promises** to preserve Suspense behavior
+ * - Returns `[undefined, result]` on success
+ *
  * ## Key Features
  *
- * 1. **Always async**: `.value` returns `Promise<T>`
+ * 1. **Always async**: `.get()` returns `Promise<T>`
  * 2. **Lazy computation**: Value is computed on first access
  * 3. **Automatic updates**: Recomputes when any source atom changes
  * 4. **Equality checking**: Only notifies if derived value changed
  * 5. **Fallback support**: Optional fallback for loading/error states
- * 6. **Suspense-like async**: `get()` throws promise if loading
+ * 6. **Suspense-like async**: `read()` throws promise if loading
  * 7. **Conditional dependencies**: Only subscribes to atoms accessed
  *
- * ## Suspense-Style get()
+ * ## Suspense-Style read()
  *
- * The `get()` function behaves like React Suspense:
- * - If source atom is **loading**: `get()` throws the promise
- * - If source atom has **error**: `get()` throws the error
- * - If source atom has **value**: `get()` returns the value
+ * The `read()` function behaves like React Suspense:
+ * - If source atom is **loading**: `read()` throws the promise
+ * - If source atom has **error**: `read()` throws the error
+ * - If source atom has **value**: `read()` returns the value
  *
  * @template T - Derived value type
  * @template F - Whether fallback is provided
@@ -75,9 +123,9 @@ export interface DerivedContext extends SelectContext {}
  * @example Basic derived (no fallback)
  * ```ts
  * const count$ = atom(5);
- * const doubled$ = derived(({ get }) => get(count$) * 2);
+ * const doubled$ = derived(({ read }) => read(count$) * 2);
  *
- * await doubled$.value; // 10
+ * await doubled$.get(); // 10
  * doubled$.staleValue;  // undefined (until first resolve) -> 10
  * doubled$.state();     // { status: "ready", value: 10 }
  * ```
@@ -85,7 +133,7 @@ export interface DerivedContext extends SelectContext {}
  * @example With fallback
  * ```ts
  * const posts$ = atom(fetchPosts());
- * const count$ = derived(({ get }) => get(posts$).length, { fallback: 0 });
+ * const count$ = derived(({ read }) => read(posts$).length, { fallback: 0 });
  *
  * count$.staleValue; // 0 (during loading) -> 42 (after resolve)
  * count$.state();    // { status: "loading", promise } during loading
@@ -105,27 +153,27 @@ export interface DerivedContext extends SelectContext {}
  *
  * @example Refresh
  * ```ts
- * const data$ = derived(({ get }) => get(source$));
+ * const data$ = derived(({ read }) => read(source$));
  * data$.refresh(); // Re-run computation
  * ```
  */
 
 // Overload: Without fallback - staleValue is T | undefined
 export function derived<T>(
-  fn: (ctx: DerivedContext) => T,
-  options?: DerivedOptions<T>
+  fn: ReactiveSelector<T, DerivedContext>,
+  options?: DerivedOptions<T> & DerivedInternalOptions
 ): DerivedAtom<T, false>;
 
 // Overload: With fallback - staleValue is guaranteed T
 export function derived<T>(
-  fn: (ctx: DerivedContext) => T,
-  options: DerivedOptions<T> & { fallback: T }
+  fn: ReactiveSelector<T, DerivedContext>,
+  options: DerivedOptions<T> & { fallback: T } & DerivedInternalOptions
 ): DerivedAtom<T, true>;
 
 // Implementation
 export function derived<T>(
-  fn: (ctx: DerivedContext) => T,
-  options: DerivedOptions<T> & { fallback?: T } = {}
+  fn: ReactiveSelector<T, DerivedContext>,
+  options: DerivedOptions<T> & { fallback?: T } & DerivedInternalOptions = {}
 ): DerivedAtom<T, boolean> {
   const changeEmitter = emitter();
   const eq = resolveEquality(options.equals as Equality<unknown>);
@@ -142,9 +190,30 @@ export function derived<T>(
   let isLoading = false;
   let version = 0;
 
+  // Store resolve/reject to allow reusing the same promise across recomputations
+  let resolvePromise: ((value: T) => void) | null = null;
+  let rejectPromise: ((error: unknown) => void) | null = null;
+
   // Track current subscriptions (atom -> unsubscribe function)
   const subscriptions = new Map<Atom<unknown>, VoidFunction>();
 
+  // CreateInfo for this derived - stored for onErrorHook
+  // Will be set after derivedAtom is created
+  let createInfo: DerivedInfo;
+
+  /**
+   * Handles errors by calling both the user's onError callback and the global onErrorHook.
+   */
+  const handleError = (error: unknown) => {
+    // Invoke user's error callback if provided
+    options.onError?.(error);
+
+    // Invoke global error hook
+    // Use _errorSource if provided (for effect), otherwise use this derived's createInfo
+    const source = options._errorSource ?? createInfo;
+    onErrorHook.current?.({ source, error });
+  };
+
   /**
    * Schedules notification to all subscribers.
    */
@@ -179,65 +248,104 @@ export function derived<T>(
 
   /**
    * Computes the derived value.
-   * Creates a new Promise that resolves when the computation completes.
+   * Reuses the existing Promise if loading (to prevent orphaned promises
+   * that React Suspense might be waiting on).
    */
   const compute = (silent = false) => {
     const computeVersion = ++version;
     isLoading = true;
     lastError = undefined; // Clear error when starting new computation
 
-    // Create a new promise for this computation
-    currentPromise = new Promise<T>((resolve, reject) => {
-      // Run select to compute value and track dependencies
-      const attemptCompute = () => {
-        const result = select(fn);
-
-        // Update subscriptions based on accessed deps
-        updateSubscriptions(result.dependencies);
-
-        if (result.promise) {
-          // Promise thrown - wait for it and retry
-          result.promise.then(
-            () => {
-              // Check if we're still the current computation
-              if (version !== computeVersion) return;
-              attemptCompute();
-            },
-            (error) => {
-              // Check if we're still the current computation
-              if (version !== computeVersion) return;
-              isLoading = false;
-              lastError = error;
-              reject(error);
-              if (!silent) notify();
-            }
-          );
-        } else if (result.error !== undefined) {
-          // Error thrown
-          isLoading = false;
-          lastError = result.error;
-          reject(result.error);
-          if (!silent) notify();
-        } else {
-          // Success - update lastResolved and resolve
-          const newValue = result.value as T;
-          isLoading = false;
-          lastError = undefined;
-
-          // Only update and notify if value changed
-          if (!lastResolved || !eq(newValue, lastResolved.value)) {
-            lastResolved = { value: newValue };
-            if (!silent) notify();
-          }
+    // Create a new promise if:
+    // 1. We don't have one yet, OR
+    // 2. The previous computation completed (resolved/rejected) and we need a new one
+    // This ensures we reuse promises while loading (for Suspense) but create fresh
+    // promises for new computations after completion
+    if (!resolvePromise) {
+      currentPromise = new Promise<T>((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+      });
+      // Prevent unhandled rejection warnings - errors are accessible via:
+      // 1. onError callback (if provided)
+      // 2. state() returning { status: "error", error }
+      // 3. .get().catch() by consumers
+      currentPromise.catch(() => {});
+    }
 
-          resolve(newValue);
+    // Run select to compute value and track dependencies
+    const attemptCompute = () => {
+      const result = select((context) => fn(context.use(withReady())));
+
+      // Update subscriptions based on accessed deps
+      updateSubscriptions(result.dependencies);
+
+      if (result.promise) {
+        // Notify subscribers that we're now in loading state
+        // This allows downstream derived atoms and useSelector to suspend
+        if (!silent) notify();
+        // Promise thrown - wait for it and retry
+        // Note: For never-resolving promises (from ready()), this .then() will never fire.
+        // But when a dependency changes, compute() is called again via subscription,
+        // and the new computation will run (with a new version).
+        result.promise.then(
+          () => {
+            // Check if we're still the current computation
+            if (version !== computeVersion) return;
+            attemptCompute();
+          },
+          (error) => {
+            // Check if we're still the current computation
+            if (version !== computeVersion) return;
+            isLoading = false;
+            lastError = error;
+            rejectPromise?.(error);
+            // Clear resolve/reject so next computation creates new promise
+            resolvePromise = null;
+            rejectPromise = null;
+            // Invoke error handlers
+            handleError(error);
+            // Always notify when promise rejects - subscribers need to know
+            // state changed from loading to error
+            notify();
+          }
+        );
+      } else if (result.error !== undefined) {
+        // Error thrown
+        isLoading = false;
+        lastError = result.error;
+        rejectPromise?.(result.error);
+        // Clear resolve/reject so next computation creates new promise
+        resolvePromise = null;
+        rejectPromise = null;
+        // Invoke error handlers
+        handleError(result.error);
+        if (!silent) notify();
+      } else {
+        // Success - update lastResolved and resolve
+        const newValue = result.value as T;
+        const wasFirstResolve = !lastResolved;
+        isLoading = false;
+        lastError = undefined;
+
+        // Only update and notify if value changed
+        if (!lastResolved || !eq(newValue, lastResolved.value)) {
+          lastResolved = { value: newValue };
+          // Always notify on first resolve (loading → ready transition)
+          // even if silent, because subscribers need to know state changed
+          if (wasFirstResolve || !silent) notify();
         }
-      };
 
-      attemptCompute();
-    });
+        resolvePromise?.(newValue);
+        // Clear resolve/reject so next computation creates new promise
+        resolvePromise = null;
+        rejectPromise = null;
+      }
+    };
+
+    attemptCompute();
 
-    return currentPromise;
+    return currentPromise!;
   };
 
   /**
@@ -258,10 +366,10 @@ export function derived<T>(
     meta: options.meta,
 
     /**
-     * The computed value as a Promise.
+     * Get the computed value as a Promise.
      * Always returns Promise<T>, even for sync computations.
      */
-    get value(): Promise<T> {
+    get(): Promise<T> {
       init();
       return currentPromise!;
     },
@@ -327,13 +435,16 @@ export function derived<T>(
     },
   };
 
-  // Notify devtools/plugins of derived atom creation
-  onCreateHook.current?.({
+  // Store createInfo for use in onErrorHook
+  createInfo = {
     type: "derived",
     key: options.meta?.key,
     meta: options.meta,
-    atom: derivedAtom,
-  });
+    instance: derivedAtom,
+  };
+
+  // Notify devtools/plugins of derived atom creation
+  onCreateHook.current?.(createInfo);
 
   return derivedAtom;
 }