@pumped-fn/lite-react 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @pumped-fn/lite-react
 
+## 1.1.1
+
+### Patch Changes
+
+- 8ed17e7: - Fix watch and invalidation edge cases in `@pumped-fn/lite` by aligning `select()` with `Object.is`, snapshotting select listeners during notification, making watch option typing match the runtime contract, and surfacing invalidation-chain failures from `flush()` instead of leaking them as background rejections.
+  - Fix `@pumped-fn/lite-react` hook refresh behavior by keeping stale values visible during re-resolution, recomputing `useSelect` snapshots when selector or equality semantics change, tracking pending promises per controller, and suppressing non-Suspense `unhandledRejection` leaks on failed refreshes.
+
+## 1.1.0
+
+### Minor Changes
+
+- 1624845: feat(lite-react): add non-Suspense mode and resolve options for useAtom/useController
+
+  - Add `{ suspense: false }` option to `useAtom` returning `UseAtomState<T>` with `data`, `loading`, `error`, `controller`
+  - Add `{ resolve: boolean }` option to control auto-resolution behavior
+    - Suspense mode: `resolve` defaults to `true` (auto-resolves idle atoms)
+    - Non-Suspense mode: `resolve` defaults to `false` (no auto-resolve)
+  - Add `{ resolve: true }` option to `useController` for Suspense integration
+  - Export new types: `UseAtomSuspenseOptions`, `UseAtomManualOptions`, `UseAtomOptions`, `UseAtomState`, `UseControllerOptions`
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -1,6 +1,6 @@
 # @pumped-fn/lite-react
 
-React bindings for `@pumped-fn/lite` with Suspense and ErrorBoundary integration.
+React bindings for `@pumped-fn/lite` with Suspense, ErrorBoundary integration, and stale-while-revalidate refreshes.
 
 **Zero dependencies** · **<2KB bundle** · **React 18+**
 
@@ -20,12 +20,14 @@ sequenceDiagram
     alt resolved
         Controller-->>useAtom: value
         useAtom->>Controller: subscribe to changes
-    else resolving
+    else resolving with stale value
+        Controller-->>useAtom: stale value
+    else resolving without value
         useAtom-->>App: throw Promise (Suspense)
     else failed
         useAtom-->>App: throw Error (ErrorBoundary)
     else idle
-        useAtom-->>App: throw Error (not resolved)
+        useAtom-->>App: throw Promise (Suspense)
     end
 ```
 
@@ -37,19 +39,21 @@ flowchart TD
     Hook --> State{ctrl.state?}
 
     State -->|idle| AutoResolve[Auto-resolve + Throw Promise]
-    State -->|resolving| Promise[Throw cached Promise]
+    State -->|resolving + stale value| Stale[Return stale value]
+    State -->|resolving + no value| Promise[Throw cached Promise]
     State -->|resolved| Value[Return value]
     State -->|failed| Stored[Throw stored error]
 
     AutoResolve --> Suspense[Suspense catches]
     Promise --> Suspense
+    Stale --> Render[Keep current UI]
     Stored --> ErrorBoundary[ErrorBoundary catches]
 ```
 
 | State | Hook Behavior |
 |-------|---------------|
 | `idle` | Auto-resolves and suspends — Suspense shows fallback |
-| `resolving` | Throws cached promise — Suspense shows fallback |
+| `resolving` | Returns stale value if available, otherwise throws cached promise |
 | `resolved` | Returns value, subscribes to changes |
 | `failed` | Throws stored error — ErrorBoundary catches |
 
@@ -91,6 +95,16 @@ ctrl.update(n => n + 1)
 ctrl.invalidate()
 ```
 
+With `{ resolve: true }` option, triggers Suspense if atom not resolved:
+
+```tsx
+// Suspense ensures controller is resolved before render
+const ctrl = useController(configAtom, { resolve: true })
+ctrl.get() // safe - Suspense guarantees resolved state
+```
+
+While a controller is re-resolving, `{ resolve: true }` keeps suspending until the controller settles.
+
 ### useAtom
 
 Subscribe to atom value with Suspense integration.
@@ -109,6 +123,42 @@ function UserProfile() {
 </ErrorBoundary>
 ```
 
+#### Non-Suspense Mode
+
+For manual loading/error state handling without Suspense:
+
+```tsx
+function UserProfile() {
+  const { data, loading, error, controller } = useAtom(userAtom, { suspense: false })
+
+  if (loading && data) return <div>Refreshing {data.name}...</div>
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  if (!data) return <div>Not loaded</div>
+
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <button onClick={() => controller.invalidate()}>Refresh</button>
+    </div>
+  )
+}
+```
+
+With `{ resolve: true }`, auto-resolves on mount:
+
+```tsx
+// Starts resolution automatically when component mounts
+const { data, loading, error } = useAtom(userAtom, { suspense: false, resolve: true })
+```
+
+| Option | Effect |
+|--------|--------|
+| `{ suspense: false }` | Returns state object, no auto-resolve |
+| `{ suspense: false, resolve: true }` | Returns state object, auto-resolves on mount |
+
+While `loading` is `true`, `data` may still contain the last resolved value during a refresh.
+
 ### useSelect
 
 Fine-grained selection — only re-renders when selected value changes.
@@ -120,7 +170,7 @@ const count = useSelect(todosAtom, todos => todos.length, (a, b) => a === b)
 
 ## Invalidation
 
-When an atom is invalidated, hooks automatically suspend during re-resolution:
+When an atom is invalidated, `useAtom` and `useSelect` keep rendering the last value while re-resolving:
 
 ```mermaid
 sequenceDiagram
@@ -133,14 +183,16 @@ sequenceDiagram
 
     Note over Controller: ctrl.invalidate()
     Controller->>Controller: state = resolving
-    useAtom-->>Component: throw Promise
-    Note over Component: Suspense fallback
+    useAtom-->>Component: stale value
+    Note over Component: current UI stays visible
 
     Controller->>Controller: factory runs
     Controller->>Controller: state = resolved
     useAtom->>Component: re-render (new value)
 ```
 
+`useController(atom, { resolve: true })` is different: it suspends until the controller settles again.
+
 ## Testing
 
 Use presets for test isolation:
