raf-effect-atom 0.0.0 → 0.2.0

package/dist/Loader.d.mts

@@ -1,11 +1,11 @@
-import * as Atom from "effect/reactivity/Atom";
+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";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 declare namespace Loader_d_exports {
-  export { LeaseTTL, Loader, SettledResult, ensure, fetch, make, prefetch };
+  export { LeaseTTL, Loader, SettledResult, ensure, fetch, make, prefetch, result };
 }
 /**
  * A settled `AsyncResult`: what `ensure` and `fetch` return.
@@ -31,7 +31,7 @@ export type SettledResult<A, E> = AsyncResult.Failure<A, E> | AsyncResult.Succes
  */
 export declare const LeaseTTL: Context.Reference<Duration.Duration>;
 /**
- * Starts an atom without waiting for it.
+ * Starts a source's atom without waiting for it, and returns its handle.
  *
  * **When to use**
  *
@@ -41,7 +41,9 @@ 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.
+ * 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.
  *
  * **Example**
  *
@@ -49,17 +51,17 @@ export declare const LeaseTTL: Context.Reference<Duration.Duration>;
  * import { Effect } from "effect"
  * import { Loader } from "raf-effect-atom"
  *
- * const program = Loader.prefetch(comments(1))
+ * const program = Loader.prefetch(commentPage, issueId, 0)
  * ```
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<void, never, AtomRegistry.AtomRegistry>;
+export declare const prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<Handle<S>, never, AtomRegistry.AtomRegistry>;
 /**
- * Starts an atom and returns its settled result, waiting only while it has
- * none.
+ * Starts a source's atom, waits only while it has no result, and returns a
+ * handle whose reader renders without suspending.
  *
  * **When to use**
  *
@@ -68,10 +70,11 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  *
  * **Details**
  *
- * An atom with a result returns it at once, without refetching. On a request
+ * An atom with a result returns at once, without refetching. On a request
  * registry, it also waits out a refresh in flight, so the server never
- * renders a result that's about to change. A typed failure is returned as
- * the result; a defect or an interruption fails the Effect.
+ * renders a result that's about to change. A typed failure settles it like
+ * a success: `result` returns it. A defect or an interruption fails the
+ * Effect.
  *
  * **Example**
  *
@@ -81,7 +84,8 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  * import { Loader } from "raf-effect-atom"
  *
  * const program = Effect.gen(function* () {
- *   const result = yield* Loader.ensure(issue(1))
+ *   const handle = yield* Loader.ensure(issue, 1)
+ *   const result = Loader.result(handle)
  *   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
  * })
  * ```
@@ -90,10 +94,11 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  * @category verbs
  * @since 0.1.0
  */
