npm - atomirx - Versions diffs - 0.0.2 → 0.0.5 - Mend

atomirx 0.0.2 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

package/README.md +868 -161
package/coverage/src/core/onCreateHook.ts.html +72 -70
package/dist/core/atom.d.ts +83 -6
package/dist/core/batch.d.ts +3 -3
package/dist/core/derived.d.ts +69 -22
package/dist/core/effect.d.ts +52 -52
package/dist/core/getAtomState.d.ts +29 -0
package/dist/core/hook.d.ts +1 -1
package/dist/core/onCreateHook.d.ts +37 -23
package/dist/core/onErrorHook.d.ts +49 -0
package/dist/core/promiseCache.d.ts +23 -32
package/dist/core/select.d.ts +208 -29
package/dist/core/types.d.ts +107 -22
package/dist/core/withReady.d.ts +115 -0
package/dist/core/withReady.test.d.ts +1 -0
package/dist/index-CBVj1kSj.js +1350 -0
package/dist/index-Cxk9v0um.cjs +1 -0
package/dist/index.cjs +1 -1
package/dist/index.d.ts +12 -8
package/dist/index.js +18 -15
package/dist/react/index.cjs +10 -10
package/dist/react/index.d.ts +2 -1
package/dist/react/index.js +422 -377
package/dist/react/rx.d.ts +114 -25
package/dist/react/useAction.d.ts +5 -4
package/dist/react/{useValue.d.ts → useSelector.d.ts} +56 -25
package/dist/react/useSelector.test.d.ts +1 -0
package/package.json +1 -1
package/src/core/atom.test.ts +307 -43
package/src/core/atom.ts +144 -22
package/src/core/batch.test.ts +10 -10
package/src/core/batch.ts +3 -3
package/src/core/define.test.ts +12 -11
package/src/core/define.ts +1 -1
package/src/core/derived.test.ts +906 -72
package/src/core/derived.ts +192 -81
package/src/core/effect.test.ts +651 -45
package/src/core/effect.ts +102 -98
package/src/core/getAtomState.ts +69 -0
package/src/core/hook.test.ts +5 -5
package/src/core/hook.ts +1 -1
package/src/core/onCreateHook.ts +38 -23
package/src/core/onErrorHook.test.ts +350 -0
package/src/core/onErrorHook.ts +52 -0
package/src/core/promiseCache.test.ts +5 -3
package/src/core/promiseCache.ts +76 -71
package/src/core/select.ts +405 -130
package/src/core/selector.test.ts +574 -32
package/src/core/types.ts +107 -29
package/src/core/withReady.test.ts +534 -0
package/src/core/withReady.ts +191 -0
package/src/core/withUse.ts +1 -1
package/src/index.test.ts +4 -4
package/src/index.ts +21 -7
package/src/react/index.ts +2 -1
package/src/react/rx.test.tsx +173 -18
package/src/react/rx.tsx +274 -43
package/src/react/useAction.test.ts +12 -14
package/src/react/useAction.ts +11 -9
package/src/react/{useValue.test.ts → useSelector.test.ts} +16 -16
package/src/react/{useValue.ts → useSelector.ts} +64 -33
package/v2.md +44 -44
package/dist/index-2ok7ilik.js +0 -1217
package/dist/index-B_5SFzfl.cjs +0 -1
/package/dist/{react/useValue.test.d.ts → core/onErrorHook.test.d.ts} +0 -0

package/coverage/src/core/onCreateHook.ts.html CHANGED Viewed

@@ -1,68 +1,64 @@
 <!doctype html>
 <html lang="en">
-<head>
+  <head>
     <title>Code coverage report for src/core/onCreateHook.ts</title>
     <meta charset="utf-8" />
     <link rel="stylesheet" href="../../prettify.css" />
     <link rel="stylesheet" href="../../base.css" />
     <link rel="shortcut icon" type="image/x-icon" href="../../favicon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <style type='text/css'>
-        .coverage-summary .sorter {
-            background-image: url(../../sort-arrow-sprite.png);
-        }
+    <style type="text/css">
+      .coverage-summary .sorter {
+        background-image: url(../../sort-arrow-sprite.png);
+      }
     </style>
