atomirx 0.0.2 → 0.0.5

package/dist/core/getAtomState.d.ts

@@ -0,0 +1,29 @@
+import { Atom, AtomState } 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 declare function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>>;

package/dist/core/hook.d.ts

@@ -54,7 +54,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.
      * The reducer receives the previous value and returns the next value.

package/dist/core/onCreateHook.d.ts

@@ -1,8 +1,9 @@
-import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta } from './types';
+import { Effect } from './effect';
+import { MutableAtomMeta, DerivedAtomMeta, 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) */
@@ -10,12 +11,12 @@ 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) */
@@ -23,16 +24,29 @@ 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) */
@@ -40,7 +54,7 @@ export interface ModuleCreateInfo {
     /** Optional metadata from define options */
     meta: ModuleMeta | undefined;
     /** The created module instance */
-    module: unknown;
+    instance: unknown;
 }
 /**
  * Global hook that fires whenever an atom or module is created.
@@ -50,30 +64,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 declare const onCreateHook: import('./hook').Hook<((info: AtomCreateInfo | ModuleCreateInfo) => void) | undefined>;
+export declare const onCreateHook: import('./hook').Hook<((info: CreateInfo | ModuleInfo) => void) | undefined>;

package/dist/core/onErrorHook.d.ts

@@ -0,0 +1,49 @@
+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 declare const onErrorHook: import('./hook').Hook<((info: ErrorInfo) => void) | undefined>;

package/dist/core/promiseCache.d.ts

@@ -1,4 +1,26 @@
-import { Atom, AtomState, DerivedAtom } from './types';
+import { DerivedAtom } from './types';
+/**
+ * Metadata attached to combined promises for comparison.
+ */
+export interface CombinedPromiseMeta {
+    type: "all" | "race" | "allSettled";
+    promises: Promise<unknown>[];
+}
+/**
+ * Gets the metadata for a combined promise, if any.
+ * Used internally by promisesEqual for comparison.
+ */
+export declare function getCombinedPromiseMetadata(promise: PromiseLike<unknown>): CombinedPromiseMeta | undefined;
+/**
+ * Create a combined promise with metadata for comparison.
+ * If only one promise, returns it directly (no metadata needed).
+ */
+export declare function createCombinedPromise(type: "all" | "race" | "allSettled", promises: Promise<unknown>[]): PromiseLike<unknown>;
+/**
+ * Compare two promises, considering combined promise metadata.
+ * Returns true if promises are considered equal.
+ */
+export declare function promisesEqual(a: PromiseLike<unknown> | undefined, b: PromiseLike<unknown> | undefined): boolean;
 /**
  * Represents the state of a tracked Promise.
  */
@@ -51,37 +73,6 @@ export declare function isTracked(promise: PromiseLike<unknown>): boolean;
  * Type guard to check if a value is a DerivedAtom.
  */
 export declare 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 declare function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>>;
 /**
  * Unwraps a value that may be a Promise.
  * - If not a Promise, returns the value directly.

package/dist/core/select.d.ts

@@ -1,4 +1,4 @@
-import { Atom, AtomValue, SettledResult } from './types';
+import { Atom, AtomValue, KeyedResult, Pipeable, SelectStateResult, SettledResult } from './types';
 /**
  * Result of a select computation.
  *
@@ -14,11 +14,16 @@ export interface SelectResult<T> {
     /** Set of atoms that were accessed during computation */
     dependencies: Set<Atom<unknown>>;
 }
+/**
+ * Result type for safe() - error-first tuple.
+ * Either [undefined, T] for success or [unknown, undefined] for error.
+ */
+export type SafeResult<T> = [error: undefined, result: T] | [error: unknown, result: undefined];
 /**
  * Context object passed to selector functions.
  * Provides utilities for reading atoms and handling async operations.
  */
