atomirx 0.0.2 → 0.0.4

package/dist/core/atom.d.ts

@@ -1,9 +1,27 @@
-import { AtomOptions, MutableAtom } from './types';
+import { AtomOptions, MutableAtom, Pipeable, Atom } from './types';
+/**
+ * Context object passed to atom initializer functions.
+ * Provides utilities for cleanup and cancellation.
+ */
+export interface AtomContext extends Pipeable {
+    /**
+     * AbortSignal that is aborted when the atom value changes (via set or reset).
+     * Use this to cancel pending async operations.
+     */
+    signal: AbortSignal;
+    /**
+     * Register a cleanup function that runs when the atom value changes or resets.
+     * Multiple cleanup functions can be registered; they run in FIFO order.
+     *
+     * @param cleanup - Function to run during cleanup
+     */
+    onCleanup(cleanup: VoidFunction): void;
+}
 /**
  * Creates a mutable atom - a reactive state container that holds a single value.
  *
  * MutableAtom is a raw storage container. It stores values as-is, including Promises.
- * If you store a Promise, `.value` returns the Promise object itself.
+ * If you store a Promise, `.get()` returns the Promise object itself.
  *
  * Features:
  * - Raw storage: stores any value including Promises
@@ -17,14 +35,14 @@ import { AtomOptions, MutableAtom } from './types';
  * @param options - Configuration options
  * @param options.meta - Optional metadata for debugging/devtools
  * @param options.equals - Equality strategy for change detection (default: strict)
- * @returns A mutable atom with value, set/reset methods
+ * @returns A mutable atom with get, set/reset methods
  *
  * @example Synchronous value
  * ```ts
  * const count = atom(0);
  * count.set(1);
  * count.set(prev => prev + 1);
- * console.log(count.value); // 2
+ * console.log(count.get()); // 2
  * ```
  *
  * @example Lazy initialization
@@ -43,7 +61,7 @@ import { AtomOptions, MutableAtom } from './types';
  * @example Async value (stores Promise as-is)
  * ```ts
  * const posts = atom(fetchPosts());
- * posts.value; // Promise<Post[]>
+ * posts.get(); // Promise<Post[]>
  *
  * // Refetch - set a new Promise
  * posts.set(fetchPosts());
@@ -60,4 +78,63 @@ import { AtomOptions, MutableAtom } from './types';
  * state.set(prev => ({ ...prev })); // No notification (shallow equal)
  * ```
  */
-export declare function atom<T>(valueOrInit: T | (() => T), options?: AtomOptions<T>): MutableAtom<T>;
+export declare function atom<T>(valueOrInit: T | ((context: AtomContext) => T), options?: AtomOptions<T>): MutableAtom<T>;
+/**
+ * Type utility to expose an atom as read-only when exporting from a module.
+ *
+ * This function returns the same atom instance but with a narrowed type (`Atom<T>`)
+ * that hides mutable methods like `set()` and `reset()`. Use this to encapsulate
+ * state mutations within a module while allowing external consumers to only read
+ * and subscribe to changes.
+ *
+ * **Note:** This is a compile-time restriction only. At runtime, the atom is unchanged.
+ * Consumers with access to the original reference can still mutate it.
+ *
+ * @param atom - The atom (or record of atoms) to expose as read-only
+ * @returns The same atom(s) with a read-only type signature
+ *
+ * @example Single atom
+ * ```ts
+ * const myModule = define(() => {
+ *   const count$ = atom(0); // Internal mutable atom
+ *
+ *   return {
+ *     // Expose as read-only - consumers can't call set() or reset()
+ *     count$: readonly(count$),
+ *     // Mutations only possible through explicit actions
+ *     increment: () => count$.set(prev => prev + 1),
+ *     decrement: () => count$.set(prev => prev - 1),
+ *   };
+ * });
+ *
+ * // Usage:
+ * const { count$, increment } = myModule();
+ * count$.get();        // ✅ OK - reading is allowed
+ * count$.on(console.log); // ✅ OK - subscribing is allowed
+ * count$.set(5);       // ❌ TypeScript error - set() not available on Atom<T>
+ * increment();         // ✅ OK - use exposed action instead
+ * ```
+ *
+ * @example Record of atoms
+ * ```ts
+ * const myModule = define(() => {
+ *   const count$ = atom(0);
+ *   const name$ = atom('');
+ *
+ *   return {
+ *     // Expose multiple atoms as read-only at once
+ *     ...readonly({ count$, name$ }),
+ *     setName: (name: string) => name$.set(name),
+ *   };
+ * });
+ *
+ * // Usage:
+ * const { count$, name$, setName } = myModule();
+ * count$.get();  // ✅ Atom<number>
+ * name$.get();   // ✅ Atom<string>
+ * name$.set(''); // ❌ TypeScript error
+ * ```
+ */
+export declare function readonly<T extends Atom<any> | Record<string, Atom<any>>>(atom: T): T extends Atom<infer V> ? Atom<V> : {
+    [K in keyof T]: T[K] extends Atom<infer V> ? Atom<V> : never;
+};

package/dist/core/batch.d.ts

@@ -54,7 +54,7 @@
  * ```ts
  * const counter = atom(0);
  *
- * counter.on(() => console.log("Counter:", counter.value));
+ * counter.on(() => console.log("Counter:", counter.get()));
  *
  * batch(() => {
  *   counter.set(1);
@@ -70,7 +70,7 @@
  * const b = atom(0);
  *
  * // Same listener subscribed to both atoms
- * const listener = () => console.log("Changed!", a.value, b.value);
+ * const listener = () => console.log("Changed!", a.get(), b.get());
  * a.on(listener);
  * b.on(listener);
  *
@@ -98,7 +98,7 @@
  * ```ts
  * const result = batch(() => {
  *   counter.set(10);
- *   return counter.value * 2;
+ *   return counter.get() * 2;
  * });
  * console.log(result); // 20
  * ```

package/dist/core/derived.d.ts

@@ -1,19 +1,20 @@
-import { SelectContext } from './select';
+import { ReactiveSelector, SelectContext } from './select';
 import { DerivedAtom, DerivedOptions } from './types';
+import { WithReadySelectContext } from './withReady';
 /**
  * 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
@@ -22,35 +23,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
@@ -62,9 +96,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 }
  * ```
@@ -72,7 +106,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
@@ -92,11 +126,11 @@ 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
  * ```
  */
-export declare function derived<T>(fn: (ctx: DerivedContext) => T, options?: DerivedOptions<T>): DerivedAtom<T, false>;
-export declare function derived<T>(fn: (ctx: DerivedContext) => T, options: DerivedOptions<T> & {
+export declare function derived<T>(fn: ReactiveSelector<T, DerivedContext>, options?: DerivedOptions<T>): DerivedAtom<T, false>;
+export declare function derived<T>(fn: ReactiveSelector<T, DerivedContext>, options: DerivedOptions<T> & {
     fallback: T;
 }): DerivedAtom<T, true>;

package/dist/core/effect.d.ts

@@ -1,10 +1,11 @@
-import { SelectContext } from './select';
+import { ReactiveSelector, SelectContext } from './select';
 import { 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.
@@ -13,41 +14,21 @@ 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;
 /**
  * Creates a side-effect that runs when accessed atom(s) change.
  *
  * 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
  *
@@ -57,23 +38,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)));
  * });
  * ```
  *
@@ -82,39 +63,54 @@ 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 declare function effect(fn: EffectFn, options?: EffectOptions): VoidFunction;
+export declare function effect(fn: ReactiveSelector<void, EffectContext>, _options?: EffectOptions): VoidFunction;

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/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.