@@ -163,10 +215,9 @@ render(
 
 ## SSR
 
-SSR-compatible by design:
+SSR-compatible when request-scoped atoms are resolved before rendering:
 
 - No side effects on import
-- Uses `useSyncExternalStore` with server snapshot
 - Scope passed as prop (no global state)
 
 ```tsx

package/dist/index.cjs

@@ -27,12 +27,28 @@ function ScopeProvider({ scope, children }) {
 //#endregion
 //#region src/hooks.ts
 const pendingPromises = /* @__PURE__ */ new WeakMap();
-function getOrCreatePendingPromise(atom$1, ctrl) {
-	let pending = pendingPromises.get(atom$1);
+function getOrCreatePendingPromise(ctrl) {
+	let pending = pendingPromises.get(ctrl);
 	if (!pending) {
-		pending = ctrl.resolve();
-		pendingPromises.set(atom$1, pending);
-		pending.finally(() => pendingPromises.delete(atom$1));
+		if (ctrl.state === "resolving") pending = new Promise((resolve, reject) => {
+			const unsub = ctrl.on("*", () => {
+				if (ctrl.state === "resolved") {
+					unsub();
+					resolve(ctrl.get());
+				} else if (ctrl.state === "failed") {
+					unsub();
+					try {
+						ctrl.get();
+					} catch (e) {
+						reject(e);
+					}
+				}
+			});
+		});
+		else pending = ctrl.resolve();
+		pendingPromises.set(ctrl, pending);
+		pending.catch(() => {});
+		pending.then(() => pendingPromises.delete(ctrl), () => pendingPromises.delete(ctrl));
 	}
 	return pending;
 }
@@ -44,8 +60,10 @@ function getOrCreatePendingPromise(atom$1, ctrl) {
 *
 * @example
 * ```tsx
-* const scope = useScope()
-* await scope.resolve(myAtom)
+* function MyComponent() {
+*   const scope = useScope()
+*   const handleClick = () => scope.resolve(myAtom)
+* }
 * ```
 */
 function useScope() {
@@ -53,48 +71,80 @@ function useScope() {
 	if (!scope) throw new Error("useScope must be used within a ScopeProvider");
 	return scope;
 }
-/**
-* Get a memoized controller for an atom.
-*
-* @param atom - The atom to create a controller for
-* @returns A memoized Lite.Controller instance
-*
-* @example
-* ```tsx
-* const ctrl = useController(counterAtom)
-* ctrl.set(ctrl.get() + 1)
-* ```
-*/
-function useController(atom$1) {
+function useController(atom$1, options) {
 	const scope = useScope();
-	return (0, react.useMemo)(() => scope.controller(atom$1), [scope, atom$1]);
+	const ctrl = (0, react.useMemo)(() => scope.controller(atom$1), [scope, atom$1]);
+	if (options?.resolve) {
+		if (ctrl.state === "idle" || ctrl.state === "resolving") throw getOrCreatePendingPromise(ctrl);
+		if (ctrl.state === "failed") throw ctrl.get();
+	}
+	return ctrl;
 }
-/**
-* Subscribe to atom value with Suspense/ErrorBoundary integration.
-* Auto-resolves atoms lazily and throws cached Promise for Suspense.
-*
-* @param atom - The atom to read
-* @returns The current value of the atom
-*
-* @example
-* ```tsx
-* function UserProfile() {
-*   const user = useAtom(userAtom)
-*   return <div>{user.name}</div>
-* }
-* ```
-*/
-function useAtom(atom$1) {
+function useAtom(atom$1, options) {
 	const ctrl = useController(atom$1);
-	const atomRef = (0, react.useRef)(atom$1);
-	atomRef.current = atom$1;
+	const ctrlState = ctrl.state;
+	const isSuspense = options?.suspense !== false;
+	const autoResolve = isSuspense ? options?.resolve !== false : !!options?.resolve;
+	const stateCache = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		if (!isSuspense && (ctrlState === "resolving" || autoResolve && ctrlState === "idle")) getOrCreatePendingPromise(ctrl).catch(() => {});
+	}, [
+		ctrl,
+		ctrlState,
+		autoResolve,
+		isSuspense
+	]);
 	const getSnapshot = (0, react.useCallback)(() => {
-		const state = ctrl.state;
-		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
-		if (state === "failed") throw ctrl.get();
-		return ctrl.get();
-	}, [ctrl]);
-	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => ctrl.on("resolved", onStoreChange), [ctrl]), getSnapshot, getSnapshot);
+		if (isSuspense) {
+			if (ctrl.state === "idle") {
+				if (autoResolve) throw getOrCreatePendingPromise(ctrl);
+				throw new Error("Atom is not resolved. Set resolve: true or resolve the atom before rendering.");
+			}
+			if (ctrl.state === "failed") throw ctrl.get();
+			try {
+				return ctrl.get();
+			} catch {
+				throw getOrCreatePendingPromise(ctrl);
+			}
+		}
+		let data;
+		let error;
+		if (ctrl.state === "resolved" || ctrl.state === "resolving") try {
+			data = ctrl.get();
+		} catch {}
+		else if (ctrl.state === "failed") try {
+			ctrl.get();
+		} catch (e) {
+			error = e instanceof Error ? e : new Error(String(e));
+		}
+		const loading = ctrl.state === "resolving" || autoResolve && ctrl.state === "idle";
+		if (stateCache.current && stateCache.current.ctrl === ctrl && stateCache.current.ctrlState === ctrl.state && stateCache.current.data === data && stateCache.current.error === error && stateCache.current.loading === loading) return stateCache.current.result;
+		const result = {
+			data,
+			loading,
+			error,
+			controller: ctrl
+		};
+		stateCache.current = {
+			ctrl,
+			ctrlState: ctrl.state,
+			data,
+			error,
+			loading,
+			result
+		};
+		return result;
+	}, [
+		ctrl,
+		autoResolve,
+		isSuspense
+	]);
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => {
+		return ctrl.on("*", () => {
+			if (!isSuspense && ctrl.state === "resolving") getOrCreatePendingPromise(ctrl).catch(() => {});
+			onStoreChange();
+		});
+	}, [ctrl, isSuspense]), getSnapshot, getSnapshot);
 }
 /**
 * Select a derived value from an atom with fine-grained reactivity.
@@ -111,33 +161,41 @@ function useAtom(atom$1) {
 * ```
 */
 function useSelect(atom$1, selector, eq) {
-	const scope = useScope();
 	const ctrl = useController(atom$1);
-	const atomRef = (0, react.useRef)(atom$1);
-	atomRef.current = atom$1;
 	const selectorRef = (0, react.useRef)(selector);
 	const eqRef = (0, react.useRef)(eq);
 	selectorRef.current = selector;
 	eqRef.current = eq;
-	const handleRef = (0, react.useRef)(null);
-	const getOrCreateHandle = (0, react.useCallback)(() => {
-		if (!handleRef.current || handleRef.current.scope !== scope || handleRef.current.atom !== atom$1) handleRef.current = {
-			scope,
-			atom: atom$1,
-			handle: scope.select(atom$1, selectorRef.current, { eq: eqRef.current })
-		};
-		return handleRef.current.handle;
-	}, [scope, atom$1]);
+	const selectionCache = (0, react.useRef)(null);
 	const getSnapshot = (0, react.useCallback)(() => {
 		const state = ctrl.state;
-		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "idle") throw getOrCreatePendingPromise(ctrl);
 		if (state === "failed") throw ctrl.get();
-		return getOrCreateHandle().get();
-	}, [ctrl, getOrCreateHandle]);
+		let value;
+		try {
+			value = ctrl.get();
+		} catch {
+			throw getOrCreatePendingPromise(ctrl);
+		}
+		const nextSelector = selectorRef.current;
+		const nextEq = eqRef.current;
+		const current = selectionCache.current;
+		if (current && current.ctrl === ctrl && current.ctrlState === state && Object.is(current.source, value) && current.selector === nextSelector && current.eq === nextEq) return current.value;
+		const nextValue = nextSelector(value);
+		const selectedValue = current && current.ctrl === ctrl && current.selector === nextSelector && (nextEq ?? Object.is)(current.value, nextValue) ? current.value : nextValue;
+		selectionCache.current = {
+			ctrl,
+			ctrlState: state,
+			source: value,
+			selector: nextSelector,
+			eq: nextEq,
+			value: selectedValue
+		};
+		return selectedValue;
+	}, [ctrl]);
 	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => {
-		if (ctrl.state !== "resolved") return () => {};
-		return getOrCreateHandle().subscribe(onStoreChange);
-	}, [ctrl, getOrCreateHandle]), getSnapshot, getSnapshot);
+		return ctrl.on("*", onStoreChange);
+	}, [ctrl]), getSnapshot, getSnapshot);
 }
 
 //#endregion