-export interface SelectContext {
+export interface SelectContext extends Pipeable {
     /**
      * Read the current value of an atom.
      * Tracks the atom as a dependency.
@@ -31,74 +36,180 @@ export interface SelectContext {
      * @param atom - The atom to read
      * @returns The atom's current value (Awaited<T>)
      */
-    get<T>(atom: Atom<T>): Awaited<T>;
+    read<T>(atom: Atom<T>): Awaited<T>;
     /**
      * Wait for all atoms to resolve (like Promise.all).
-     * Variadic form - pass atoms as arguments.
+     * Array-based - pass atoms as an array.
      *
      * - If all atoms are ready → returns array of values
      * - If any atom has error → throws that error
      * - If any atom is loading (no fallback) → throws Promise
      * - If loading with fallback → uses staleValue
      *
-     * @param atoms - Atoms to wait for (variadic)
+     * @param atoms - Array of atoms to wait for
      * @returns Array of resolved values (same order as input)
      *
      * @example
      * ```ts
-     * const [user, posts] = all(user$, posts$);
+     * const [user, posts] = all([user$, posts$]);
      * ```
      */
-    all<A extends Atom<unknown>[]>(...atoms: A): {
+    all<A extends Atom<unknown>[]>(atoms: A): {
         [K in keyof A]: AtomValue<A[K]>;
     };
     /**
      * Return the first settled value (like Promise.race).
-     * Variadic form - pass atoms as arguments.
+     * Object-based - pass atoms as a record with keys.
      *
-     * - If any atom is ready → returns first ready value
+     * - If any atom is ready → returns `{ key, value }` for first ready
      * - If any atom has error → throws first error
      * - If all atoms are loading → throws first Promise
      *
+     * The `key` in the result identifies which atom won the race.
+     *
      * Note: race() does NOT use fallback - it's meant for first "real" settled value.
      *
-     * @param atoms - Atoms to race (variadic)
-     * @returns First settled value
+     * @param atoms - Record of atoms to race
+     * @returns KeyedResult with winning key and value
+     *
+     * @example
+     * ```ts
+     * const result = race({ cache: cache$, api: api$ });
+     * console.log(result.key);   // "cache" or "api"
+     * console.log(result.value); // The winning value
+     * ```
      */
-    race<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+    race<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
     /**
      * Return the first ready value (like Promise.any).
-     * Variadic form - pass atoms as arguments.
+     * Object-based - pass atoms as a record with keys.
      *
-     * - If any atom is ready → returns first ready value
+     * - If any atom is ready → returns `{ key, value }` for first ready
      * - If all atoms have errors → throws AggregateError
      * - If any loading (not all errored) → throws Promise
      *
+     * The `key` in the result identifies which atom resolved first.
+     *
      * Note: any() does NOT use fallback - it waits for a real ready value.
      *
-     * @param atoms - Atoms to check (variadic)
-     * @returns First ready value
+     * @param atoms - Record of atoms to check
+     * @returns KeyedResult with winning key and value
+     *
+     * @example
+     * ```ts
+     * const result = any({ primary: primaryApi$, fallback: fallbackApi$ });
+     * console.log(result.key);   // "primary" or "fallback"
+     * console.log(result.value); // The winning value
+     * ```
      */
-    any<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+    any<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
     /**
      * Get all atom statuses when all are settled (like Promise.allSettled).
-     * Variadic form - pass atoms as arguments.
+     * Array-based - pass atoms as an array.
      *
      * - If all atoms are settled → returns array of statuses
      * - If any atom is loading (no fallback) → throws Promise
      * - If loading with fallback → { status: "ready", value: staleValue }
      *
-     * @param atoms - Atoms to check (variadic)
+     * @param atoms - Array of atoms to check
      * @returns Array of settled results
+     *
+     * @example
+     * ```ts
+     * const [userResult, postsResult] = settled([user$, posts$]);
+     * ```
      */
-    settled<A extends Atom<unknown>[]>(...atoms: A): {
+    settled<A extends Atom<unknown>[]>(atoms: A): {
         [K in keyof A]: SettledResult<AtomValue<A[K]>>;
     };
+    /**
+     * Safely execute a function, catching errors but preserving Suspense.
+     *
+     * - If function succeeds → returns [undefined, result]
+     * - If function throws Error → returns [error, undefined]
+     * - If function throws Promise → re-throws (preserves Suspense)
+     *
+     * Use this when you need error handling inside selectors without
+     * accidentally catching Suspense promises.
+     *
+     * @param fn - Function to execute safely
+     * @returns Error-first tuple: [error, result]
+     *
+     * @example
+     * ```ts
+     * const data$ = derived(({ get, safe }) => {
+     *   const [err, data] = safe(() => {
+     *     const raw = get(raw$);
+     *     return JSON.parse(raw); // Can throw SyntaxError
+     *   });
+     *
+     *   if (err) {
+     *     return { error: err.message };
+     *   }
+     *   return { data };
+     * });
+     * ```
+     */
+    safe<T>(fn: () => T): SafeResult<T>;
+    /**
+     * Get the async state of an atom or selector without throwing.
+     *
+     * Unlike `read()` which throws promises/errors (Suspense pattern),
+     * `state()` always returns a `SelectStateResult<T>` object that you can
+     * inspect and handle inline.
+     *
+     * All properties (`status`, `value`, `error`) are always present,
+     * enabling easy destructuring:
+     * ```ts
+     * const { status, value, error } = state(atom$);
+     * ```
+     *
+     * @param atom - The atom to get state from
+     * @returns SelectStateResult with status, value, error (no promise - for equality)
+     *
+     * @example
+     * ```ts
+     * // Get state of single atom
+     * const dashboard$ = derived(({ state }) => {
+     *   const userState = state(user$);
+     *   const postsState = state(posts$);
+     *
+     *   return {
+     *     user: userState.value, // undefined if not ready
+     *     isLoading: userState.status === 'loading' || postsState.status === 'loading',
+     *   };
+     * });
+     * ```
+     */
+    state<T>(atom: Atom<T>): SelectStateResult<Awaited<T>>;
+    /**
+     * Get the async state of a selector function without throwing.
+     *
+     * Wraps the selector in try/catch and returns the result as a
+     * `SelectStateResult<T>` object. Useful for getting state of combined
+     * operations like `all()`, `race()`, etc.
+     *
+     * @param selector - Function that may throw promises or errors
+     * @returns SelectStateResult with status, value, error (no promise - for equality)
+     *
+     * @example
+     * ```ts
+     * // Get state of combined operation
+     * const allData$ = derived(({ state, all }) => {
+     *   const result = state(() => all(a$, b$, c$));
+     *
+     *   if (result.status === 'loading') return { loading: true };
+     *   if (result.status === 'error') return { error: result.error };
+     *   return { data: result.value };
+     * });
+     * ```
+     */
+    state<T>(selector: () => T): SelectStateResult<T>;
 }
 /**
  * Selector function type for context-based API.
  */
-export type ContextSelectorFn<T> = (context: SelectContext) => T;
+export type ReactiveSelector<T, C extends SelectContext = SelectContext> = (context: C) => T;
 /**
  * Custom error for when all atoms in `any()` are rejected.
  */
@@ -110,7 +221,7 @@ export declare class AllAtomsRejectedError extends Error {
  * Selects/computes a value from atom(s) with dependency tracking.
  *
  * This is the core computation logic used by `derived()`. It:
- * 1. Creates a context with `get`, `all`, `any`, `race`, `settled` utilities
+ * 1. Creates a context with `read`, `all`, `any`, `race`, `settled`, `safe` utilities
  * 2. Tracks which atoms are accessed during computation
  * 3. Returns a result with value/error/promise and dependencies
  *
@@ -123,29 +234,97 @@ export declare class AllAtomsRejectedError extends Error {
  * If your selector returns a Promise, it will throw an error. This is because:
  * - `select()` is designed for synchronous derivation from atoms
  * - Async atoms should be created using `atom(Promise)` directly
- * - Use `get()` to read async atoms - it handles Suspense-style loading
+ * - Use `read()` to read async atoms - it handles Suspense-style loading
  *
  * ```ts
  * // ❌ WRONG - Don't return a Promise from selector
  * select(({ get }) => fetch('/api/data'));
  *
- * // ✅ CORRECT - Create async atom and read with get()
+ * // ✅ CORRECT - Create async atom and read with read()
  * const data$ = atom(fetch('/api/data').then(r => r.json()));
- * select(({ get }) => get(data$)); // Suspends until resolved
+ * select(({ 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
+ * select(({ 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
+ * select(({ 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
+ *
+ * ## IMPORTANT: SelectContext Methods Are Synchronous Only
+ *
+ * **All context methods (`read`, `all`, `race`, `any`, `settled`, `safe`) must be
+ * called synchronously during selector execution.** They cannot be used in async
+ * callbacks like `setTimeout`, `Promise.then`, or event handlers.
+ *
+ * ```ts
+ * // ❌ WRONG - Calling read() in async callback
+ * select(({ read }) => {
+ *   setTimeout(() => {
+ *     read(atom$); // Error: called outside selection context
+ *   }, 100);
+ *   return 'value';
+ * });
+ *
+ * // ❌ WRONG - Storing read() for later use
+ * let savedRead;
+ * select(({ read }) => {
+ *   savedRead = read; // Don't do this!
+ *   return read(atom$);
+ * });
+ * savedRead(atom$); // Error: called outside selection context
+ *
+ * // ✅ CORRECT - For async access, use atom.get() directly
+ * effect(({ read }) => {
+ *   const config = read(config$);
+ *   setTimeout(async () => {
+ *     // Use atom.get() for async access
+ *     const data = await asyncAtom$.get();
+ *     console.log(data);
+ *   }, 100);
+ * });
  * ```
  *
  * @template T - The type of the computed value
  * @param fn - Context-based selector function (must return sync value)
  * @returns SelectResult with value, error, promise, and dependencies
  * @throws Error if selector returns a Promise or PromiseLike
+ * @throws Error if context methods are called outside selection context
  *
  * @example
  * ```ts
- * select(({ get, all }) => {
- *   const user = get(user$);
- *   const [posts, comments] = all(posts$, comments$);
+ * select(({ read, all }) => {
+ *   const user = read(user$);
+ *   const [posts, comments] = all([posts$, comments$]);
  *   return { user, posts, comments };
  * });
  * ```
  */
-export declare function select<T>(fn: ContextSelectorFn<T>): SelectResult<T>;
+export declare function select<T>(fn: ReactiveSelector<T>): SelectResult<T>;