raf-effect-atom 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,14 +1,41 @@
 # Changelog
 
+## [0.3.2](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.3.1...raf-effect-atom%400.3.2) (2026-10-24)
+
+### Bug Fixes
+
+* **raf-effect-atom:** take no lease on an atom a mounted component reads ([899d0b7](https://github.com/KATT/raf-effect-atom/commit/899d0b7c70f6836c41c4416b0c2063c1ccf3d8b2))
+
+## [0.3.1](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.3.0...raf-effect-atom%400.3.1) (2026-10-24)
+
+### Features
+
+- **raf-effect-atom:** add useHandleValue, a handle read that doesn't suspend ([4b083f7](https://github.com/KATT/raf-effect-atom/commit/4b083f7dee91834cda71691f44a1498061f3cfe1))
+
+### Code Refactoring
+
+- name files in kebab-case, PascalCase only for Effect modules ([d76b06a](https://github.com/KATT/raf-effect-atom/commit/d76b06aef3d04d6be6c0b0e086a756234ab3f253))
+
+### Documentation
+
+- **raf-effect-atom:** pass a read's result to a boundary's hook in the README and JSDoc ([fd82e5c](https://github.com/KATT/raf-effect-atom/commit/fd82e5c1f92b3f99dc166140383837b11b695ca7))
+- **raf-effect-atom:** pass the atom to a boundary's hook in the README and JSDoc ([772d349](https://github.com/KATT/raf-effect-atom/commit/772d3494954f64a5c0fc92ebfd146b5f14e16e51))
+
+### Tests
+
+- **raf-effect-atom:** pass a read's result to a boundary's hook ([df11247](https://github.com/KATT/raf-effect-atom/commit/df11247edab69b060c0677059ae24a4d8835c28e))
+- **raf-effect-atom:** read through a boundary's hook with the atom ([de19b85](https://github.com/KATT/raf-effect-atom/commit/de19b8502ef41a8efbd9b50da6e00843cb38f2fd))
+- **raf-effect-atom:** start an Atom.swr over a keyed readable that picks a seed or a live query ([697e785](https://github.com/KATT/raf-effect-atom/commit/697e78550bff0dce02903b963677828786770338))
+
 ## [0.3.0](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.6...raf-effect-atom%400.3.0) (2026-10-23)
 
 ### ⚠ BREAKING CHANGES
 
-* **raf-effect-atom:** `raf-effect-atom/next` is `raf-effect-atom/rsc`, without `dehydrate`; write `<HydrationBoundary registry={getRegistry()}>` from `raf-effect-atom` instead of `<HydrateAtoms state={await dehydrate()}>`, and import `RegistryProvider` from `raf-effect-atom`.
+- **raf-effect-atom:** `raf-effect-atom/next` is `raf-effect-atom/rsc`, without `dehydrate`; write `<HydrationBoundary registry={getRegistry()}>` from `raf-effect-atom` instead of `<HydrateAtoms state={await dehydrate()}>`, and import `RegistryProvider` from `raf-effect-atom`.
 
 ### Features
 
-* **raf-effect-atom:** import HydrationBoundary from raf-effect-atom in server components, and the RSC verbs from raf-effect-atom/rsc ([bf7fdbc](https://github.com/KATT/raf-effect-atom/commit/bf7fdbcde2e9f785bd276a08117aefa359051b82))
+- **raf-effect-atom:** import HydrationBoundary from raf-effect-atom in server components, and the RSC verbs from raf-effect-atom/rsc ([bf7fdbc](https://github.com/KATT/raf-effect-atom/commit/bf7fdbcde2e9f785bd276a08117aefa359051b82))
 
 ## [0.2.6](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.5...raf-effect-atom%400.2.6) (2026-10-23)
 

package/README.md

@@ -37,13 +37,13 @@ export async function loader(args: LoaderArgs) {
 }
 ```
 
-A component takes the handle as a prop and reads it with `useAtomResult(source, handle)`, which waits for a streamed result instead of starting the atom again, and returns typed failures. Given a handle instead of an id, it can't start a request of its own. The source can be a family derived from the loader's, such as the one an [`effect-atom-boundary`](https://github.com/KATT/raf-effect-atom/tree/main/packages/effect-atom-boundary) boundary's `wrap` returns, which throws the errors that boundary claims to it:
+A component takes the handle as a prop and reads it with `useAtomResult(source, handle)`, which waits for a streamed result instead of starting the atom again, and returns typed failures. Given a handle instead of an id, it can't start a request of its own. An [`effect-atom-boundary`](https://github.com/KATT/raf-effect-atom/tree/main/packages/effect-atom-boundary) boundary's hook takes the result, throws the errors that boundary claims to it, and returns the rest:
 
 ```tsx
 import { type Handle, useAtomResult } from "raf-effect-atom";
 
 function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
-	const result = useAtomResult(useIssueBoundary().wrap(issue), props.issue);
+	const result = useIssueBoundary(useAtomResult(issue, props.issue));
 	// Success<Issue, never>: its boundaries claim every failure
 	return <h1>{result.value.title}</h1>;
 }

package/dist/Loader.d.mts

@@ -1,4 +1,4 @@
-import { ArgsOf, ErrorOf, Handle, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
+import { ArgsOf, ErrorOf, Handle, LoadedHandle, Source, SuccessOf } from "./handle.mjs";
 import * as Context from "effect/Context";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -21,9 +21,11 @@ export type SettledResult<A, E> = AsyncResult.Failure<A, E> | AsyncResult.Succes
  *
  * **Details**
  *
- * A lease ends when `useAtomResult` mounts the atom, or when this time has
- * passed, after which the registry's idle TTL applies as usual. On a request
- * registry, leases last until the registry is disposed.
+ * A lease ends when `useAtomResult` or `useHandleValue` mounts the atom, or
+ * when this time has passed, after which the registry's idle TTL applies as
+ * usual. While a component reads the atom, a verb takes no lease on it, so the
+ * atom goes idle when the last reader unmounts. On a request registry, leases
+ * last until the registry is disposed.
  *
  * @stability unstable
  * @category references
@@ -41,14 +43,14 @@ export declare const LeaseTTL: Context.Reference<Duration.Duration>;
  * **Details**
  *
  * - Starts the atom if it isn't in the registry, and leaves it alone if it
- *   is. Takes a lease either way. The component that reads the handle
+ *   is. Takes a lease either way, unless a mounted component reads the
+ *   atom. The component that reads the handle
  *   suspends until the result settles. On a request registry whose async
  *   seed is still running, it waits for the seed first.
- * - A derived atom that isn't serializable, such as an error boundary's
- *   `wrap(source)`, starts the first serializable atom its
- *   `initialValueTarget` chain points at, the one `useAtomResult` reads it
- *   through: the lease, the handle's key and what the server sends are
- *   that atom's. `ensure` and `fetch` wait for the derived atom's own
+ * - A derived atom that isn't serializable starts the first serializable
+ *   atom its `initialValueTarget` chain points at, the one `useAtomResult`
+ *   reads it through: the lease, the handle's key and what the server sends
+ *   are that atom's. `ensure` and `fetch` wait for the derived atom's own
  *   result.
  *
  * **Gotchas**

package/dist/Loader.mjs

@@ -60,9 +60,11 @@ var Loader_exports = /* @__PURE__ */ __exportAll({
 *
 * **Details**
 *
-* A lease ends when `useAtomResult` mounts the atom, or when this time has
-* passed, after which the registry's idle TTL applies as usual. On a request
-* registry, leases last until the registry is disposed.
+* A lease ends when `useAtomResult` or `useHandleValue` mounts the atom, or
+* when this time has passed, after which the registry's idle TTL applies as
+* usual. While a component reads the atom, a verb takes no lease on it, so the
+* atom goes idle when the last reader unmounts. On a request registry, leases
+* last until the registry is disposed.
 *
 * @stability unstable
 * @category references
@@ -122,14 +124,14 @@ const rejectDefects = (result) => {
 * **Details**
 *
 * - Starts the atom if it isn't in the registry, and leaves it alone if it
-*   is. Takes a lease either way. The component that reads the handle
+*   is. Takes a lease either way, unless a mounted component reads the
+*   atom. The component that reads the handle
 *   suspends until the result settles. On a request registry whose async
 *   seed is still running, it waits for the seed first.
-* - A derived atom that isn't serializable, such as an error boundary's
-*   `wrap(source)`, starts the first serializable atom its
-*   `initialValueTarget` chain points at, the one `useAtomResult` reads it
-*   through: the lease, the handle's key and what the server sends are
-*   that atom's. `ensure` and `fetch` wait for the derived atom's own
+* - A derived atom that isn't serializable starts the first serializable
+*   atom its `initialValueTarget` chain points at, the one `useAtomResult`
+*   reads it through: the lease, the handle's key and what the server sends
+*   are that atom's. `ensure` and `fetch` wait for the derived atom's own
 *   result.
 *
 * **Gotchas**

package/dist/{ReactHydration.react-server.d.mts → hydration-boundary-react-server.d.mts}

@@ -1,4 +1,4 @@
-import { HydrationBoundaryProps } from "./ReactHydration.mjs";
+import { HydrationBoundaryProps } from "./hydration-boundary.mjs";
 import * as React from "react";
 /**
  * Sends a server component's request registry to the client components

package/dist/{ReactHydration.react-server.mjs → hydration-boundary-react-server.mjs}

@@ -1,8 +1,8 @@
 import { dehydrate } from "./Hydration.mjs";
 import { isRequestRegistry, settled } from "./RequestRegistry.mjs";
-import { HydrationBoundary as HydrationBoundary$1 } from "./ReactHydration.mjs";
+import { HydrationBoundary as HydrationBoundary$1 } from "./hydration-boundary.mjs";
 import { jsx } from "react/jsx-runtime";
-// src/ReactHydration.react-server.tsx
+// src/hydration-boundary-react-server.tsx
 /**
 * Sends a server component's request registry to the client components
 * under it.

package/dist/{ReactHydration.mjs → hydration-boundary.mjs}

@@ -5,7 +5,7 @@ import { isServer, requireRequestRegistry } from "./internal/registry.mjs";
 import { HydrationBoundary, RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-// src/ReactHydration.tsx
+// src/hydration-boundary.tsx
 /**
 * Applies a server registry's dehydrated state to the nearest
 * `RegistryContext`, while rendering.

package/dist/{index.react-server.d.mts → index-react-server.d.mts}

@@ -1,11 +1,11 @@
-import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
+import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./handle.mjs";
+import { Hydration_d_exports } from "./Hydration.mjs";
 import { Loader_d_exports } from "./Loader.mjs";
 import { RequestRegistry_d_exports } from "./RequestRegistry.mjs";
-import { Hydration_d_exports } from "./Hydration.mjs";
-import { useAtomResult } from "./Hooks.mjs";
-import { HydrationBoundaryProps } from "./ReactHydration.mjs";
-import { RegistryProvider } from "./RegistryProvider.mjs";
-import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
-import "./index.shared.mjs";
-import { HydrationBoundary } from "./ReactHydration.react-server.mjs";
-export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, HydrationBoundary, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };
+import { useAtomResult, useHandleValue } from "./use-atom-result.mjs";
+import { HydrationBoundaryProps } from "./hydration-boundary.mjs";
+import { RegistryProvider } from "./registry-provider.mjs";
+import { WaterfallDetection, WaterfallMode, useWaterfall } from "./waterfalls.mjs";
+import "./index-shared.mjs";
+import { HydrationBoundary } from "./hydration-boundary-react-server.mjs";
+export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, HydrationBoundary, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useHandleValue, useWaterfall };

package/dist/index-react-server.mjs

@@ -0,0 +1,8 @@
+import { Hydration_exports } from "./Hydration.mjs";
+import { RequestRegistry_exports } from "./RequestRegistry.mjs";
+import { Loader_exports } from "./Loader.mjs";
+import { useAtomResult, useHandleValue } from "./use-atom-result.mjs";
+import { RegistryProvider } from "./registry-provider.mjs";
+import { WaterfallDetection, useWaterfall } from "./waterfalls.mjs";
+import { HydrationBoundary } from "./hydration-boundary-react-server.mjs";
+export { Hydration_exports as Hydration, HydrationBoundary, Loader_exports as Loader, RegistryProvider, RequestRegistry_exports as RequestRegistry, WaterfallDetection, useAtomResult, useHandleValue, useWaterfall };

package/dist/{index.shared.d.mts → index-shared.d.mts}

@@ -1,9 +1,9 @@
-import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
+import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./handle.mjs";
+import { Hydration_d_exports } from "./Hydration.mjs";
 import { Loader_d_exports } from "./Loader.mjs";
 import { RequestRegistry_d_exports } from "./RequestRegistry.mjs";
-import { Hydration_d_exports } from "./Hydration.mjs";
-import { useAtomResult } from "./Hooks.mjs";
-import { HydrationBoundaryProps } from "./ReactHydration.mjs";
-import { RegistryProvider } from "./RegistryProvider.mjs";
-import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
-export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };
+import { useAtomResult, useHandleValue } from "./use-atom-result.mjs";
+import { HydrationBoundaryProps } from "./hydration-boundary.mjs";
+import { RegistryProvider } from "./registry-provider.mjs";
+import { WaterfallDetection, WaterfallMode, useWaterfall } from "./waterfalls.mjs";
+export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useHandleValue, useWaterfall };

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
+import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./handle.mjs";
+import { Hydration_d_exports } from "./Hydration.mjs";
 import { Loader_d_exports } from "./Loader.mjs";
 import { RequestRegistry_d_exports } from "./RequestRegistry.mjs";
-import { Hydration_d_exports } from "./Hydration.mjs";
-import { useAtomResult } from "./Hooks.mjs";
-import { HydrationBoundary, HydrationBoundaryProps } from "./ReactHydration.mjs";
-import { RegistryProvider } from "./RegistryProvider.mjs";
-import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
-import "./index.shared.mjs";
-export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, HydrationBoundary, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };
+import { useAtomResult, useHandleValue } from "./use-atom-result.mjs";
+import { HydrationBoundary, HydrationBoundaryProps } from "./hydration-boundary.mjs";
+import { RegistryProvider } from "./registry-provider.mjs";
+import { WaterfallDetection, WaterfallMode, useWaterfall } from "./waterfalls.mjs";
+import "./index-shared.mjs";
+export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, HydrationBoundary, type HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RegistryProvider, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useHandleValue, useWaterfall };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { Hydration_exports } from "./Hydration.mjs";
 import { RequestRegistry_exports } from "./RequestRegistry.mjs";
 import { Loader_exports } from "./Loader.mjs";
-import { useAtomResult } from "./Hooks.mjs";
-import { RegistryProvider } from "./RegistryProvider.mjs";
-import { WaterfallDetection, useWaterfall } from "./Waterfalls.mjs";
-import { HydrationBoundary } from "./ReactHydration.mjs";
-export { Hydration_exports as Hydration, HydrationBoundary, Loader_exports as Loader, RegistryProvider, RequestRegistry_exports as RequestRegistry, WaterfallDetection, useAtomResult, useWaterfall };
+import { useAtomResult, useHandleValue } from "./use-atom-result.mjs";
+import { RegistryProvider } from "./registry-provider.mjs";
+import { WaterfallDetection, useWaterfall } from "./waterfalls.mjs";
+import { HydrationBoundary } from "./hydration-boundary.mjs";
+export { Hydration_exports as Hydration, HydrationBoundary, Loader_exports as Loader, RegistryProvider, RequestRegistry_exports as RequestRegistry, WaterfallDetection, useAtomResult, useHandleValue, useWaterfall };

package/dist/internal/leases.mjs

@@ -1,39 +1,60 @@
 import * as Atom from "effect/reactivity/Atom";
 // src/internal/leases.ts
-const leases = /* @__PURE__ */ new WeakMap();
+const registries = /* @__PURE__ */ new WeakMap();
+const leasesOf = (registry) => {
+	let state = registries.get(registry);
+	if (state === void 0) {
+		state = {
+			leases: /* @__PURE__ */ new Map(),
+			readers: /* @__PURE__ */ new Map()
+		};
+		registries.set(registry, state);
+	}
+	return state;
+};
 /** The registry's key for an atom: its serialization key, or the atom. */
 const keyOf = (atom) => Atom.isSerializable(atom) ? atom[Atom.SerializableTypeId].key : atom;
 /**
 * Mounts `atom` until `release`, or until `ttl` milliseconds pass. Taking a
-* lease the atom already has restarts its timer.
+* lease the atom already has restarts its timer. While a component holds the
+* atom (see `hold`), it takes none: the component keeps the atom mounted, and
+* a lease would keep it mounted after the component unmounts.
 */
 const take = (registry, atom, ttl) => {
-	let byKey = leases.get(registry);
-	if (byKey === void 0) {
-		byKey = /* @__PURE__ */ new Map();
-		leases.set(registry, byKey);
-	}
+	const state = leasesOf(registry);
 	const key = keyOf(atom);
-	let lease = byKey.get(key);
+	if (state.readers.has(key)) return;
+	let lease = state.leases.get(key);
 	if (lease === void 0) {
 		const unmount = registry.mount(atom);
-		const owner = byKey;
 		const created = {
 			release: () => {
 				clearTimeout(created.timer);
-				owner.delete(key);
+				state.leases.delete(key);
 				unmount();
 			},
 			timer: void 0
 		};
-		byKey.set(key, created);
+		state.leases.set(key, created);
 		lease = created;
 	}
 	clearTimeout(lease.timer);
 	lease.timer = ttl === void 0 ? void 0 : setTimeout(lease.release, ttl);
 };
-/** Releases `atom`'s lease, if it has one. */
-const release = (registry, atom) => {
-	leases.get(registry)?.get(keyOf(atom))?.release();
+/**
+* Marks `atom` as held by a component subscribed to it, until the returned
+* function runs. Ends the atom's lease, and `take` takes none while any
+* component holds it.
+*/
+const hold = (registry, atom) => {
+	const state = leasesOf(registry);
+	const key = keyOf(atom);
+	state.readers.set(key, (state.readers.get(key) ?? 0) + 1);
+	state.leases.get(key)?.release();
+	return () => {
+		const count = (state.readers.get(key) ?? 1) - 1;
+		if (count === 0) state.readers.delete(key);
+		else state.readers.set(key, count);
+	};
 };
-export { keyOf, release, take };
+export { hold, keyOf, take };

package/dist/{ReactRouter.mjs → react-router.mjs}

@@ -3,7 +3,7 @@ import { make, settled } from "./RequestRegistry.mjs";
 import { make as make$1 } from "./Loader.mjs";
 import { current } from "./internal/registry.mjs";
 import * as Predicate from "effect/Predicate";
-// src/ReactRouter.ts
+// src/react-router.ts
 /**
 * Connects the loader verbs to React Router's Framework Mode.
 *

package/dist/{RegistryProvider.mjs → registry-provider.mjs}

@@ -3,7 +3,7 @@ import { make, mount } from "./internal/registry.mjs";
 import { RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-// src/RegistryProvider.tsx
+// src/registry-provider.tsx
 /**
 * The registry provider for apps that render the server's state through
 * `HydrationBoundary`, such as React Server Components and React Router.

package/dist/{Rsc.d.mts → rsc.d.mts}

@@ -1,4 +1,4 @@
-import { ArgsOf, Handle, LoadedHandle, Source } from "./Handle.mjs";
+import { ArgsOf, Handle, LoadedHandle, Source } from "./handle.mjs";
 import { Loader } from "./Loader.mjs";
 import { Options } from "./RequestRegistry.mjs";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";

package/dist/{Rsc.mjs → rsc.mjs}

@@ -1,5 +1,5 @@
 import { make } from "./internal/rsc.mjs";
-// src/Rsc.ts
+// src/rsc.ts
 /**
 * Creates the verbs and `getRegistry` over a request registry that `seed`
 * prepares.

package/dist/{TanStackRouter.mjs → tanstack-router.mjs}

@@ -5,7 +5,7 @@ import * as Predicate from "effect/Predicate";
 import { RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-// src/TanStackRouter.tsx
+// src/tanstack-router.tsx
 /**
 * Connects the loader verbs to TanStack Router and TanStack Start.
 *

package/dist/{Hooks.d.mts → use-atom-result.d.mts}

@@ -1,11 +1,11 @@
-import { ErrorOf, Handle, Source, SuccessOf } from "./Handle.mjs";
+import { ErrorOf, Handle, Source, SuccessOf } from "./handle.mjs";
 import { SettledResult } from "./Loader.mjs";
 import * as Atom from "effect/reactivity/Atom";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
 /**
  * A source with the same arguments and success type as `S`, and any error:
- * the sources whose handles `S` reads, such as the source an error
- * boundary's `wrap(S)` wraps.
+ * the sources whose handles `S` reads, such as the source a derived `S`
+ * points at.
  */
 type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.AsyncResult<infer A, infer _E>>) ? (...args: Args) => Atom.Atom<AsyncResult.AsyncResult<A, unknown>> : S extends Atom.Atom<AsyncResult.AsyncResult<infer A, infer _E>> ? Atom.Atom<AsyncResult.AsyncResult<A, unknown>> : never;
 /**
@@ -16,8 +16,9 @@ type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.Asy
  *
  * Use in the component a loader, a server component or `useWaterfall` gave
  * the handle to. The source can be the one the verb started, or one derived
- * from it whose atoms point at its atoms with `initialValueTarget`, such as
- * an error boundary's `wrap(source)`.
+ * from it whose atoms point at its atoms with `initialValueTarget`. To send
+ * some failures to an error boundary, pass the result to the boundary's hook,
+ * such as `useIssueBoundary(useAtomResult(issue, handle))`.
  *
  * **Details**
  *
@@ -33,13 +34,14 @@ type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.Asy
  *   instead of started, so the browser doesn't request it a second time.
  * - The atom is read through `hydrated`, so a hydrated result is kept.
  * - Once the component mounts, the loader's lease ends and the component
- *   keeps the atom mounted.
+ *   keeps the atom mounted. A loader that starts the atom again while it's
+ *   mounted takes no lease, so the atom goes idle when the component unmounts.
  * - A derived atom is read through the first serializable atom its
  *   `initialValueTarget` chain points at: that one is awaited, hydrated and
  *   released, so the derived atom doesn't request it again.
  * - The settled result is returned, typed failures included. A defect is
- *   thrown to the error boundaries above. With no typed failures left, such
- *   as an atom whose boundaries claim all of them, it's typed as a success.
+ *   thrown to the error boundaries above. With no typed failures, it's typed
+ *   as a success.
  * - While a failed atom refreshes, such as after a boundary's `reset`, the
  *   read suspends instead of returning the old failure again.
  *
@@ -64,8 +66,8 @@ type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.Asy
  * `Atom.transform`'s `initialValueTarget` option points at the end of the
  * target's own chain, which for an AtomRpc query with `reactivityKeys` is an
  * inner atom with no serialization key. A derived atom read here sets
- * `initialValueTarget` to its source itself, as an error boundary's
- * wrapper does, or it requests the source again after hydration.
+ * `initialValueTarget` to its source itself, or it requests the source again
+ * after hydration.
  *
  * **Example**
  *
@@ -86,4 +88,61 @@ type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.Asy
  * @since 0.1.0
  */
 export declare const useAtomResult: <S extends Source>(source: S, handle: NoInfer<Handle<Readable<S>>>) => [ErrorOf<S>] extends [never] ? AsyncResult.Success<SuccessOf<S>, never> : SettledResult<SuccessOf<S>, ErrorOf<S>>;
+/**
+ * Reads a handle without React Suspense, through the source that made it,
+ * and returns the atom's current result as it is.
+ *
+ * **When to use**
+ *
+ * Use where a component renders every state of the read itself: its loading
+ * state, a failure that stays on the page while the atom refreshes, or a
+ * defect. Otherwise prefer `useAtomResult`, which suspends until the result
+ * settles and sends defects to the error boundaries above.
+ *
+ * **Details**
+ *
+ * - It reads the atom as `useAtomResult` does: through `hydrated`, through
+ *   the serializable atom a derived source points at, and with the same
+ *   development checks on the handle's key and on request waterfalls.
+ * - It returns `Initial` while the atom loads, and while a result the server
+ *   was still loading streams in. It doesn't read the atom until the stream
+ *   settles, so the browser doesn't request it a second time.
+ * - A failure is returned as it is, `waiting` while the atom refreshes, and
+ *   so is a defect.
+ * - Once the component has subscribed to the atom, the loader's lease ends
+ *   and the component keeps the atom mounted. A loader that starts the atom
+ *   again while it's mounted takes no lease, so the atom goes idle when the
+ *   component unmounts.
+ * - A handle `Loader.prefetchInBrowser` returned on the server reads as
+ *   `Initial` there, without starting the atom; the browser's read starts
+ *   it.
+ *
+ * **Gotchas**
+ *
+ * The server renders what the read returns, `Initial` for a result still
+ * loading, and the browser's first render has to match it: render the same
+ * loading state for every `Initial`.
+ *
+ * During server rendering, the registry must be a request registry (see
+ * `RequestRegistry.make`): in development, the hook throws without one.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { AsyncResult } from "effect/reactivity"
+ * import { type Handle, useHandleValue } from "raf-effect-atom"
+ *
+ * function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+ *   const result = useHandleValue(issue, props.issue)
+ *   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : <p>Loading…</p>
+ * }
+ * ```
+ *
+ * @see {@link useAtomResult} for a read that suspends until the result settles
+ *
+ * @stability unstable
+ * @category hooks
+ * @since 0.3.1
+ */
+export declare const useHandleValue: <S extends Source>(source: S, handle: NoInfer<Handle<Readable<S>>>) => AsyncResult.AsyncResult<SuccessOf<S>, ErrorOf<S>>;
 export {};

package/dist/{Hooks.mjs → use-atom-result.mjs}

@@ -1,24 +1,37 @@
 "use client";
-import { stream } from "./internal/pending.mjs";
+import { get, stream } from "./internal/pending.mjs";
 import { hydrated } from "./Hydration.mjs";
-import { keyOf, release } from "./internal/leases.mjs";
+import { hold, keyOf } from "./internal/leases.mjs";
 import { atomOf, sourceOf } from "./internal/handles.mjs";
 import { isRequestRegistry } from "./RequestRegistry.mjs";
 import { requireRequestRegistry } from "./internal/registry.mjs";
 import { ModeContext, check } from "./internal/waterfalls.mjs";
+import * as Atom from "effect/reactivity/Atom";
 import * as Predicate from "effect/Predicate";
 import * as Cause from "effect/Cause";
 import * as Option from "effect/Option";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
-import { RegistryContext, useAtomSuspense } from "@effect/atom-react";
+import { RegistryContext, useAtomSuspense, useAtomValue } from "@effect/atom-react";
 import * as React from "react";
-// src/Hooks.ts
+// src/use-atom-result.ts
 /**
-* The read hook for atoms started by loaders and streamed from the server.
+* The read hooks for atoms started by loaders and streamed from the server.
 *
 * @stability unstable
 * @since 0.1.0
 */
+const targetsOf = (atom, handle, hook) => {
+	const target = sourceOf(atom);
+	const started = hydrated(target);
+	const read = target === atom ? hydrated(atom) : atom;
+	const key = keyOf(started);
+	if (process.env.NODE_ENV !== "production" && handle.key !== void 0 && Predicate.isString(key) && handle.key !== key) throw new Error(`raf-effect-atom: ${hook} read the handle of ${handle.key} through a source that makes ${key}. Read a handle through the source that made it.`);
+	return {
+		key,
+		read,
+		started
+	};
+};
 /**
 * Reads a handle through React Suspense, through the source that made it: a
 * result streamed from the server, a hydrated one, or one a loader started.
@@ -27,8 +40,9 @@ import * as React from "react";
 *
 * Use in the component a loader, a server component or `useWaterfall` gave
 * the handle to. The source can be the one the verb started, or one derived
-* from it whose atoms point at its atoms with `initialValueTarget`, such as
-* an error boundary's `wrap(source)`.
+* from it whose atoms point at its atoms with `initialValueTarget`. To send
+* some failures to an error boundary, pass the result to the boundary's hook,
+* such as `useIssueBoundary(useAtomResult(issue, handle))`.
 *
 * **Details**
 *
@@ -44,13 +58,14 @@ import * as React from "react";
 *   instead of started, so the browser doesn't request it a second time.
 * - The atom is read through `hydrated`, so a hydrated result is kept.
 * - Once the component mounts, the loader's lease ends and the component
-*   keeps the atom mounted.
+*   keeps the atom mounted. A loader that starts the atom again while it's
+*   mounted takes no lease, so the atom goes idle when the component unmounts.
 * - A derived atom is read through the first serializable atom its
 *   `initialValueTarget` chain points at: that one is awaited, hydrated and
 *   released, so the derived atom doesn't request it again.
 * - The settled result is returned, typed failures included. A defect is
-*   thrown to the error boundaries above. With no typed failures left, such
-*   as an atom whose boundaries claim all of them, it's typed as a success.
+*   thrown to the error boundaries above. With no typed failures, it's typed
+*   as a success.
 * - While a failed atom refreshes, such as after a boundary's `reset`, the
 *   read suspends instead of returning the old failure again.
 *
@@ -75,8 +90,8 @@ import * as React from "react";
 * `Atom.transform`'s `initialValueTarget` option points at the end of the
 * target's own chain, which for an AtomRpc query with `reactivityKeys` is an
 * inner atom with no serialization key. A derived atom read here sets
-* `initialValueTarget` to its source itself, as an error boundary's
-* wrapper does, or it requests the source again after hydration.
+* `initialValueTarget` to its source itself, or it requests the source again
+* after hydration.
 *
 * **Example**
 *
@@ -101,12 +116,9 @@ const useAtomResult = (source, handle) => {
 	const atom = atomOf(source, handle.args);
 	requireRequestRegistry(registry, "useAtomResult");
 	if (handle.inBrowser === true && isRequestRegistry(registry)) throw new Error(`raf-effect-atom: ${String(atom)} starts in the browser (Loader.prefetchInBrowser), so the server renders the nearest Suspense boundary's fallback, and the browser renders the boundary.`);
-	const target = sourceOf(atom);
-	const started = hydrated(target);
-	const read = target === atom ? hydrated(atom) : atom;
-	const key = keyOf(started);
-	if (process.env.NODE_ENV !== "production" && handle.key !== void 0 && Predicate.isString(key) && handle.key !== key) throw new Error(`raf-effect-atom: useAtomResult read the handle of ${handle.key} through a source that makes ${key}. Read a handle through the source that made it.`);
-	const streamed = Predicate.isString(key) ? stream(registry, key) : void 0;
+	const targets = targetsOf(atom, handle, "useAtomResult");
+	const { read, started } = targets;
+	const streamed = Predicate.isString(targets.key) ? stream(registry, targets.key) : void 0;
 	if (streamed !== void 0) React.use(streamed);
 	if (process.env.NODE_ENV !== "production" && handle.inBrowser !== true) check(registry, started, React.use(ModeContext));
 	if (read !== started) registry.get(started);
@@ -115,10 +127,100 @@ const useAtomResult = (source, handle) => {
 		includeFailure: true,
 		suspendOnWaiting: AsyncResult.isFailure(current) && current.waiting
 	});
-	React.useEffect(() => {
-		release(registry, started);
-	}, [registry, started]);
+	React.useEffect(() => hold(registry, started), [registry, started]);
 	if (AsyncResult.isFailure(result) && Option.isNone(Cause.findErrorOption(result.cause))) throw Cause.squash(result.cause);
 	return result;
 };
-export { useAtomResult };
+/** What a read shows while it can't read the atom yet. */
+const loading = Atom.make(AsyncResult.initial(true));
+/**
+* Reads a handle without React Suspense, through the source that made it,
+* and returns the atom's current result as it is.
+*
+* **When to use**
+*
+* Use where a component renders every state of the read itself: its loading
+* state, a failure that stays on the page while the atom refreshes, or a
+* defect. Otherwise prefer `useAtomResult`, which suspends until the result
+* settles and sends defects to the error boundaries above.
+*
+* **Details**
+*
+* - It reads the atom as `useAtomResult` does: through `hydrated`, through
+*   the serializable atom a derived source points at, and with the same
+*   development checks on the handle's key and on request waterfalls.
+* - It returns `Initial` while the atom loads, and while a result the server
+*   was still loading streams in. It doesn't read the atom until the stream
+*   settles, so the browser doesn't request it a second time.
+* - A failure is returned as it is, `waiting` while the atom refreshes, and
+*   so is a defect.
+* - Once the component has subscribed to the atom, the loader's lease ends
+*   and the component keeps the atom mounted. A loader that starts the atom
+*   again while it's mounted takes no lease, so the atom goes idle when the
+*   component unmounts.
+* - A handle `Loader.prefetchInBrowser` returned on the server reads as
+*   `Initial` there, without starting the atom; the browser's read starts
+*   it.
+*
+* **Gotchas**
+*
+* The server renders what the read returns, `Initial` for a result still
+* loading, and the browser's first render has to match it: render the same
+* loading state for every `Initial`.
+*
+* During server rendering, the registry must be a request registry (see
+* `RequestRegistry.make`): in development, the hook throws without one.
+*
+* **Example**
+*
+* ```tsx
+* import { AsyncResult } from "effect/reactivity"
+* import { type Handle, useHandleValue } from "raf-effect-atom"
+*
+* function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+*   const result = useHandleValue(issue, props.issue)
+*   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : <p>Loading…</p>
+* }
+* ```
+*
+* @see {@link useAtomResult} for a read that suspends until the result settles
+*
+* @stability unstable
+* @category hooks
+* @since 0.3.1
+*/
+const useHandleValue = (source, handle) => {
+	const registry = React.useContext(RegistryContext);
+	const atom = atomOf(source, handle.args);
+	requireRequestRegistry(registry, "useHandleValue");
+	const targets = targetsOf(atom, handle, "useHandleValue");
+	const { started } = targets;
+	const streamed = Predicate.isString(targets.key) ? get(registry, targets.key) : void 0;
+	const [, settled] = React.useReducer((count) => count + 1, 0);
+	React.useEffect(() => {
+		if (streamed === void 0) return;
+		let active = true;
+		const rerender = () => {
+			if (active) settled();
+		};
+		streamed.then(rerender, rerender);
+		return () => {
+			active = false;
+		};
+	}, [streamed]);
+	const waiting = streamed !== void 0 || handle.inBrowser === true && isRequestRegistry(registry);
+	if (!waiting) {
+		if (process.env.NODE_ENV !== "production" && handle.inBrowser !== true) check(registry, started, React.use(ModeContext));
+		if (targets.read !== started) registry.get(started);
+	}
+	const result = useAtomValue(waiting ? loading : targets.read);
+	React.useEffect(() => {
+		if (!waiting) return hold(registry, started);
+	}, [
+		registry,
+		started,
+		waiting
+	]);
+	return result;
+};
+export { useAtomResult, useHandleValue };

package/dist/{Waterfalls.d.mts → waterfalls.d.mts}

@@ -1,4 +1,4 @@
-import { ArgsOf, Handle, Source } from "./Handle.mjs";
+import { ArgsOf, Handle, Source } from "./handle.mjs";
 import { Mode } from "./internal/waterfalls.mjs";
 import * as React from "react";
 /**
@@ -72,9 +72,8 @@ export declare const WaterfallDetection: (props: {
  * - `useAtomResult` doesn't report an atom started this way.
  * - The handle is a prefetched one: its reader suspends until the result
  *   settles, as for a handle from a loader's `prefetch`.
- * - A derived source, such as an error boundary's `wrap(source)`, starts
- *   the serializable atom its `initialValueTarget` chain points at, as
- *   `Loader.prefetch` does.
+ * - A derived source starts the serializable atom its `initialValueTarget`
+ *   chain points at, as `Loader.prefetch` does.
  *
  * **Example**
  *

package/dist/{Waterfalls.mjs → waterfalls.mjs}

@@ -11,7 +11,7 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import { RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-// src/Waterfalls.tsx
+// src/waterfalls.tsx
 /**
 * Request waterfalls: the escape hatch for atoms only a render can start,
 * and the development check that finds the others.
@@ -76,9 +76,8 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 * - `useAtomResult` doesn't report an atom started this way.
 * - The handle is a prefetched one: its reader suspends until the result
 *   settles, as for a handle from a loader's `prefetch`.
-* - A derived source, such as an error boundary's `wrap(source)`, starts
-*   the serializable atom its `initialValueTarget` chain points at, as
-*   `Loader.prefetch` does.
+* - A derived source starts the serializable atom its `initialValueTarget`
+*   chain points at, as `Loader.prefetch` does.
 *
 * **Example**
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
   "keywords": [
     "effect",
@@ -34,12 +34,12 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "react-server": "./dist/index.react-server.mjs",
+      "react-server": "./dist/index-react-server.mjs",
       "default": "./dist/index.mjs"
     },
-    "./react-router": "./dist/ReactRouter.mjs",
-    "./rsc": "./dist/Rsc.mjs",
-    "./tanstack-router": "./dist/TanStackRouter.mjs"
+    "./react-router": "./dist/react-router.mjs",
+    "./rsc": "./dist/rsc.mjs",
+    "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "peerDependencies": {
     "@effect/atom-react": "^4.0.6",
@@ -61,7 +61,7 @@
     "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "5.0.5",
     "effect": "4.0.6",
-    "effect-atom-boundary": "0.1.2",
+    "effect-atom-boundary": "0.3.0",
     "happy-dom": "21.0.4",
     "react": "19.3.1",
     "react-dom": "19.3.1",

package/dist/index.react-server.mjs

@@ -1,8 +0,0 @@
-import { Hydration_exports } from "./Hydration.mjs";
-import { RequestRegistry_exports } from "./RequestRegistry.mjs";
-import { Loader_exports } from "./Loader.mjs";
-import { useAtomResult } from "./Hooks.mjs";
-import { RegistryProvider } from "./RegistryProvider.mjs";
-import { WaterfallDetection, useWaterfall } from "./Waterfalls.mjs";
-import { HydrationBoundary } from "./ReactHydration.react-server.mjs";
-export { Hydration_exports as Hydration, HydrationBoundary, Loader_exports as Loader, RegistryProvider, RequestRegistry_exports as RequestRegistry, WaterfallDetection, useAtomResult, useWaterfall };