-</head>
-<body>
-<div class='wrapper'>
-    <div class='pad1'>
-        <h1><a href="../../index.html">All files</a> / <a href="index.html">src/core</a> onCreateHook.ts</h1>
-        <div class='clearfix'>
-            <div class='fl pad1y space-right2'>
-                <span class="strong">100% </span>
-                <span class="quiet">Statements</span>
-                <span class='fraction'>17/17</span>
-            </div>
-            <div class='fl pad1y space-right2'>
-                <span class="strong">100% </span>
-                <span class="quiet">Branches</span>
-                <span class='fraction'>0/0</span>
-            </div>
-            <div class='fl pad1y space-right2'>
-                <span class="strong">100% </span>
-                <span class="quiet">Functions</span>
-                <span class='fraction'>0/0</span>
-            </div>
-            <div class='fl pad1y space-right2'>
-                <span class="strong">100% </span>
-                <span class="quiet">Lines</span>
-                <span class='fraction'>17/17</span>
-            </div>
+  </head>
+  <body>
+    <div class="wrapper">
+      <div class="pad1">
+        <h1>
+          <a href="../../index.html">All files</a> /
+          <a href="index.html">src/core</a> onCreateHook.ts
+        </h1>
+        <div class="clearfix">
+          <div class="fl pad1y space-right2">
+            <span class="strong">100% </span>
+            <span class="quiet">Statements</span>
+            <span class="fraction">17/17</span>
+          </div>
+          <div class="fl pad1y space-right2">
+            <span class="strong">100% </span>
+            <span class="quiet">Branches</span>
+            <span class="fraction">0/0</span>
+          </div>
+          <div class="fl pad1y space-right2">
+            <span class="strong">100% </span>
+            <span class="quiet">Functions</span>
+            <span class="fraction">0/0</span>
+          </div>
+          <div class="fl pad1y space-right2">
+            <span class="strong">100% </span>
+            <span class="quiet">Lines</span>
+            <span class="fraction">17/17</span>
+          </div>
         </div>
         <p class="quiet">
-            Press <em>n</em> or <em>j</em> to go to the next uncovered block, <em>b</em>, <em>p</em> or <em>k</em> for the previous block.
+          Press <em>n</em> or <em>j</em> to go to the next uncovered block,
+          <em>b</em>, <em>p</em> or <em>k</em> for the previous block.
         </p>
         <template id="filterTemplate">
-            <div class="quiet">
-                Filter:
-                <input type="search" id="fileSearch">
-            </div>
+          <div class="quiet">
+            Filter:
+            <input type="search" id="fileSearch" />
+          </div>
         </template>
-    </div>
-    <div class='status-line high'></div>
-    <pre><table class="coverage">
+      </div>
+      <div class="status-line high"></div>
+      <pre><table class="coverage">
 <tr><td class="line-count quiet"><a name='L1'></a><a href='#L1'>1</a>
 <a name='L2'></a><a href='#L2'>2</a>
 <a name='L3'></a><a href='#L3'>3</a>
@@ -100,7 +96,7 @@
 <span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import { hook } from "./hook";
 import { MutableAtom } from "./types";
 &nbsp;
-export interface AtomCreateInfo {
+export interface CreateInfo {
   type: "atom";
   key: string | undefined;
   atom: MutableAtom&lt;any&gt;;
@@ -113,24 +109,30 @@ export interface ModuleCreateInfo {
 }
 &nbsp;
 export const onCreateHook =
-  hook&lt;(info: AtomCreateInfo | ModuleCreateInfo) =&gt; void&gt;();
+  hook&lt;(info: CreateInfo | ModuleCreateInfo) =&gt; void&gt;();
 &nbsp;</pre></td></tr></table></pre>
-                <div class='push'></div><!-- for sticky footer -->
-            </div><!-- /wrapper -->
-            <div class='footer quiet pad2 space-top1 center small'>
-                Code coverage generated by
-                <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-01-16T14:35:38.788Z
-            </div>
-        <script src="../../prettify.js"></script>
-        <script>
-            window.onload = function () {
-                prettyPrint();
-            };
-        </script>
-        <script src="../../sorter.js"></script>
-        <script src="../../block-navigation.js"></script>
-    </body>
+      <div class="push"></div>
+      <!-- for sticky footer -->
+    </div>
+    <!-- /wrapper -->
+    <div class="footer quiet pad2 space-top1 center small">
+      Code coverage generated by
+      <a
+        href="https://istanbul.js.org/"
+        target="_blank"
+        rel="noopener noreferrer"
+        >istanbul</a
+      >
+      at 2026-01-16T14:35:38.788Z
+    </div>
+    <script src="../../prettify.js"></script>
+    <script>
+      window.onload = function () {
+        prettyPrint();
+      };
+    </script>
+    <script src="../../sorter.js"></script>
+    <script src="../../block-navigation.js"></script>
+  </body>
 </html>

package/dist/core/atom.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,19 +1,33 @@
-import { SelectContext } from './select';
+import { CreateInfo } from './onCreateHook';
+import { ReactiveSelector, SelectContext } from './select';
 import { DerivedAtom, DerivedOptions } from './types';
+import { 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
@@ -22,35 +36,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 +109,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 +119,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 +139,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> & DerivedInternalOptions): DerivedAtom<T, false>;
+export declare function derived<T>(fn: ReactiveSelector<T, DerivedContext>, options: DerivedOptions<T> & {
     fallback: T;
-}): DerivedAtom<T, true>;
+} & DerivedInternalOptions): DerivedAtom<T, true>;

package/dist/core/effect.d.ts CHANGED Viewed

@@ -1,10 +1,11 @@
-import { SelectContext } from './select';
-import { EffectOptions } from './types';
+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.
@@ -13,41 +14,25 @@ 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.
  *
  * 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 +42,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 +67,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): Effect;