raf-effect-atom 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,14 +1,20 @@
 # Changelog
 
+## [0.2.5](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.4...raf-effect-atom%400.2.5) (2026-10-23)
+
+### Features
+
+* **raf-effect-atom:** start a derived atom's source from the loader verbs, following initialValueTarget ([00a9760](https://github.com/KATT/raf-effect-atom/commit/00a97602068cabf085fa9cfe41e88bf853b6af32))
+
 ## [0.2.4](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.3...raf-effect-atom%400.2.4) (2026-10-23)
 
 ### Features
 
-* **raf-effect-atom:** start a request registry with initialValues, readable atoms included ([67cf767](https://github.com/KATT/raf-effect-atom/commit/67cf767e121e76b385ff0808a087efc6662aed89))
+- **raf-effect-atom:** start a request registry with initialValues, readable atoms included ([67cf767](https://github.com/KATT/raf-effect-atom/commit/67cf767e121e76b385ff0808a087efc6662aed89))
 
 ### Documentation
 
-* correct the generated changelogs' cut-off breaking change and bogus issue links ([c21f64c](https://github.com/KATT/raf-effect-atom/commit/c21f64cad3b4638f2341968aa2e10af5a19904c1))
+- correct the generated changelogs' cut-off breaking change and bogus issue links ([c21f64c](https://github.com/KATT/raf-effect-atom/commit/c21f64cad3b4638f2341968aa2e10af5a19904c1))
 
 ## [0.2.3](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.2...raf-effect-atom%400.2.3) (2026-10-23)
 

package/dist/Hooks.mjs

@@ -2,10 +2,9 @@
 import { stream } from "./internal/pending.mjs";
 import { hydrated } from "./Hydration.mjs";
 import { keyOf, release } from "./internal/leases.mjs";
-import { atomOf } from "./internal/handles.mjs";
+import { atomOf, sourceOf } from "./internal/handles.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";
@@ -20,15 +19,6 @@ import * as React from "react";
 * @since 0.1.0
 */
 /**
-* The atom the loader started and the server sent: the first serializable
-* atom in `atom`'s `initialValueTarget` chain, starting with `atom`. An
-* AtomRpc query is serializable itself, though it points at an inner atom.
-*/
-const sourceOf = (atom) => {
-	for (let target = atom; target !== void 0; target = target.initialValueTarget) if (Atom.isSerializable(target)) return target;
-	return atom;
-};
-/**
 * 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.
 *

package/dist/Loader.d.mts

@@ -40,10 +40,24 @@ 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 suspends
- * until the result settles. On a request registry whose async seed is still
- * running, it waits for the seed first.
+ * - 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
+ *   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
+ *   result.
+ *
+ * **Gotchas**
+ *
+ * The server sends a result still loading as a promise only when the atom
+ * it sends holds an `AsyncResult`. A derived atom whose serializable atom
+ * holds another value, such as an `Option` snapshot, crosses with the value
+ * it has when the registry is dehydrated: point it at an `AsyncResult`
+ * atom, or `ensure` it.
  *
  * **Example**
  *

package/dist/Loader.mjs

@@ -2,7 +2,7 @@ import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { hydrated } from "./Hydration.mjs";
 import { isDevelopment } from "./internal/development.mjs";
 import { keyOf, take } from "./internal/leases.mjs";
-import { atomOf, loaded as loaded$1, make as make$1 } from "./internal/handles.mjs";
+import { atomOf, loaded as loaded$1, make as make$1, sourceOf } from "./internal/handles.mjs";
 import { afterSeed, pending } from "./internal/seeds.mjs";
 import { isRequestRegistry } from "./RequestRegistry.mjs";
 import * as Atom from "effect/reactivity/Atom";
@@ -70,14 +70,16 @@ const start = Effect.fnUntraced(function* (atom) {
 	const seed = pending(registry);
 	if (seed !== void 0) yield* Effect.promise(() => seed);
 	const request = isRequestRegistry(registry);
-	if (request && !Atom.isSerializable(atom) && (yield* isDevelopment)) return yield* Effect.die(/* @__PURE__ */ new Error(`raf-effect-atom: a loader started ${String(atom)}, which isn't serializable, so the browser would request it again. Give it a serialization key, such as AtomRpc's serializationKey option.`));
+	const source = sourceOf(atom);
+	if (request && !Atom.isSerializable(source) && (yield* isDevelopment)) return yield* Effect.die(/* @__PURE__ */ new Error(`raf-effect-atom: a loader started ${String(atom)}, which isn't serializable and doesn't point at a serializable atom with initialValueTarget, so the browser would request it again. Give it a serialization key, such as AtomRpc's serializationKey option.`));
 	const ttl = request ? void 0 : Duration.toMillis(yield* LeaseTTL);
-	const target = hydrated(atom);
+	const target = hydrated(source);
 	const key = keyOf(target);
 	const existed = registry.getNodes().has(key) || Predicate.isString(key) && registry.preloadedSerializable.has(key);
 	take(registry, target, ttl);
 	return {
 		existed,
+		read: source === atom ? hydrated(atom) : atom,
 		registry,
 		request,
 		target
@@ -115,10 +117,24 @@ 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 suspends
-* until the result settles. On a request registry whose async seed is still
-* running, it waits for the seed first.
+* - 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
+*   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
+*   result.
+*
+* **Gotchas**
+*
+* The server sends a result still loading as a promise only when the atom
+* it sends holds an `AsyncResult`. A derived atom whose serializable atom
+* holds another value, such as an `Option` snapshot, crosses with the value
+* it has when the registry is dehydrated: point it at an `AsyncResult`
+* atom, or `ensure` it.
 *
 * **Example**
 *
@@ -181,7 +197,7 @@ const loaded = (args, atom, result) => {
 const ensure = (source, ...args) => Effect.gen(function* () {
 	const atom = atomOf(source, args);
 	const started = yield* start(atom);
-	const result = yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+	const result = yield* settled(started.registry, started.read, started.request ? isSettled : AsyncResult.isNotInitial);
 	return loaded(args, atom, result);
 });
 /**
@@ -207,12 +223,12 @@ const ensure = (source, ...args) => Effect.gen(function* () {
 const fetch = (source, ...args) => Effect.gen(function* () {
 	const atom = atomOf(source, args);
 	const started = yield* start(atom);
-	const { registry, target } = started;
-	if (started.existed && isSettled(registry.get(target))) {
+	const { read, registry, target } = started;
+	if (started.existed && isSettled(registry.get(read))) {
 		const node = registry.getNodes().get(keyOf(target));
-		registry.refresh(node?.atom ?? target);
+		registry.refresh(read === target ? node?.atom ?? target : read);
 	}
-	const result = yield* settled(registry, target, isSettled);
+	const result = yield* settled(registry, read, isSettled);
 	return loaded(args, atom, result);
 });
 const results = /* @__PURE__ */ new WeakMap();

package/dist/Waterfalls.d.mts

@@ -72,12 +72,9 @@ 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`.
- *
- * **Gotchas**
- *
- * Pass it the source a loader would start, not an error boundary's
- * `wrap(source)`: the wrapper's atoms aren't serializable, so the server
- * couldn't send them to the browser. Read the handle through the wrapper.
+ * - A derived source, such as an error boundary's `wrap(source)`, starts
+ *   the serializable atom its `initialValueTarget` chain points at, as
+ *   `Loader.prefetch` does.
  *
  * **Example**
  *

package/dist/Waterfalls.mjs

@@ -2,7 +2,7 @@
 import { get } from "./internal/pending.mjs";
 import { hydrated } from "./Hydration.mjs";
 import { keyOf } from "./internal/leases.mjs";
-import { atomOf, make } from "./internal/handles.mjs";
+import { atomOf, make, sourceOf } from "./internal/handles.mjs";
 import { prefetch } from "./Loader.mjs";
 import { ModeContext, isStarted } from "./internal/waterfalls.mjs";
 import * as Predicate from "effect/Predicate";
@@ -76,12 +76,9 @@ 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`.
-*
-* **Gotchas**
-*
-* Pass it the source a loader would start, not an error boundary's
-* `wrap(source)`: the wrapper's atoms aren't serializable, so the server
-* couldn't send them to the browser. Read the handle through the wrapper.
+* - A derived source, such as an error boundary's `wrap(source)`, starts
+*   the serializable atom its `initialValueTarget` chain points at, as
+*   `Loader.prefetch` does.
 *
 * **Example**
 *
@@ -103,7 +100,7 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 const useWaterfall = (source, ...args) => {
 	const registry = React.useContext(RegistryContext);
 	const atom = atomOf(source, args);
-	const target = hydrated(atom);
+	const target = hydrated(sourceOf(atom));
 	const key = keyOf(target);
 	if (!(Predicate.isString(key) && get(registry, key) !== void 0) && !isStarted(registry, target)) return Effect.runSync(Effect.provideService(prefetch(source, ...args), AtomRegistry.AtomRegistry, registry));
 	return make(args, atom);

package/dist/internal/handles.mjs

@@ -4,9 +4,18 @@ import * as Predicate from "effect/Predicate";
 // src/internal/handles.ts
 /** The atom a source makes for its arguments. */
 const atomOf = (source, args) => Atom.isAtom(source) ? source : source(...args);
-/** The registry key a handle records: the atom's serialization key. */
+/**
+* The atom the loader starts and the server sends for `atom`: the first
+* serializable atom in its `initialValueTarget` chain, starting with `atom`.
+* An AtomRpc query is serializable itself, though it points at an inner atom.
+*/
+const sourceOf = (atom) => {
+	for (let target = atom; target !== void 0; target = target.initialValueTarget) if (Atom.isSerializable(target)) return target;
+	return atom;
+};
+/** The registry key a handle records: its source atom's serialization key. */
 const keyOf = (atom) => {
-	const key = keyOf$1(atom);
+	const key = keyOf$1(sourceOf(atom));
 	if (!Predicate.isString(key)) return;
 	return key;
 };
@@ -19,4 +28,4 @@ const loaded = (args, atom) => ({
 	key: keyOf(atom),
 	loaded: true
 });
-export { atomOf, loaded, make };
+export { atomOf, loaded, make, sourceOf };

package/package.json

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