raf-effect-atom 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,25 +1,37 @@
 # Changelog
 
+## [0.3.3](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.3.2...raf-effect-atom%400.3.3) (2026-10-24)
+
+### Bug Fixes
+
+* **raf-effect-atom:** name the fixes when useAtomResult throws for a browser-only handle on the server ([40b94d0](https://github.com/KATT/raf-effect-atom/commit/40b94d07947b65bb06d278cf47c855f4b8afdc78))
+
+## [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))
+- **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))
+- 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))
+- **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))
+- **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)
 

package/dist/Loader.d.mts

@@ -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,7 +43,8 @@ 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 starts the first serializable

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,7 +124,8 @@ 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 starts the first serializable

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/use-atom-result.d.mts

@@ -34,7 +34,8 @@ 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.
@@ -62,6 +63,12 @@ type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.Asy
  * `RequestRegistry.make`), or a module-level registry would share results
  * between requests: in development, the hook throws without one.
  *
+ * On the server, the hook throws for a handle `Loader.prefetchInBrowser`
+ * returned, so React renders the nearest Suspense boundary's fallback and
+ * reports the error. With no boundary between the read and the route, the
+ * server can't render the page. `useHandleValue` returns `Initial` there
+ * instead.
+ *
  * `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
@@ -109,7 +116,9 @@ export declare const useAtomResult: <S extends Source>(source: S, handle: NoInfe
  * - 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.
+ *   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.

package/dist/use-atom-result.mjs

@@ -1,7 +1,7 @@
 "use client";
 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";
@@ -58,7 +58,8 @@ const targetsOf = (atom, handle, hook) => {
 *   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.
@@ -86,6 +87,12 @@ const targetsOf = (atom, handle, hook) => {
 * `RequestRegistry.make`), or a module-level registry would share results
 * between requests: in development, the hook throws without one.
 *
+* On the server, the hook throws for a handle `Loader.prefetchInBrowser`
+* returned, so React renders the nearest Suspense boundary's fallback and
+* reports the error. With no boundary between the read and the route, the
+* server can't render the page. `useHandleValue` returns `Initial` there
+* instead.
+*
 * `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
@@ -114,7 +121,7 @@ const useAtomResult = (source, handle) => {
 	const registry = React.useContext(RegistryContext);
 	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.`);
+	if (handle.inBrowser === true && isRequestRegistry(registry)) throw new Error(`raf-effect-atom: ${String(atom)} starts in the browser (Loader.prefetchInBrowser), so useAtomResult throws on the server: React renders the nearest Suspense boundary's fallback, and the browser renders the boundary. Read it under a Suspense boundary inside the route, or with useHandleValue, which returns Initial on the server.`);
 	const targets = targetsOf(atom, handle, "useAtomResult");
 	const { read, started } = targets;
 	const streamed = Predicate.isString(targets.key) ? stream(registry, targets.key) : void 0;
@@ -126,9 +133,7 @@ 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;
 };
@@ -156,7 +161,9 @@ const loading = Atom.make(AsyncResult.initial(true));
 * - 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.
+*   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.
@@ -214,7 +221,7 @@ const useHandleValue = (source, handle) => {
 	}
 	const result = useAtomValue(waiting ? loading : targets.read);
 	React.useEffect(() => {
-		if (!waiting) release(registry, started);
+		if (!waiting) return hold(registry, started);
 	}, [
 		registry,
 		started,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
   "keywords": [
     "effect",