package/dist/index.d.cts

@@ -28,6 +28,26 @@ declare function ScopeProvider({
 }: ScopeProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/hooks.d.ts
+interface UseAtomSuspenseOptions {
+  suspense?: true;
+  /** @default true */
+  resolve?: boolean;
+}
+interface UseAtomManualOptions {
+  suspense: false;
+  /** @default false */
+  resolve?: boolean;
+}
+type UseAtomOptions = UseAtomSuspenseOptions | UseAtomManualOptions;
+interface UseAtomState<T> {
+  data: T | undefined;
+  loading: boolean;
+  error: Error | undefined;
+  controller: Lite$1.Controller<T>;
+}
+interface UseControllerOptions {
+  resolve?: boolean;
+}
 /**
  * Access the current Lite.Scope from context.
  *
@@ -36,17 +56,16 @@ declare function ScopeProvider({
  *
  * @example
  * ```tsx
- * const scope = useScope()
- * await scope.resolve(myAtom)
+ * function MyComponent() {
+ *   const scope = useScope()
+ *   const handleClick = () => scope.resolve(myAtom)
+ * }
  * ```
  */
 declare function useScope(): Lite$1.Scope;
 /**
  * Get a memoized controller for an atom.
  *
- * @param atom - The atom to create a controller for
- * @returns A memoized Lite.Controller instance
- *
  * @example
  * ```tsx
  * const ctrl = useController(counterAtom)
@@ -54,22 +73,19 @@ declare function useScope(): Lite$1.Scope;
  * ```
  */
 declare function useController<T>(atom: Lite$1.Atom<T>): Lite$1.Controller<T>;
+declare function useController<T>(atom: Lite$1.Atom<T>, options: UseControllerOptions): Lite$1.Controller<T>;
 /**
  * Subscribe to atom value with Suspense/ErrorBoundary integration.
- * Auto-resolves atoms lazily and throws cached Promise for Suspense.
- *
- * @param atom - The atom to read
- * @returns The current value of the atom
  *
  * @example
  * ```tsx
- * function UserProfile() {
- *   const user = useAtom(userAtom)
- *   return <div>{user.name}</div>
- * }
+ * const user = useAtom(userAtom)
+ * const { data, loading, error } = useAtom(userAtom, { suspense: false })
  * ```
  */
 declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
+declare function useAtom<T>(atom: Lite$1.Atom<T>, options: UseAtomSuspenseOptions): T;
+declare function useAtom<T>(atom: Lite$1.Atom<T>, options: UseAtomManualOptions): UseAtomState<T>;
 /**
  * Select a derived value from an atom with fine-grained reactivity.
  * Only re-renders when the selected value changes per equality function.
@@ -86,5 +102,5 @@ declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
  */
 declare function useSelect<T, S>(atom: Lite$1.Atom<T>, selector: (value: T) => S, eq?: (a: S, b: S) => boolean): S;
 //#endregion
-export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
+export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, type UseAtomManualOptions, type UseAtomOptions, type UseAtomState, type UseAtomSuspenseOptions, type UseControllerOptions, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AA2BZ;;iBDLtB,aAAA,CCyB4B;EAAA,KAAA;EAAA;AAAA,CAAA,EDzBO,kBCyBP,CAAA,EDzByB,kBAAA,CAAA,GAAA,CAAA,OCyBzB;;;;;;;;AD/CM;AAKzB;AAIG;;;;;iBCkBZ,QAAA,CAAA,CDLqD,ECKzC,MAAA,CAAK,KDLoC;;;;ACtBnB;AA2BZ;;;;;;AAoB+B;;iBAArD,aAoBsB,CAAA,CAAA,CAAA,CAAA,IAAA,EApBC,MAAA,CAAK,IAoBN,CApBW,CAoBX,CAAA,CAAA,EApBgB,MAAA,CAAK,UAoBrB,CApBgC,CAoBhC,CAAA;;;AAAW;;;;;;;;;;;;;iBAAjC,iBAAiB,MAAA,CAAK,KAAK,KAAK;;;;;;;;;;;;;;;iBAsChC,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AAGX;AAMF;AAMqC,iBDO1D,aAAA,CCLa;EAAA,KAAA;EAAA;AAAA,CAAA,EDKsB,kBCLtB,CAAA,EDKwC,kBAAA,CAAA,GAAA,CAAA,OCLxC;;;UAdZ,sBAAA;;;;;ADHiC,UCSjC,oBAAA,CDJQ;EAER,QAAA,EAAA,KAAA;EAeD;EAAgB,OAAA,CAAA,EAAA,OAAA;;KCPpB,cAAA,GAAiB,sBDOsB,GCPG,oBDOH;UCLlC,YDKoD,CAAA,CAAA,CAAA,CAAA;EAAA,IAAA,ECJtD,CDIsD,GAAA,SAAA;;SCFrD;cACK,MAAA,CAAK,WAAW;AArBa;AAGX,UAqBtB,oBAAA,CAfoB;EAMzB,OAAA,CAAA,EAAA,OAAc;AAAgD;;;;;;AAMtC;AAGC;AAgDC;;;;;;AAiB+B;iBAjBrD,QAAA,CAAA,CAkBiC,EAlBrB,MAAA,CAAK,KAkBgB;;;;;;AAAmD;;;;iBADpF,aA2BiC,CAAA,CAAA,CAAA,CAAA,IAAA,EA3BV,MAAA,CAAK,IA2BK,CA3BA,CA2BA,CAAA,CAAA,EA3BK,MAAA,CAAK,UA2BV,CA3BqB,CA2BrB,CAAA;AAAA,iBA1BjC,aA2BO,CAAA,CAAA,CAAA,CAAA,IAAA,EA3BgB,MAAA,CAAK,IA2BrB,CA3B0B,CA2B1B,CAAA,EAAA,OAAA,EA3BuC,oBA2BvC,CAAA,EA3B8D,MAAA,CAAK,UA2BnE,CA3B8E,CA2B9E,CAAA;;;;;;AAA2D;;;;iBADlE,OAE4E,CAAA,CAAA,CAAA,CAAA,IAAA,EAF3D,MAAA,CAAK,IAEsD,CAFjD,CAEiD,CAAA,CAAA,EAF5C,CAE4C;iBAD5E,OAC+D,CAAA,CAAA,CAAA,CAAA,IAAA,EAD9C,MAAA,CAAK,IACyC,CADpC,CACoC,CAAA,EAAA,OAAA,EADvB,sBACuB,CAAA,EADE,CACF;iBAA/D,OAA2E,CAAA,CAAA,CAAA,CAAA,IAAA,EAA1D,MAAA,CAAK,IAAqD,CAAhD,CAAgD,CAAA,EAAA,OAAA,EAAnC,oBAAmC,CAAA,EAAZ,YAAY,CAAC,CAAD,CAAA;AAAA;;;;;;;;;;;;;;iBA0G3E,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}