-export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<SettledResult<A, E>, never, AtomRegistry.AtomRegistry>;
+export declare const ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<LoadedHandle<S>, never, AtomRegistry.AtomRegistry>;
 /**
- * Starts an atom, or refreshes it if it has a result, and returns the new
- * settled result.
+ * Starts a source's atom, or refreshes it if it has a result, waits for the
+ * new result to settle, and returns a handle whose reader renders without
+ * suspending.
  *
  * **When to use**
  *
@@ -102,14 +107,45 @@ export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E
  *
  * **Details**
  *
- * Waits until the result settles and isn't refreshing. A typed failure is
- * returned as the result; a defect or an interruption fails the Effect.
+ * Waits until the result settles and isn't refreshing. A typed failure
+ * settles it like a success: `result` returns it. A defect or an
+ * interruption fails the Effect.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<SettledResult<A, E>, never, AtomRegistry.AtomRegistry>;
+export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<LoadedHandle<S>, never, AtomRegistry.AtomRegistry>;
+/**
+ * Returns the settled result `ensure` or `fetch` waited for.
+ *
+ * **When to use**
+ *
+ * Use in the loader that ran the verb, to branch on the result: redirect on
+ * a tag, or build another atom's arguments from it. Components read the
+ * handle with `useAtomResult`, which follows the registry.
+ *
+ * **Gotchas**
+ *
+ * Only the handle object the verb returned has it: a handle that crossed
+ * the network, as loader data or a server component's prop, is a copy, and
+ * this throws for it.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { AsyncResult } from "effect/reactivity"
+ * import { Loader } from "raf-effect-atom"
+ *
+ * const handle = await atoms.ensure(issue, id)
+ * const error = AsyncResult.error(Loader.result(handle))
+ * ```
+ *
+ * @stability unstable
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const result: <S extends Source>(handle: LoadedHandle<S>) => SettledResult<SuccessOf<S>, ErrorOf<S>>;
 /**
  * The loader verbs as Promises over one registry, as the framework
  * integrations put them on the router context.
@@ -120,11 +156,15 @@ export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>
  */
 export interface Loader {
   /** {@link ensure}, as a Promise that rejects only on a defect. */
-  readonly ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+  readonly ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
   /** {@link fetch}, as a Promise that rejects only on a defect. */
-  readonly fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
-  /** {@link prefetch}, run at once. */
-  readonly prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => void;
+  readonly fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
+  /**
+   * {@link prefetch}, run at once. On a request registry whose async seed is
+   * still running, it returns the handle at once and starts the atom once
+   * the seed resolves.
+   */
+  readonly prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
 }
 /**
  * Creates the Promise verbs over one registry.
@@ -143,8 +183,8 @@ export interface Loader {
  * import { Loader, RequestRegistry } from "raf-effect-atom"
  *
  * const loader = Loader.make(RequestRegistry.make())
- * loader.prefetch(comments(1))
- * const result = await loader.ensure(issue(1))
+ * const comments = loader.prefetch(commentPage, 1, 0)
+ * const issueHandle = await loader.ensure(issue, 1)
  * ```
  *
  * @stability unstable

package/dist/Loader.mjs

@@ -2,6 +2,8 @@ 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 { afterSeed, pending } from "./internal/seeds.mjs";
 import { isRequestRegistry } from "./RequestRegistry.mjs";
 import * as Atom from "effect/reactivity/Atom";
 import * as Predicate from "effect/Predicate";
@@ -17,9 +19,11 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 * Starts atoms from route loaders, before anything renders, so nothing
 * waterfalls.
 *
-* Each verb starts an `AsyncResult` atom in the registry and takes a lease
-* on it, so the registry's idle TTL can't evict it before the route renders
-* and `useAtomResult` takes it over:
+* Each verb takes a source, an atom family or an `AsyncResult` atom, with its
+* arguments. It starts the atom in the registry, takes a lease on it, so the
+* registry's idle TTL can't evict it before the route renders and
+* `useAtomResult` takes it over, and returns its handle for the component
+* that reads it:
 *
 * | Verb       | Starts the atom                 | Waits                         | Has a value already   |
 * | ---------- | ------------------------------- | ----------------------------- | --------------------- |
@@ -27,9 +31,10 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 * | `ensure`   | if it isn't in the registry     | only while it's `Initial`     | returns it at once    |
 * | `fetch`    | if it isn't, or refreshes it    | until the new result settles  | refreshes, then waits |
 *
-* Typed failures don't reject: `ensure` and `fetch` return the settled
-* `AsyncResult`, so a loader can redirect on a tag and otherwise let a
-* boundary render the failure. Only defects and interruptions reject.
+* Typed failures don't reject: `ensure` and `fetch` settle on them, and
+* `result` returns the settled `AsyncResult`, so a loader can redirect on a
+* tag and otherwise let a boundary render the failure. Only defects and
+* interruptions reject.
 *
 * The verbs are Effects that need the `AtomRegistry`; `make` gives the same
 * verbs as Promises over one registry, for loaders that are async functions.
@@ -42,7 +47,8 @@ var Loader_exports = /* @__PURE__ */ __exportAll({
 	ensure: () => ensure,
 	fetch: () => fetch,
 	make: () => make,
-	prefetch: () => prefetch
+	prefetch: () => prefetch,
+	result: () => result
 });
 /**
 * How long a loader's lease keeps an atom mounted when no component takes it
@@ -61,6 +67,8 @@ var Loader_exports = /* @__PURE__ */ __exportAll({
 const LeaseTTL = Context.Reference("raf-effect-atom/Loader/LeaseTTL", { defaultValue: () => Duration.seconds(30) });
 const start = Effect.fnUntraced(function* (atom) {
 	const registry = yield* AtomRegistry.AtomRegistry;
+	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 ttl = request ? void 0 : Duration.toMillis(yield* LeaseTTL);
@@ -98,7 +106,7 @@ const rejectDefects = (result) => {
 	return Effect.succeed(result);
 };
 /**
-* Starts an atom without waiting for it.
+* Starts a source's atom without waiting for it, and returns its handle.
 *
 * **When to use**
 *
@@ -108,7 +116,9 @@ 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.
+* 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.
 *
 * **Example**
 *
@@ -116,19 +126,26 @@ const rejectDefects = (result) => {
 * import { Effect } from "effect"
 * import { Loader } from "raf-effect-atom"
 *
-* const program = Loader.prefetch(comments(1))
+* const program = Loader.prefetch(commentPage, issueId, 0)
 * ```
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const prefetch = Effect.fnUntraced(function* (atom) {
+const prefetch = (source, ...args) => Effect.gen(function* () {
+	const atom = atomOf(source, args);
 	yield* start(atom);
+	return make$1(args, atom);
 });
+const loaded = (args, atom, result) => {
+	const handle = loaded$1(args, atom);
+	results.set(handle, result);
+	return handle;
+};
 /**
-* Starts an atom and returns its settled result, waiting only while it has
-* none.
+* Starts a source's atom, waits only while it has no result, and returns a
+* handle whose reader renders without suspending.
 *
 * **When to use**
 *
@@ -137,10 +154,11 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 *
 * **Details**
 *
-* An atom with a result returns it at once, without refetching. On a request
+* An atom with a result returns at once, without refetching. On a request
 * registry, it also waits out a refresh in flight, so the server never
-* renders a result that's about to change. A typed failure is returned as
-* the result; a defect or an interruption fails the Effect.
+* renders a result that's about to change. A typed failure settles it like
+* a success: `result` returns it. A defect or an interruption fails the
+* Effect.
 *
 * **Example**
 *
@@ -150,7 +168,8 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 * import { Loader } from "raf-effect-atom"
 *
 * const program = Effect.gen(function* () {
-*   const result = yield* Loader.ensure(issue(1))
+*   const handle = yield* Loader.ensure(issue, 1)
+*   const result = Loader.result(handle)
 *   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
 * })
 * ```
@@ -159,13 +178,16 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 * @category verbs
 * @since 0.1.0
 */
-const ensure = Effect.fnUntraced(function* (atom) {
+const ensure = (source, ...args) => Effect.gen(function* () {
+	const atom = atomOf(source, args);
 	const started = yield* start(atom);
-	return yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+	const result = yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+	return loaded(args, atom, result);
 });
 /**
-* Starts an atom, or refreshes it if it has a result, and returns the new
-* settled result.
+* Starts a source's atom, or refreshes it if it has a result, waits for the
+* new result to settle, and returns a handle whose reader renders without
+* suspending.
 *
 * **When to use**
 *
@@ -174,22 +196,60 @@ const ensure = Effect.fnUntraced(function* (atom) {
 *
 * **Details**
 *
-* Waits until the result settles and isn't refreshing. A typed failure is
-* returned as the result; a defect or an interruption fails the Effect.
+* Waits until the result settles and isn't refreshing. A typed failure
+* settles it like a success: `result` returns it. A defect or an
+* interruption fails the Effect.
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const fetch = Effect.fnUntraced(function* (atom) {
+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 node = registry.getNodes().get(keyOf(target));
 		registry.refresh(node?.atom ?? target);
 	}
-	return yield* settled(registry, target, isSettled);
+	const result = yield* settled(registry, target, isSettled);
+	return loaded(args, atom, result);
 });
+const results = /* @__PURE__ */ new WeakMap();
+/**
+* Returns the settled result `ensure` or `fetch` waited for.
+*
+* **When to use**
+*
+* Use in the loader that ran the verb, to branch on the result: redirect on
+* a tag, or build another atom's arguments from it. Components read the
+* handle with `useAtomResult`, which follows the registry.
+*
+* **Gotchas**
+*
+* Only the handle object the verb returned has it: a handle that crossed
+* the network, as loader data or a server component's prop, is a copy, and
+* this throws for it.
+*
+* **Example**
+*
+* ```ts
+* import { AsyncResult } from "effect/reactivity"
+* import { Loader } from "raf-effect-atom"
+*
+* const handle = await atoms.ensure(issue, id)
+* const error = AsyncResult.error(Loader.result(handle))
+* ```
+*
+* @stability unstable
+* @category getters
+* @since 0.1.0
+*/
+const result = (handle) => {
+	const settledResult = results.get(handle);
+	if (settledResult === void 0) throw new Error("raf-effect-atom: Loader.result got a handle that no ensure or fetch returned here. Only the code that ran the verb has its result: a handle that crossed the network is a copy. Read it with useAtomResult instead.");
+	return settledResult;
+};
 /**
 * Creates the Promise verbs over one registry.
 *
@@ -207,8 +267,8 @@ const fetch = Effect.fnUntraced(function* (atom) {
 * import { Loader, RequestRegistry } from "raf-effect-atom"
 *
 * const loader = Loader.make(RequestRegistry.make())
-* loader.prefetch(comments(1))
-* const result = await loader.ensure(issue(1))
+* const comments = loader.prefetch(commentPage, 1, 0)
+* const issueHandle = await loader.ensure(issue, 1)
 * ```
 *
 * @stability unstable
@@ -222,11 +282,15 @@ const make = (registry, options) => {
 		return leaseTTL === void 0 ? provided : Effect.provideService(provided, LeaseTTL, leaseTTL);
 	};
 	return {
-		ensure: (atom) => Effect.runPromise(provide(ensure(atom))),
-		fetch: (atom) => Effect.runPromise(provide(fetch(atom))),
-		prefetch: (atom) => {
-			Effect.runSync(provide(prefetch(atom)));
+		ensure: (source, ...args) => Effect.runPromise(provide(ensure(source, ...args))),
+		fetch: (source, ...args) => Effect.runPromise(provide(fetch(source, ...args))),
+		prefetch: (source, ...args) => {
+			const atom = atomOf(source, args);
+			afterSeed(registry, () => {
+				Effect.runSync(provide(start(atom)));
+			});
+			return make$1(args, atom);
 		}
 	};
 };
-export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch };
+export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch, result };

package/dist/Next.d.mts

@@ -1,10 +1,65 @@
-import { SettledResult } from "./Loader.mjs";
+import { ArgsOf, Handle, LoadedHandle, Source } from "./Handle.mjs";
+import { Loader } from "./Loader.mjs";
+import { Options } from "./RequestRegistry.mjs";
 import { HydrateAtoms } from "./NextClient.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
-import * as Atom from "effect/reactivity/Atom";
 import * as EffectHydration from "effect/reactivity/Hydration";
-import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+/**
+ * The loader verbs over the request registry of the server render in
+ * progress, with its registry and `dehydrate`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface RequestAtoms extends Loader {
+  /**
+   * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`,
+   * once its seed has settled.
+   */
+  readonly dehydrate: () => Promise<Array<EffectHydration.DehydratedAtom>>;
+  /** The request registry of the server render in progress. */
+  readonly getRegistry: () => AtomRegistry.AtomRegistry;
+}
+/**
+ * Creates the verbs, `getRegistry` and `dehydrate` over a request registry
+ * that `seed` prepares.
+ *
+ * **When to use**
+ *
+ * Use when the request's atoms need something from the request before they
+ * run, such as an RPC protocol that forwards the page request's cookie. Make
+ * them once, in a server-only module, and call the verbs on them instead of
+ * the ones `raf-effect-atom/next` exports.
+ *
+ * **Details**
+ *
+ * The seed runs on each request's registry when a server component first
+ * uses it. It can be async, as `headers()` is: `ensure` and `fetch` wait
+ * for it, `prefetch` returns its handle at once and starts the atom once the
+ * seed resolves, and `dehydrate` waits for both.
+ *
+ * **Example**
+ *
+ * ```ts
+ * // src/atoms.server.ts
+ * import "server-only"
+ * import { headers } from "next/headers"
+ * import { makeRequestAtoms } from "raf-effect-atom/next"
+ *
+ * export const atoms = makeRequestAtoms({
+ *   seed: async (registry) => {
+ *     registry.set(requestCookie, (await headers()).get("cookie") ?? undefined)
+ *   }
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const makeRequestAtoms: (options?: Options) => RequestAtoms;
 /**
  * Returns the request registry of the server render in progress.
  *
@@ -25,31 +80,32 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
  */
 export declare const getRegistry: () => AtomRegistry.AtomRegistry;
 /**
- * `Loader.prefetch` on the request's registry: starts an atom, to stream it.
+ * `Loader.prefetch` on the request's registry: starts a source's atom, to
+ * stream it, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => void;
+export declare const prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
 /**
- * `Loader.ensure` on the request's registry: starts an atom and returns its
- * settled result.
+ * `Loader.ensure` on the request's registry: starts a source's atom, waits
+ * for its result, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+export declare const ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
 /**
- * `Loader.fetch` on the request's registry: starts or refreshes an atom and
- * returns the new settled result.
+ * `Loader.fetch` on the request's registry: starts or refreshes a source's
+ * atom, waits for the new result, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
 /**
  * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
  *
@@ -58,9 +114,17 @@ export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>
  * Includes the atoms started so far, so call it after the server component's
  * verbs. Each `HydrateAtoms` hydrates what its own `dehydrate()` saw.
  *
+ * **Example**
+ *
+ * ```tsx
+ * <HydrateAtoms state={await dehydrate()}>
+ *   <Issue issue={handle} />
+ * </HydrateAtoms>
+ * ```
+ *
  * @stability unstable
  * @category dehydration
  * @since 0.1.0
  */
-export declare const dehydrate: () => Array<EffectHydration.DehydratedAtom>;
+export declare const dehydrate: () => Promise<Array<EffectHydration.DehydratedAtom>>;
 export { HydrateAtoms, RegistryProvider };

package/dist/Next.mjs

@@ -1,8 +1,47 @@
-import { dehydrate as dehydrate$1, ensure as ensure$1, fetch as fetch$1, getRegistry as getRegistry$1, prefetch as prefetch$1 } from "./internal/next.mjs";
+import { make } from "./internal/next.mjs";
 import { HydrateAtoms } from "./NextClient.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
 // src/Next.ts
 /**
+* Creates the verbs, `getRegistry` and `dehydrate` over a request registry
+* that `seed` prepares.
+*
+* **When to use**
+*
+* Use when the request's atoms need something from the request before they
+* run, such as an RPC protocol that forwards the page request's cookie. Make
+* them once, in a server-only module, and call the verbs on them instead of
+* the ones `raf-effect-atom/next` exports.
+*
+* **Details**
+*
+* The seed runs on each request's registry when a server component first
+* uses it. It can be async, as `headers()` is: `ensure` and `fetch` wait
+* for it, `prefetch` returns its handle at once and starts the atom once the
+* seed resolves, and `dehydrate` waits for both.
+*
+* **Example**
+*
+* ```ts
+* // src/atoms.server.ts
+* import "server-only"
+* import { headers } from "next/headers"
+* import { makeRequestAtoms } from "raf-effect-atom/next"
+*
+* export const atoms = makeRequestAtoms({
+*   seed: async (registry) => {
+*     registry.set(requestCookie, (await headers()).get("cookie") ?? undefined)
+*   }
+* })
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const makeRequestAtoms = make;
+const atoms = make();
+/**
 * Returns the request registry of the server render in progress.
 *
 * **Details**
@@ -20,33 +59,34 @@ import { RegistryProvider } from "./RegistryProvider.mjs";
 * @category registry
 * @since 0.1.0
 */
-const getRegistry = getRegistry$1;
+const getRegistry = atoms.getRegistry;
 /**
-* `Loader.prefetch` on the request's registry: starts an atom, to stream it.
+* `Loader.prefetch` on the request's registry: starts a source's atom, to
+* stream it, and returns its handle.
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const prefetch = prefetch$1;
+const prefetch = atoms.prefetch;
 /**
-* `Loader.ensure` on the request's registry: starts an atom and returns its
-* settled result.
+* `Loader.ensure` on the request's registry: starts a source's atom, waits
+* for its result, and returns its handle.
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const ensure = ensure$1;
+const ensure = atoms.ensure;
 /**
-* `Loader.fetch` on the request's registry: starts or refreshes an atom and
-* returns the new settled result.
+* `Loader.fetch` on the request's registry: starts or refreshes a source's
+* atom, waits for the new result, and returns its handle.
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const fetch = fetch$1;
+const fetch = atoms.fetch;
 /**
 * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
 *
@@ -55,9 +95,17 @@ const fetch = fetch$1;
 * Includes the atoms started so far, so call it after the server component's
 * verbs. Each `HydrateAtoms` hydrates what its own `dehydrate()` saw.
 *
+* **Example**
+*
+* ```tsx
+* <HydrateAtoms state={await dehydrate()}>
+*   <Issue issue={handle} />
+* </HydrateAtoms>
+* ```
+*
 * @stability unstable
 * @category dehydration
 * @since 0.1.0
 */
-const dehydrate = dehydrate$1;
-export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, prefetch };
+const dehydrate = atoms.dehydrate;
+export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, makeRequestAtoms, prefetch };