raf-effect-atom 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,16 +1,32 @@
 # 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))
+
+### Documentation
+
+- 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)
 
 ### Features
 
-* **raf-effect-atom:** run Effect code on a loader's registry with Loader.Loader.run ([d26307d](https://github.com/KATT/raf-effect-atom/commit/d26307dc6279106ebd9d26078c88e4ad10a8cbc9))
+- **raf-effect-atom:** run Effect code on a loader's registry with Loader.Loader.run ([d26307d](https://github.com/KATT/raf-effect-atom/commit/d26307dc6279106ebd9d26078c88e4ad10a8cbc9))
 
 ## [0.2.2](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.1...raf-effect-atom%400.2.2) (2026-10-23)
 
 ### Features
 
-- **raf-effect-atom:** stop a loader's wait when its request is aborted ([b1f2f16](https://github.com/KATT/raf-effect-atom/commit/b1f2f16fcce9cd5dd1ba18fa653b40c805eebd93)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#40](https://github.com/KATT/raf-effect-atom/issues/40) [#40](https://github.com/KATT/raf-effect-atom/issues/40) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+- **raf-effect-atom:** stop a loader's wait when its request is aborted ([b1f2f16](https://github.com/KATT/raf-effect-atom/commit/b1f2f16fcce9cd5dd1ba18fa653b40c805eebd93))
 
 ### Bug Fixes
 
@@ -25,13 +41,13 @@
 
 ### Features
 
-- **raf-effect-atom:** run React Router loaders in the browser after the first page ([bee00a9](https://github.com/KATT/raf-effect-atom/commit/bee00a981fd24fcdc9d746053dcd73dbc7ebc853)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+- **raf-effect-atom:** run React Router loaders in the browser after the first page ([bee00a9](https://github.com/KATT/raf-effect-atom/commit/bee00a981fd24fcdc9d746053dcd73dbc7ebc853))
 
 ## [0.2.0](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.1.0...raf-effect-atom%400.2.0) (2026-10-23)
 
 ### ⚠ BREAKING CHANGES
 
-- **raf-effect-atom:** `dehydrate()` from `raf-effect-atom/next` returns a
+- **raf-effect-atom:** `dehydrate()` from `raf-effect-atom/next` returns a promise: write `<HydrateAtoms state={await dehydrate()}>`.
 
 ### Features
 
@@ -123,7 +139,7 @@
 
 ### Bug Fixes
 
-- **raf-effect-atom:** call use() on a streamed result's promise on every render that reads it ([36d2aaa](https://github.com/KATT/raf-effect-atom/commit/36d2aaa8bacf18a60507e4997fd61476d7a908c0)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+- **raf-effect-atom:** call use() on a streamed result's promise on every render that reads it ([36d2aaa](https://github.com/KATT/raf-effect-atom/commit/36d2aaa8bacf18a60507e4997fd61476d7a908c0))
 - **raf-effect-atom:** point waterfall reports at the URL before the escape hatches ([0d127e3](https://github.com/KATT/raf-effect-atom/commit/0d127e38a10cb3a44340c5540c75b53491faceee))
 - **raf-effect-atom:** refresh the atom the registry runs for a key in Loader.fetch ([0b35c97](https://github.com/KATT/raf-effect-atom/commit/0b35c97b4de60de254c7fc921b89aed7be753ec8))
 - **raf-effect-atom:** wait for results streamed in a server component payload ([00cb981](https://github.com/KATT/raf-effect-atom/commit/00cb98125aad2cda70525fbfdedcd2b5a8f7fc79))

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/RequestRegistry.d.mts

@@ -1,8 +1,9 @@
 import { Seed as Seed$1 } from "./internal/seeds.mjs";
+import * as Atom from "effect/reactivity/Atom";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import * as Layer from "effect/Layer";
 declare namespace RequestRegistry_d_exports {
-  export { Options, Seed, isRequestRegistry, layer, make, settled };
+  export { InitialValues, Options, Seed, isRequestRegistry, layer, make, settled };
 }
 /**
  * Prepares a request registry before the loader verbs start atoms in it,
@@ -13,6 +14,16 @@ declare namespace RequestRegistry_d_exports {
  * @since 0.2.0
  */
 export type Seed = Seed$1;
+/**
+ * Atoms paired with the values a registry starts with, as
+ * `AtomRegistry.make`'s `initialValues` takes them: build each pair with
+ * `Atom.initialValue`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.4
+ */
+export type InitialValues = Iterable<readonly [Atom.Atom<any>, any, Atom.InitialValueOptions?]>;
 /**
  * Options for `make`.
  *
@@ -21,6 +32,14 @@ export type Seed = Seed$1;
  * @since 0.2.0
  */
 export interface Options {
+  /**
+   * Values the registry starts with, as `AtomRegistry.make`'s
+   * `initialValues`. Unlike `registry.set` in a seed, they reach readable
+   * atoms, such as one that provides a per-request service. The registry
+   * keeps each of these atoms mounted until it's disposed, so the value
+   * outlives the atoms that read it.
+   */
+  readonly initialValues?: InitialValues | undefined;
   /**
    * Runs on the new registry before any verb starts an atom in it. When it
    * returns a promise, `ensure` and `fetch` wait for it, and `prefetch`
@@ -38,10 +57,15 @@ export interface Options {
  *   in the background, and a loader's lease lasts until the registry is
  *   disposed. In development, the loader verbs refuse an atom that isn't
  *   serializable, because the browser would request it again.
+ * - `initialValues` are values the request's atoms start with, set on each
+ *   atom, or on the end of its `initialValueTarget` chain, before anything
+ *   reads it. They reach atoms `registry.set` can't, such as a readable atom
+ *   that provides the request's `fetch`, and each stays mounted until the
+ *   registry is disposed.
  * - `seed` sets what the request's atoms need before they run, such as the
  *   page request's cookie for an RPC protocol that forwards it. It can be
  *   async, for request data only a promise gives, such as Next.js's
- *   `headers()`.
+ *   `headers()`. It runs after `initialValues` are set.
  *
  * **Gotchas**
  *
@@ -52,9 +76,11 @@ export interface Options {
  * **Example**
  *
  * ```ts
+ * import { Atom } from "effect/reactivity"
  * import { RequestRegistry } from "raf-effect-atom"
  *
  * const registry = RequestRegistry.make({
+ *   initialValues: [Atom.initialValue(requestFetch, request.fetch)],
  *   seed: (registry) => registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
  * })
  * ```

package/dist/RequestRegistry.mjs

@@ -33,10 +33,15 @@ const requestRegistries = /* @__PURE__ */ new WeakSet();
 *   in the background, and a loader's lease lasts until the registry is
 *   disposed. In development, the loader verbs refuse an atom that isn't
 *   serializable, because the browser would request it again.
+* - `initialValues` are values the request's atoms start with, set on each
+*   atom, or on the end of its `initialValueTarget` chain, before anything
+*   reads it. They reach atoms `registry.set` can't, such as a readable atom
+*   that provides the request's `fetch`, and each stays mounted until the
+*   registry is disposed.
 * - `seed` sets what the request's atoms need before they run, such as the
 *   page request's cookie for an RPC protocol that forwards it. It can be
 *   async, for request data only a promise gives, such as Next.js's
-*   `headers()`.
+*   `headers()`. It runs after `initialValues` are set.
 *
 * **Gotchas**
 *
@@ -47,9 +52,11 @@ const requestRegistries = /* @__PURE__ */ new WeakSet();
 * **Example**
 *
 * ```ts
+* import { Atom } from "effect/reactivity"
 * import { RequestRegistry } from "raf-effect-atom"
 *
 * const registry = RequestRegistry.make({
+*   initialValues: [Atom.initialValue(requestFetch, request.fetch)],
 *   seed: (registry) => registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
 * })
 * ```
@@ -59,8 +66,10 @@ const requestRegistries = /* @__PURE__ */ new WeakSet();
 * @since 0.1.0
 */
 const make = (options) => {
-	const registry = AtomRegistry.make();
+	const initialValues = options?.initialValues === void 0 ? void 0 : Array.from(options.initialValues);
+	const registry = AtomRegistry.make({ initialValues });
 	requestRegistries.add(registry);
+	if (initialValues !== void 0) for (const [atom] of initialValues) registry.mount(atom);
 	if (options?.seed !== void 0) run(registry, options.seed);
 	return registry;
 };

package/dist/TanStackRouter.d.mts

@@ -1,4 +1,4 @@
-import { Seed } from "./RequestRegistry.mjs";
+import { InitialValues, Seed } from "./RequestRegistry.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import { AnyRouter } from "@tanstack/react-router";
@@ -39,6 +39,12 @@ export interface RouterAtomsOptions<TRouter extends AnyRouter> {
  *   default registry does. An atom's own `Atom.setIdleTTL` or
  *   `Atom.keepAlive` wins. The server's request registry lives for one
  *   request, so it has none.
+ * - `initialValues` are values both registries start with, as
+ *   `AtomRegistry.make`'s `initialValues`, such as the session the server
+ *   verified or a readable atom that provides the request's `fetch`. The
+ *   server's request registry keeps those atoms mounted until it's disposed.
+ *   The browser's registry drops an atom no component reads, value included,
+ *   so make one whose value must outlive its readers `Atom.keepAlive`.
  * - `seed` runs on the server's request registry before the loaders start
  *   atoms in it, as `RequestRegistry.make`'s does: set what the request's
  *   atoms need, such as its cookie. It can be async. The browser's registry
@@ -64,6 +70,7 @@ export interface RouterAtomsOptions<TRouter extends AnyRouter> {
  */
 export declare const makeRegistry: (options?: {
   readonly defaultIdleTTL?: number | undefined;
+  readonly initialValues?: InitialValues | undefined;
   readonly seed?: Seed | undefined;
 }) => AtomRegistry.AtomRegistry;
 /**

package/dist/TanStackRouter.mjs

@@ -51,6 +51,12 @@ import { jsx } from "react/jsx-runtime";
 *   default registry does. An atom's own `Atom.setIdleTTL` or
 *   `Atom.keepAlive` wins. The server's request registry lives for one
 *   request, so it has none.
+* - `initialValues` are values both registries start with, as
+*   `AtomRegistry.make`'s `initialValues`, such as the session the server
+*   verified or a readable atom that provides the request's `fetch`. The
+*   server's request registry keeps those atoms mounted until it's disposed.
+*   The browser's registry drops an atom no component reads, value included,
+*   so make one whose value must outlive its readers `Atom.keepAlive`.
 * - `seed` runs on the server's request registry before the loaders start
 *   atoms in it, as `RequestRegistry.make`'s does: set what the request's
 *   atoms need, such as its cookie. It can be async. The browser's registry

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/dist/internal/registry.mjs

@@ -19,8 +19,12 @@ const defaultIdleTTL = 400;
 * A request registry on the server, and in the browser a registry like
 * `@effect/atom-react`'s `RegistryProvider` makes.
 */
-const make = (options) => isServer() ? make$1({ seed: options?.seed }) : AtomRegistry.make({
+const make = (options) => isServer() ? make$1({
+	initialValues: options?.initialValues,
+	seed: options?.seed
+}) : AtomRegistry.make({
 	defaultIdleTTL: options?.defaultIdleTTL ?? defaultIdleTTL,
+	initialValues: options?.initialValues,
 	scheduleTask
 });
 let mounted;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.2.3",
+  "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",