package/dist/index.d.mts

@@ -28,6 +28,26 @@ declare function ScopeProvider({
 }: ScopeProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/hooks.d.ts
+interface UseAtomSuspenseOptions {
+  suspense?: true;
+  /** @default true */
+  resolve?: boolean;
+}
+interface UseAtomManualOptions {
+  suspense: false;
+  /** @default false */
+  resolve?: boolean;
+}
+type UseAtomOptions = UseAtomSuspenseOptions | UseAtomManualOptions;
+interface UseAtomState<T> {
+  data: T | undefined;
+  loading: boolean;
+  error: Error | undefined;
+  controller: Lite$1.Controller<T>;
+}
+interface UseControllerOptions {
+  resolve?: boolean;
+}
 /**
  * Access the current Lite.Scope from context.
  *
@@ -36,17 +56,16 @@ declare function ScopeProvider({
  *
  * @example
  * ```tsx
- * const scope = useScope()
- * await scope.resolve(myAtom)
+ * function MyComponent() {
+ *   const scope = useScope()
+ *   const handleClick = () => scope.resolve(myAtom)
+ * }
  * ```
  */
 declare function useScope(): Lite$1.Scope;
 /**
  * Get a memoized controller for an atom.
  *
- * @param atom - The atom to create a controller for
- * @returns A memoized Lite.Controller instance
- *
  * @example
  * ```tsx
  * const ctrl = useController(counterAtom)
@@ -54,22 +73,19 @@ declare function useScope(): Lite$1.Scope;
  * ```
  */
 declare function useController<T>(atom: Lite$1.Atom<T>): Lite$1.Controller<T>;
+declare function useController<T>(atom: Lite$1.Atom<T>, options: UseControllerOptions): Lite$1.Controller<T>;
 /**
  * Subscribe to atom value with Suspense/ErrorBoundary integration.
- * Auto-resolves atoms lazily and throws cached Promise for Suspense.
- *
- * @param atom - The atom to read
- * @returns The current value of the atom
  *
  * @example
  * ```tsx
- * function UserProfile() {
- *   const user = useAtom(userAtom)
- *   return <div>{user.name}</div>
- * }
+ * const user = useAtom(userAtom)
+ * const { data, loading, error } = useAtom(userAtom, { suspense: false })
  * ```
  */
 declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
+declare function useAtom<T>(atom: Lite$1.Atom<T>, options: UseAtomSuspenseOptions): T;
+declare function useAtom<T>(atom: Lite$1.Atom<T>, options: UseAtomManualOptions): UseAtomState<T>;
 /**
  * Select a derived value from an atom with fine-grained reactivity.
  * Only re-renders when the selected value changes per equality function.
@@ -86,5 +102,5 @@ declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
  */
 declare function useSelect<T, S>(atom: Lite$1.Atom<T>, selector: (value: T) => S, eq?: (a: S, b: S) => boolean): S;
 //#endregion
-export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
+export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, type UseAtomManualOptions, type UseAtomOptions, type UseAtomState, type UseAtomSuspenseOptions, type UseControllerOptions, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AA2BZ;;iBDLtB,aAAA,CCyB4B;EAAA,KAAA;EAAA;AAAA,CAAA,EDzBO,kBCyBP,CAAA,EDzByB,kBAAA,CAAA,GAAA,CAAA,OCyBzB;;;;;;;;AD/CM;AAKzB;AAIG;;;;;iBCkBZ,QAAA,CAAA,CDLqD,ECKzC,MAAA,CAAK,KDLoC;;;;ACtBnB;AA2BZ;;;;;;AAoB+B;;iBAArD,aAoBsB,CAAA,CAAA,CAAA,CAAA,IAAA,EApBC,MAAA,CAAK,IAoBN,CApBW,CAoBX,CAAA,CAAA,EApBgB,MAAA,CAAK,UAoBrB,CApBgC,CAoBhC,CAAA;;;AAAW;;;;;;;;;;;;;iBAAjC,iBAAiB,MAAA,CAAK,KAAK,KAAK;;;;;;;;;;;;;;;iBAsChC,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AAGX;AAMF;AAMqC,iBDO1D,aAAA,CCLa;EAAA,KAAA;EAAA;AAAA,CAAA,EDKsB,kBCLtB,CAAA,EDKwC,kBAAA,CAAA,GAAA,CAAA,OCLxC;;;UAdZ,sBAAA;;;;;ADHiC,UCSjC,oBAAA,CDJQ;EAER,QAAA,EAAA,KAAA;EAeD;EAAgB,OAAA,CAAA,EAAA,OAAA;;KCPpB,cAAA,GAAiB,sBDOsB,GCPG,oBDOH;UCLlC,YDKoD,CAAA,CAAA,CAAA,CAAA;EAAA,IAAA,ECJtD,CDIsD,GAAA,SAAA;;SCFrD;cACK,MAAA,CAAK,WAAW;AArBa;AAGX,UAqBtB,oBAAA,CAfoB;EAMzB,OAAA,CAAA,EAAA,OAAc;AAAgD;;;;;;AAMtC;AAGC;AAgDC;;;;;;AAiB+B;iBAjBrD,QAAA,CAAA,CAkBiC,EAlBrB,MAAA,CAAK,KAkBgB;;;;;;AAAmD;;;;iBADpF,aA2BiC,CAAA,CAAA,CAAA,CAAA,IAAA,EA3BV,MAAA,CAAK,IA2BK,CA3BA,CA2BA,CAAA,CAAA,EA3BK,MAAA,CAAK,UA2BV,CA3BqB,CA2BrB,CAAA;AAAA,iBA1BjC,aA2BO,CAAA,CAAA,CAAA,CAAA,IAAA,EA3BgB,MAAA,CAAK,IA2BrB,CA3B0B,CA2B1B,CAAA,EAAA,OAAA,EA3BuC,oBA2BvC,CAAA,EA3B8D,MAAA,CAAK,UA2BnE,CA3B8E,CA2B9E,CAAA;;;;;;AAA2D;;;;iBADlE,OAE4E,CAAA,CAAA,CAAA,CAAA,IAAA,EAF3D,MAAA,CAAK,IAEsD,CAFjD,CAEiD,CAAA,CAAA,EAF5C,CAE4C;iBAD5E,OAC+D,CAAA,CAAA,CAAA,CAAA,IAAA,EAD9C,MAAA,CAAK,IACyC,CADpC,CACoC,CAAA,EAAA,OAAA,EADvB,sBACuB,CAAA,EADE,CACF;iBAA/D,OAA2E,CAAA,CAAA,CAAA,CAAA,IAAA,EAA1D,MAAA,CAAK,IAAqD,CAAhD,CAAgD,CAAA,EAAA,OAAA,EAAnC,oBAAmC,CAAA,EAAZ,YAAY,CAAC,CAAD,CAAA;AAAA;;;;;;;;;;;;;;iBA0G3E,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { atom, createScope, flow, preset } from "@pumped-fn/lite";
-import { createContext, useCallback, useContext, useMemo, useRef, useSyncExternalStore } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/context.tsx
@@ -27,12 +27,28 @@ function ScopeProvider({ scope, children }) {
 //#endregion
 //#region src/hooks.ts
 const pendingPromises = /* @__PURE__ */ new WeakMap();
-function getOrCreatePendingPromise(atom$1, ctrl) {
-	let pending = pendingPromises.get(atom$1);
+function getOrCreatePendingPromise(ctrl) {
+	let pending = pendingPromises.get(ctrl);
 	if (!pending) {
-		pending = ctrl.resolve();
-		pendingPromises.set(atom$1, pending);
-		pending.finally(() => pendingPromises.delete(atom$1));
+		if (ctrl.state === "resolving") pending = new Promise((resolve, reject) => {
+			const unsub = ctrl.on("*", () => {
+				if (ctrl.state === "resolved") {
+					unsub();
+					resolve(ctrl.get());
+				} else if (ctrl.state === "failed") {
+					unsub();
+					try {
+						ctrl.get();
+					} catch (e) {
+						reject(e);
+					}
+				}
+			});
+		});
+		else pending = ctrl.resolve();
+		pendingPromises.set(ctrl, pending);
+		pending.catch(() => {});
+		pending.then(() => pendingPromises.delete(ctrl), () => pendingPromises.delete(ctrl));
 	}
 	return pending;
 }
@@ -44,8 +60,10 @@ function getOrCreatePendingPromise(atom$1, ctrl) {
 *
 * @example
 * ```tsx
-* const scope = useScope()
-* await scope.resolve(myAtom)
+* function MyComponent() {
+*   const scope = useScope()
+*   const handleClick = () => scope.resolve(myAtom)
+* }
 * ```
 */
 function useScope() {
@@ -53,48 +71,80 @@ function useScope() {
 	if (!scope) throw new Error("useScope must be used within a ScopeProvider");
 	return scope;
 }
-/**
-* Get a memoized controller for an atom.
-*
-* @param atom - The atom to create a controller for
-* @returns A memoized Lite.Controller instance
-*
-* @example
-* ```tsx
-* const ctrl = useController(counterAtom)
-* ctrl.set(ctrl.get() + 1)
-* ```
-*/
-function useController(atom$1) {
+function useController(atom$1, options) {
 	const scope = useScope();
-	return useMemo(() => scope.controller(atom$1), [scope, atom$1]);
+	const ctrl = useMemo(() => scope.controller(atom$1), [scope, atom$1]);
+	if (options?.resolve) {
+		if (ctrl.state === "idle" || ctrl.state === "resolving") throw getOrCreatePendingPromise(ctrl);
+		if (ctrl.state === "failed") throw ctrl.get();
+	}
+	return ctrl;
 }
-/**
-* Subscribe to atom value with Suspense/ErrorBoundary integration.
-* Auto-resolves atoms lazily and throws cached Promise for Suspense.
-*
-* @param atom - The atom to read
-* @returns The current value of the atom
-*
-* @example
-* ```tsx
-* function UserProfile() {
-*   const user = useAtom(userAtom)
-*   return <div>{user.name}</div>
-* }
-* ```
-*/
-function useAtom(atom$1) {
+function useAtom(atom$1, options) {
 	const ctrl = useController(atom$1);
-	const atomRef = useRef(atom$1);
-	atomRef.current = atom$1;
+	const ctrlState = ctrl.state;
+	const isSuspense = options?.suspense !== false;
+	const autoResolve = isSuspense ? options?.resolve !== false : !!options?.resolve;
+	const stateCache = useRef(null);
+	useEffect(() => {
+		if (!isSuspense && (ctrlState === "resolving" || autoResolve && ctrlState === "idle")) getOrCreatePendingPromise(ctrl).catch(() => {});
+	}, [
+		ctrl,
+		ctrlState,
+		autoResolve,
+		isSuspense
+	]);
 	const getSnapshot = useCallback(() => {
-		const state = ctrl.state;
-		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
-		if (state === "failed") throw ctrl.get();
-		return ctrl.get();
-	}, [ctrl]);
-	return useSyncExternalStore(useCallback((onStoreChange) => ctrl.on("resolved", onStoreChange), [ctrl]), getSnapshot, getSnapshot);
+		if (isSuspense) {
+			if (ctrl.state === "idle") {
+				if (autoResolve) throw getOrCreatePendingPromise(ctrl);
+				throw new Error("Atom is not resolved. Set resolve: true or resolve the atom before rendering.");
+			}
+			if (ctrl.state === "failed") throw ctrl.get();
+			try {
+				return ctrl.get();
+			} catch {
+				throw getOrCreatePendingPromise(ctrl);
+			}
+		}
+		let data;
+		let error;
+		if (ctrl.state === "resolved" || ctrl.state === "resolving") try {
+			data = ctrl.get();
+		} catch {}
+		else if (ctrl.state === "failed") try {
+			ctrl.get();
+		} catch (e) {
+			error = e instanceof Error ? e : new Error(String(e));
+		}
+		const loading = ctrl.state === "resolving" || autoResolve && ctrl.state === "idle";
+		if (stateCache.current && stateCache.current.ctrl === ctrl && stateCache.current.ctrlState === ctrl.state && stateCache.current.data === data && stateCache.current.error === error && stateCache.current.loading === loading) return stateCache.current.result;
+		const result = {
+			data,
+			loading,
+			error,
+			controller: ctrl
+		};
+		stateCache.current = {
+			ctrl,
+			ctrlState: ctrl.state,
+			data,
+			error,
+			loading,
+			result
+		};
+		return result;
+	}, [
+		ctrl,
+		autoResolve,
+		isSuspense
+	]);
+	return useSyncExternalStore(useCallback((onStoreChange) => {
+		return ctrl.on("*", () => {
+			if (!isSuspense && ctrl.state === "resolving") getOrCreatePendingPromise(ctrl).catch(() => {});
+			onStoreChange();
+		});
+	}, [ctrl, isSuspense]), getSnapshot, getSnapshot);
 }
 /**
 * Select a derived value from an atom with fine-grained reactivity.
@@ -111,33 +161,41 @@ function useAtom(atom$1) {
 * ```
 */
 function useSelect(atom$1, selector, eq) {
-	const scope = useScope();
 	const ctrl = useController(atom$1);
-	const atomRef = useRef(atom$1);
-	atomRef.current = atom$1;
 	const selectorRef = useRef(selector);
 	const eqRef = useRef(eq);
 	selectorRef.current = selector;
 	eqRef.current = eq;
-	const handleRef = useRef(null);
-	const getOrCreateHandle = useCallback(() => {
-		if (!handleRef.current || handleRef.current.scope !== scope || handleRef.current.atom !== atom$1) handleRef.current = {
-			scope,
-			atom: atom$1,
-			handle: scope.select(atom$1, selectorRef.current, { eq: eqRef.current })
-		};
-		return handleRef.current.handle;
-	}, [scope, atom$1]);
+	const selectionCache = useRef(null);
 	const getSnapshot = useCallback(() => {
 		const state = ctrl.state;
-		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "idle") throw getOrCreatePendingPromise(ctrl);
 		if (state === "failed") throw ctrl.get();
-		return getOrCreateHandle().get();
-	}, [ctrl, getOrCreateHandle]);
+		let value;
+		try {
+			value = ctrl.get();
+		} catch {
+			throw getOrCreatePendingPromise(ctrl);
+		}
+		const nextSelector = selectorRef.current;
+		const nextEq = eqRef.current;
+		const current = selectionCache.current;
+		if (current && current.ctrl === ctrl && current.ctrlState === state && Object.is(current.source, value) && current.selector === nextSelector && current.eq === nextEq) return current.value;
+		const nextValue = nextSelector(value);
+		const selectedValue = current && current.ctrl === ctrl && current.selector === nextSelector && (nextEq ?? Object.is)(current.value, nextValue) ? current.value : nextValue;
+		selectionCache.current = {
+			ctrl,
+			ctrlState: state,
+			source: value,
+			selector: nextSelector,
+			eq: nextEq,
+			value: selectedValue
+		};
+		return selectedValue;
+	}, [ctrl]);
 	return useSyncExternalStore(useCallback((onStoreChange) => {
-		if (ctrl.state !== "resolved") return () => {};
-		return getOrCreateHandle().subscribe(onStoreChange);
-	}, [ctrl, getOrCreateHandle]), getSnapshot, getSnapshot);
+		return ctrl.on("*", onStoreChange);
+	}, [ctrl]), getSnapshot, getSnapshot);
 }
 
 //#endregion

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["atom"],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":["import { createContext, type ReactNode } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\n\n/**\n * React context for Lite.Scope.\n */\nconst ScopeContext = createContext<Lite.Scope | null>(null)\n\ninterface ScopeProviderProps {\n  scope: Lite.Scope\n  children: ReactNode\n}\n\n/**\n * Provider component for Lite.Scope.\n *\n * @example\n * ```tsx\n * <ScopeProvider scope={scope}>\n *   <App />\n * </ScopeProvider>\n * ```\n */\nfunction ScopeProvider({ scope, children }: ScopeProviderProps) {\n  return (\n    <ScopeContext.Provider value={scope}>\n      {children}\n    </ScopeContext.Provider>\n  )\n}\n\nexport { ScopeContext, ScopeProvider }\nexport type { ScopeProviderProps }\n","import { useCallback, useContext, useMemo, useRef, useSyncExternalStore } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\nimport { ScopeContext } from './context'\n\nconst pendingPromises = new WeakMap<Lite.Atom<unknown>, Promise<unknown>>()\n\nfunction getOrCreatePendingPromise<T>(atom: Lite.Atom<T>, ctrl: Lite.Controller<T>): Promise<T> {\n  let pending = pendingPromises.get(atom) as Promise<T> | undefined\n  if (!pending) {\n    pending = ctrl.resolve()\n    pendingPromises.set(atom, pending)\n    pending.finally(() => pendingPromises.delete(atom))\n  }\n  return pending\n}\n\n/**\n * Access the current Lite.Scope from context.\n *\n * @returns The current Lite.Scope instance from context\n * @throws When called outside of a ScopeProvider\n *\n * @example\n * ```tsx\n * const scope = useScope()\n * await scope.resolve(myAtom)\n * ```\n */\nfunction useScope(): Lite.Scope {\n  const scope = useContext(ScopeContext)\n  if (!scope) {\n    throw new Error(\"useScope must be used within a ScopeProvider\")\n  }\n  return scope\n}\n\n/**\n * Get a memoized controller for an atom.\n *\n * @param atom - The atom to create a controller for\n * @returns A memoized Lite.Controller instance\n *\n * @example\n * ```tsx\n * const ctrl = useController(counterAtom)\n * ctrl.set(ctrl.get() + 1)\n * ```\n */\nfunction useController<T>(atom: Lite.Atom<T>): Lite.Controller<T> {\n  const scope = useScope()\n  return useMemo(() => scope.controller(atom), [scope, atom])\n}\n\n/**\n * Subscribe to atom value with Suspense/ErrorBoundary integration.\n * Auto-resolves atoms lazily and throws cached Promise for Suspense.\n *\n * @param atom - The atom to read\n * @returns The current value of the atom\n *\n * @example\n * ```tsx\n * function UserProfile() {\n *   const user = useAtom(userAtom)\n *   return <div>{user.name}</div>\n * }\n * ```\n */\nfunction useAtom<T>(atom: Lite.Atom<T>): T {\n  const ctrl = useController(atom)\n  const atomRef = useRef(atom)\n  atomRef.current = atom\n\n  const getSnapshot = useCallback((): T => {\n    const state = ctrl.state\n    if (state === 'idle' || state === 'resolving') {\n      throw getOrCreatePendingPromise(atomRef.current, ctrl)\n    }\n    if (state === 'failed') {\n      throw ctrl.get()\n    }\n    return ctrl.get()\n  }, [ctrl])\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => ctrl.on('resolved', onStoreChange),\n    [ctrl]\n  )\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\n/**\n * Select a derived value from an atom with fine-grained reactivity.\n * Only re-renders when the selected value changes per equality function.\n *\n * @param atom - The atom to select from\n * @param selector - Function to extract a derived value\n * @param eq - Optional equality function\n * @returns The selected value\n *\n * @example\n * ```tsx\n * const name = useSelect(userAtom, user => user.name)\n * ```\n */\nfunction useSelect<T, S>(\n  atom: Lite.Atom<T>,\n  selector: (value: T) => S,\n  eq?: (a: S, b: S) => boolean\n): S {\n  const scope = useScope()\n  const ctrl = useController(atom)\n\n  const atomRef = useRef(atom)\n  atomRef.current = atom\n\n  const selectorRef = useRef(selector)\n  const eqRef = useRef(eq)\n  selectorRef.current = selector\n  eqRef.current = eq\n\n  const handleRef = useRef<{\n    scope: Lite.Scope\n    atom: Lite.Atom<T>\n    handle: Lite.SelectHandle<S>\n  } | null>(null)\n\n  const getOrCreateHandle = useCallback(() => {\n    if (\n      !handleRef.current ||\n      handleRef.current.scope !== scope ||\n      handleRef.current.atom !== atom\n    ) {\n      const handle = scope.select(atom, selectorRef.current, { eq: eqRef.current })\n      handleRef.current = { scope, atom, handle }\n    }\n    return handleRef.current.handle\n  }, [scope, atom])\n\n  const getSnapshot = useCallback((): S => {\n    const state = ctrl.state\n    if (state === 'idle' || state === 'resolving') {\n      throw getOrCreatePendingPromise(atomRef.current, ctrl)\n    }\n    if (state === 'failed') {\n      throw ctrl.get()\n    }\n    return getOrCreateHandle().get()\n  }, [ctrl, getOrCreateHandle])\n\n  const subscribe = useCallback((onStoreChange: () => void) => {\n    if (ctrl.state !== 'resolved') {\n      return () => {}\n    }\n    return getOrCreateHandle().subscribe(onStoreChange)\n  }, [ctrl, getOrCreateHandle])\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\nexport { useScope, useController, useAtom, useSelect }\n"],"mappings":";;;;;;;;AAMA,MAAM,eAAe,cAAiC,KAAK;;;;;;;;;;;AAiB3D,SAAS,cAAc,EAAE,OAAO,YAAgC;AAC9D,QACE,oBAAC,aAAa;EAAS,OAAO;EAC3B;GACqB;;;;;ACvB5B,MAAM,kCAAkB,IAAI,SAA+C;AAE3E,SAAS,0BAA6B,QAAoB,MAAsC;CAC9F,IAAI,UAAU,gBAAgB,IAAIA,OAAK;AACvC,KAAI,CAAC,SAAS;AACZ,YAAU,KAAK,SAAS;AACxB,kBAAgB,IAAIA,QAAM,QAAQ;AAClC,UAAQ,cAAc,gBAAgB,OAAOA,OAAK,CAAC;;AAErD,QAAO;;;;;;;;;;;;;;AAeT,SAAS,WAAuB;CAC9B,MAAM,QAAQ,WAAW,aAAa;AACtC,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,+CAA+C;AAEjE,QAAO;;;;;;;;;;;;;;AAeT,SAAS,cAAiB,QAAwC;CAChE,MAAM,QAAQ,UAAU;AACxB,QAAO,cAAc,MAAM,WAAWA,OAAK,EAAE,CAAC,OAAOA,OAAK,CAAC;;;;;;;;;;;;;;;;;AAkB7D,SAAS,QAAW,QAAuB;CACzC,MAAM,OAAO,cAAcA,OAAK;CAChC,MAAM,UAAU,OAAOA,OAAK;AAC5B,SAAQ,UAAUA;CAElB,MAAM,cAAc,kBAAqB;EACvC,MAAM,QAAQ,KAAK;AACnB,MAAI,UAAU,UAAU,UAAU,YAChC,OAAM,0BAA0B,QAAQ,SAAS,KAAK;AAExD,MAAI,UAAU,SACZ,OAAM,KAAK,KAAK;AAElB,SAAO,KAAK,KAAK;IAChB,CAAC,KAAK,CAAC;AAOV,QAAO,qBALW,aACf,kBAA8B,KAAK,GAAG,YAAY,cAAc,EACjE,CAAC,KAAK,CACP,EAEsC,aAAa,YAAY;;;;;;;;;;;;;;;;AAiBlE,SAAS,UACP,QACA,UACA,IACG;CACH,MAAM,QAAQ,UAAU;CACxB,MAAM,OAAO,cAAcA,OAAK;CAEhC,MAAM,UAAU,OAAOA,OAAK;AAC5B,SAAQ,UAAUA;CAElB,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,QAAQ,OAAO,GAAG;AACxB,aAAY,UAAU;AACtB,OAAM,UAAU;CAEhB,MAAM,YAAY,OAIR,KAAK;CAEf,MAAM,oBAAoB,kBAAkB;AAC1C,MACE,CAAC,UAAU,WACX,UAAU,QAAQ,UAAU,SAC5B,UAAU,QAAQ,SAASA,OAG3B,WAAU,UAAU;GAAE;GAAO;GAAM,QADpB,MAAM,OAAOA,QAAM,YAAY,SAAS,EAAE,IAAI,MAAM,SAAS,CAAC;GAClC;AAE7C,SAAO,UAAU,QAAQ;IACxB,CAAC,OAAOA,OAAK,CAAC;CAEjB,MAAM,cAAc,kBAAqB;EACvC,MAAM,QAAQ,KAAK;AACnB,MAAI,UAAU,UAAU,UAAU,YAChC,OAAM,0BAA0B,QAAQ,SAAS,KAAK;AAExD,MAAI,UAAU,SACZ,OAAM,KAAK,KAAK;AAElB,SAAO,mBAAmB,CAAC,KAAK;IAC/B,CAAC,MAAM,kBAAkB,CAAC;AAS7B,QAAO,qBAPW,aAAa,kBAA8B;AAC3D,MAAI,KAAK,UAAU,WACjB,cAAa;AAEf,SAAO,mBAAmB,CAAC,UAAU,cAAc;IAClD,CAAC,MAAM,kBAAkB,CAAC,EAEU,aAAa,YAAY"}
+{"version":3,"file":"index.mjs","names":["atom","data: T | undefined","error: Error | undefined","result: UseAtomState<T>","value: T"],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":["import { createContext, type ReactNode } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\n\n/**\n * React context for Lite.Scope.\n */\nconst ScopeContext = createContext<Lite.Scope | null>(null)\n\ninterface ScopeProviderProps {\n  scope: Lite.Scope\n  children: ReactNode\n}\n\n/**\n * Provider component for Lite.Scope.\n *\n * @example\n * ```tsx\n * <ScopeProvider scope={scope}>\n *   <App />\n * </ScopeProvider>\n * ```\n */\nfunction ScopeProvider({ scope, children }: ScopeProviderProps) {\n  return (\n    <ScopeContext.Provider value={scope}>\n      {children}\n    </ScopeContext.Provider>\n  )\n}\n\nexport { ScopeContext, ScopeProvider }\nexport type { ScopeProviderProps }\n","import { useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\nimport { ScopeContext } from './context'\n\ninterface UseAtomSuspenseOptions {\n  suspense?: true\n  /** @default true */\n  resolve?: boolean\n}\n\ninterface UseAtomManualOptions {\n  suspense: false\n  /** @default false */\n  resolve?: boolean\n}\n\ntype UseAtomOptions = UseAtomSuspenseOptions | UseAtomManualOptions\n\ninterface UseAtomState<T> {\n  data: T | undefined\n  loading: boolean\n  error: Error | undefined\n  controller: Lite.Controller<T>\n}\n\ninterface UseControllerOptions {\n  resolve?: boolean\n}\n\nconst pendingPromises = new WeakMap<Lite.Controller<unknown>, Promise<unknown>>()\n\nfunction getOrCreatePendingPromise<T>(ctrl: Lite.Controller<T>): Promise<T> {\n  let pending = pendingPromises.get(ctrl) as Promise<T> | undefined\n  if (!pending) {\n    if (ctrl.state === 'resolving') {\n      pending = new Promise<T>((resolve, reject) => {\n        const unsub = ctrl.on('*', () => {\n          if (ctrl.state === 'resolved') {\n            unsub()\n            resolve(ctrl.get())\n          } else if (ctrl.state === 'failed') {\n            unsub()\n            try { ctrl.get() } catch (e) { reject(e) }\n          }\n        })\n      })\n    } else {\n      pending = ctrl.resolve()\n    }\n    pendingPromises.set(ctrl, pending)\n    void pending.catch(() => {})\n    pending.then(\n      () => pendingPromises.delete(ctrl),\n      () => pendingPromises.delete(ctrl)\n    )\n  }\n  return pending\n}\n\n/**\n * Access the current Lite.Scope from context.\n *\n * @returns The current Lite.Scope instance from context\n * @throws When called outside of a ScopeProvider\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const scope = useScope()\n *   const handleClick = () => scope.resolve(myAtom)\n * }\n * ```\n */\nfunction useScope(): Lite.Scope {\n  const scope = useContext(ScopeContext)\n  if (!scope) {\n    throw new Error(\"useScope must be used within a ScopeProvider\")\n  }\n  return scope\n}\n\n/**\n * Get a memoized controller for an atom.\n *\n * @example\n * ```tsx\n * const ctrl = useController(counterAtom)\n * ctrl.set(ctrl.get() + 1)\n * ```\n */\nfunction useController<T>(atom: Lite.Atom<T>): Lite.Controller<T>\nfunction useController<T>(atom: Lite.Atom<T>, options: UseControllerOptions): Lite.Controller<T>\nfunction useController<T>(atom: Lite.Atom<T>, options?: UseControllerOptions): Lite.Controller<T> {\n  const scope = useScope()\n  const ctrl = useMemo(() => scope.controller(atom), [scope, atom])\n\n  if (options?.resolve) {\n    if (ctrl.state === 'idle' || ctrl.state === 'resolving') {\n      throw getOrCreatePendingPromise(ctrl)\n    }\n    if (ctrl.state === 'failed') {\n      throw ctrl.get()\n    }\n  }\n\n  return ctrl\n}\n\n/**\n * Subscribe to atom value with Suspense/ErrorBoundary integration.\n *\n * @example\n * ```tsx\n * const user = useAtom(userAtom)\n * const { data, loading, error } = useAtom(userAtom, { suspense: false })\n * ```\n */\nfunction useAtom<T>(atom: Lite.Atom<T>): T\nfunction useAtom<T>(atom: Lite.Atom<T>, options: UseAtomSuspenseOptions): T\nfunction useAtom<T>(atom: Lite.Atom<T>, options: UseAtomManualOptions): UseAtomState<T>\nfunction useAtom<T>(atom: Lite.Atom<T>, options?: UseAtomOptions): T | UseAtomState<T> {\n  const ctrl = useController(atom)\n  const ctrlState = ctrl.state\n\n  const isSuspense = options?.suspense !== false\n  const autoResolve = isSuspense ? options?.resolve !== false : !!options?.resolve\n\n  const stateCache = useRef<{\n    ctrl: Lite.Controller<T>\n    ctrlState: Lite.Controller<T>['state']\n    data: T | undefined\n    error: Error | undefined\n    loading: boolean\n    result: UseAtomState<T>\n  } | null>(null)\n\n  useEffect(() => {\n    if (!isSuspense && (ctrlState === 'resolving' || (autoResolve && ctrlState === 'idle'))) {\n      void getOrCreatePendingPromise(ctrl).catch(() => {})\n    }\n  }, [ctrl, ctrlState, autoResolve, isSuspense])\n\n  const getSnapshot = useCallback((): T | UseAtomState<T> => {\n    if (isSuspense) {\n      if (ctrl.state === 'idle') {\n        if (autoResolve) {\n          throw getOrCreatePendingPromise(ctrl)\n        }\n        throw new Error('Atom is not resolved. Set resolve: true or resolve the atom before rendering.')\n      }\n      if (ctrl.state === 'failed') {\n        throw ctrl.get()\n      }\n      try {\n        return ctrl.get()\n      } catch {\n        throw getOrCreatePendingPromise(ctrl)\n      }\n    }\n\n    let data: T | undefined\n    let error: Error | undefined\n\n    if (ctrl.state === 'resolved' || ctrl.state === 'resolving') {\n      try {\n        data = ctrl.get()\n      } catch {}\n    } else if (ctrl.state === 'failed') {\n      try {\n        ctrl.get()\n      } catch (e) {\n        error = e instanceof Error ? e : new Error(String(e))\n      }\n    }\n\n    const loading = ctrl.state === 'resolving' || (autoResolve && ctrl.state === 'idle')\n\n    if (\n      stateCache.current &&\n      stateCache.current.ctrl === ctrl &&\n      stateCache.current.ctrlState === ctrl.state &&\n      stateCache.current.data === data &&\n      stateCache.current.error === error &&\n      stateCache.current.loading === loading\n    ) {\n      return stateCache.current.result\n    }\n\n    const result: UseAtomState<T> = {\n      data,\n      loading,\n      error,\n      controller: ctrl,\n    }\n\n    stateCache.current = { ctrl, ctrlState: ctrl.state, data, error, loading, result }\n    return result\n  }, [ctrl, autoResolve, isSuspense])\n\n  const subscribe = useCallback((onStoreChange: () => void) => {\n    return ctrl.on('*', () => {\n      if (!isSuspense && ctrl.state === 'resolving') {\n        void getOrCreatePendingPromise(ctrl).catch(() => {})\n      }\n      onStoreChange()\n    })\n  }, [ctrl, isSuspense])\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\n/**\n * Select a derived value from an atom with fine-grained reactivity.\n * Only re-renders when the selected value changes per equality function.\n *\n * @param atom - The atom to select from\n * @param selector - Function to extract a derived value\n * @param eq - Optional equality function\n * @returns The selected value\n *\n * @example\n * ```tsx\n * const name = useSelect(userAtom, user => user.name)\n * ```\n */\nfunction useSelect<T, S>(\n  atom: Lite.Atom<T>,\n  selector: (value: T) => S,\n  eq?: (a: S, b: S) => boolean\n): S {\n  const ctrl = useController(atom)\n\n  const selectorRef = useRef(selector)\n  const eqRef = useRef(eq)\n  selectorRef.current = selector\n  eqRef.current = eq\n\n  const selectionCache = useRef<{\n    ctrl: Lite.Controller<T>\n    ctrlState: Lite.Controller<T>['state']\n    source: T\n    selector: (value: T) => S\n    eq: ((a: S, b: S) => boolean) | undefined\n    value: S\n  } | null>(null)\n\n  const getSnapshot = useCallback((): S => {\n    const state = ctrl.state\n    if (state === 'idle') {\n      throw getOrCreatePendingPromise(ctrl)\n    }\n    if (state === 'failed') {\n      throw ctrl.get()\n    }\n    let value: T\n    try {\n      value = ctrl.get()\n    } catch {\n      throw getOrCreatePendingPromise(ctrl)\n    }\n\n    const nextSelector = selectorRef.current\n    const nextEq = eqRef.current\n    const current = selectionCache.current\n    if (\n      current &&\n      current.ctrl === ctrl &&\n      current.ctrlState === state &&\n      Object.is(current.source, value) &&\n      current.selector === nextSelector &&\n      current.eq === nextEq\n    ) {\n      return current.value\n    }\n\n    const nextValue = nextSelector(value)\n    const selectedValue = current &&\n      current.ctrl === ctrl &&\n      current.selector === nextSelector &&\n      (nextEq ?? Object.is)(current.value, nextValue)\n      ? current.value\n      : nextValue\n\n    selectionCache.current = {\n      ctrl,\n      ctrlState: state,\n      source: value,\n      selector: nextSelector,\n      eq: nextEq,\n      value: selectedValue,\n    }\n\n    return selectedValue\n  }, [ctrl])\n\n  const subscribe = useCallback((onStoreChange: () => void) => {\n    return ctrl.on('*', onStoreChange)\n  }, [ctrl])\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\nexport { useScope, useController, useAtom, useSelect }\nexport type { UseAtomSuspenseOptions, UseAtomManualOptions, UseAtomOptions, UseAtomState, UseControllerOptions }\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pumped-fn/lite-react",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "React integration for @pumped-fn/lite",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -31,13 +31,14 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
-    "@types/react": "^18.3.18",
-    "jsdom": "^27.2.0",
+    "@types/node": "^20.19.22",
+    "@types/react": "^18.3.27",
+    "jsdom": "^27.3.0",
     "react": "^18.3.1",
-    "tsdown": "^0.16.5",
+    "tsdown": "^0.17.2",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.5",
-    "@pumped-fn/lite": "1.6.0"
+    "vitest": "^4.0.18",
+    "@pumped-fn/lite": "2.1.2"
   },
   "engines": {
     "node": ">=18"