atomirx 0.0.2 → 0.0.5

package/src/core/effect.ts

@@ -1,15 +1,16 @@
 import { batch } from "./batch";
 import { derived } from "./derived";
 import { emitter } from "./emitter";
-import { isPromiseLike } from "./isPromiseLike";
-import { SelectContext } from "./select";
-import { EffectOptions } from "./types";
+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 and error handling utilities.
+ * Extends `SelectContext` with cleanup utilities.
  */
-export interface EffectContext extends SelectContext {
+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.
@@ -18,36 +19,19 @@ export interface EffectContext extends SelectContext {
    *
    * @example
    * ```ts
-   * effect(({ get, onCleanup }) => {
+   * effect(({ read, onCleanup }) => {
    *   const id = setInterval(() => console.log('tick'), 1000);
    *   onCleanup(() => clearInterval(id));
    * });
    * ```
    */
   onCleanup: (cleanup: VoidFunction) => void;
-
-  /**
-   * Register an error handler for synchronous errors thrown in the effect.
-   * If registered, prevents errors from propagating to `options.onError`.
-   *
-   * @param handler - Function to handle errors
-   *
-   * @example
-   * ```ts
-   * effect(({ get, onError }) => {
-   *   onError((e) => console.error('Effect failed:', e));
-   *   riskyOperation();
-   * });
-   * ```
-   */
-  onError: (handler: (error: unknown) => void) => void;
 }
 
-/**
- * Callback function for effects.
- * Receives the effect context with `{ get, all, any, race, settled, onCleanup, onError }` utilities.
- */
-export type EffectFn = (context: EffectContext) => void;
+export interface Effect {
+  dispose: VoidFunction;
+  meta?: EffectMeta;
+}
 
 /**
  * Creates a side-effect that runs when accessed atom(s) change.
@@ -55,7 +39,7 @@ export type EffectFn = (context: EffectContext) => void;
  * 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 `get()`
+ * - **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
  *
@@ -65,23 +49,23 @@ export type EffectFn = (context: EffectContext) => void;
  *
  * ```ts
  * // ❌ WRONG - Don't use async function
- * effect(async ({ get }) => {
+ * effect(async ({ read }) => {
  *   const data = await fetch('/api');
  *   console.log(data);
  * });
  *
- * // ✅ 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()));
- * effect(({ get }) => {
- *   console.log(get(data$)); // Suspends until resolved
+ * effect(({ read }) => {
+ *   console.log(read(data$)); // Suspends until resolved
  * });
  * ```
  *
  * ## Basic Usage
  *
  * ```ts
- * const dispose = effect(({ get }) => {
- *   localStorage.setItem('count', String(get(countAtom)));
+ * const dispose = effect(({ read }) => {
+ *   localStorage.setItem('count', String(read(countAtom)));
  * });
  * ```
  *
@@ -90,95 +74,115 @@ export type EffectFn = (context: EffectContext) => void;
  * Use `onCleanup` to register cleanup functions that run before the next execution or on dispose:
  *
  * ```ts
- * const dispose = effect(({ get, onCleanup }) => {
- *   const interval = get(intervalAtom);
+ * const dispose = effect(({ read, onCleanup }) => {
+ *   const interval = read(intervalAtom);
  *   const id = setInterval(() => console.log('tick'), interval);
  *   onCleanup(() => clearInterval(id));
  * });
  * ```
  *
- * ## Error Handling
+ * ## IMPORTANT: Do NOT Use try/catch - Use safe() Instead
  *
- * Use `onError` callback to handle errors within the effect, or `options.onError` for unhandled errors:
+ * **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
- * // Callback-based error handling
- * const dispose = effect(({ get, onError }) => {
- *   onError((e) => console.error('Effect failed:', e));
- *   const data = get(dataAtom);
- *   riskyOperation(data);
+ * // ❌ 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!
+ *   }
  * });
  *
- * // Option-based error handling (for unhandled errors)
- * const dispose = effect(
- *   ({ get }) => {
- *     const data = get(dataAtom);
- *     riskyOperation(data);
- *   },
- *   { onError: (e) => console.error('Effect failed:', e) }
- * );
+ * // ✅ 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
+ * });
  * ```
  *
- * @param fn - Effect callback receiving context with `{ get, all, any, race, settled, onCleanup, onError }`.
+ * 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, onError for unhandled errors)
+ * @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: EffectFn, options?: EffectOptions): VoidFunction {
+export function effect(
+  fn: ReactiveSelector<void, EffectContext>,
+  options?: EffectOptions
+): Effect {
   let disposed = false;
   const cleanupEmitter = emitter();
-  const errorEmitter = emitter<unknown>();
+
+  // 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
-    errorEmitter.clear();
-    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;
 
-    try {
       // Run effect in a batch - multiple atom updates will only notify once
-      batch(() =>
-        fn({
-          ...context,
-          onCleanup: cleanupEmitter.on,
-          onError: errorEmitter.on,
-        })
-      );
-    } catch (error) {
-      if (isPromiseLike(error)) {
-        // let derived atom handle the promise
-        throw error;
-      }
-      // Emit to registered handlers, or fall back to options.onError
-      if (errorEmitter.size() > 0) {
-        errorEmitter.emitAndClear(error);
-      } else if (options?.onError && error instanceof Error) {
-        options.onError(error);
-      }
+      // 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 .value to trigger initial computation (derived is lazy)
-  // Handle the promise
-  derivedAtom.value.catch((error) => {
-    if (options?.onError && error instanceof Error) {
-      options.onError(error);
-    }
-    // Silently ignore if no error handler
-  });
+  // Access .get() to trigger initial computation (derived is lazy)
+  // 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;
-    errorEmitter.clear();
-    // Run final cleanup
-    cleanupEmitter.emitAndClear();
-  };
+  return e;
 }

package/src/core/getAtomState.ts

@@ -0,0 +1,69 @@
+import { isDerived } from "./isAtom";
+import { isPromiseLike } from "./isPromiseLike";
+import { trackPromise } from "./promiseCache";
+import { Atom, AtomState, DerivedAtom } from "./types";
+
+/**
+ * Returns the current state of an atom as a discriminated union.
+ *
+ * For any atom (mutable or derived):
+ * - 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>> {
+  if (isDerived(atom)) {
+    return (atom as DerivedAtom<Awaited<T>>).state();
+  }
+  const value = atom.get();
+
+  // 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>>,
+      };
+  }
+}

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.

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>();