raf-effect-atom 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex / KATT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# raf-effect-atom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Render-as-you-fetch for [Effect Atom](https://github.com/Effect-TS/effect/tree/main/packages/atom/react). Route loaders start atoms before anything renders, the server streams their results into the browser, and the browser reads them without requesting them again. Typed failures survive the trip: a server-side `IssueNotFound` is an `IssueNotFound` in the browser.
+
+**[GitHub](https://github.com/KATT/raf-effect-atom)**
+
+> [!NOTE]
+> raf-effect-atom is early. The API can still change between minor releases.
+
+## Install
+
+```bash
+npm install raf-effect-atom effect @effect/atom-react react
+```
+
+`effect`, `@effect/atom-react` and `react` (19.2 or newer) are peer dependencies.
+
+## Usage
+
+A loader starts atoms with a verb per call. `prefetch` starts one and streams it, `ensure` waits for its first result, and `fetch` waits for a fresh one. Typed failures come back as results, so a loader can redirect on a tag:
+
+```ts
+// issue: (id: number) => an AtomRpc query with a serializationKey
+export async function loader(args: LoaderArgs) {
+	const id = Number(args.params.id);
+	args.context.atoms.prefetch(comments(id));
+	const result = await args.context.atoms.ensure(issue(id));
+	if (AsyncResult.isFailure(result)) {
+		// result.cause holds IssueNotFound | Unauthorized | RpcClientError
+	}
+}
+```
+
+A component reads the atom with `useAtomResult`, which waits for a streamed result instead of starting the atom again, and returns typed failures. It also reads an atom derived from one, such as the atom 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:
+
+```tsx
+import { useAtomResult } from "raf-effect-atom";
+
+function IssueTitle(props: { readonly id: number }) {
+	const result = useAtomResult(useIssueBoundary().wrap(issue(props.id)));
+	// Success<Issue, never>: its boundaries claim every failure
+	return <h1>{result.value.title}</h1>;
+}
+```
+
+Each framework has a subpath that gives every server request its own registry and sends it to the browser:
+
+- `raf-effect-atom/tanstack-router`, for TanStack Router and TanStack Start: `setupRouterAtoms({ router, registry })` in `getRouter`, with `Loader.make(registry)` on the router context.
+- `raf-effect-atom/next`, for the App Router: `prefetch`, `ensure` and `fetch` in server components, and `<HydrateAtoms state={dehydrate()}>` around the client components that read them.
+- `raf-effect-atom/react-router`, for Framework Mode: `atomsMiddleware(atomsContext)` as the root middleware, loaders that return `atoms.dehydrate()`, and `HydrationBoundary` in the route component.
+
+In development, `useAtomResult` reports a read that starts an atom nothing started, a request waterfall. `<WaterfallDetection mode="throw">` at the root makes it throw to the nearest error boundary. `useWaterfall(atom)` starts an atom whose input exists only in render, and marks it as a known waterfall.
+
+## For coding agents
+
+Start every atom in a loader or a server component, never in a component or `useEffect`, and put the state that picks data (pages, filters, open dialogs) in the URL so the loader can. Event handlers and `useWaterfall` are escape hatches for state that can't be in the URL. Read atoms with `useAtomResult`, not `useAtomValue` or `useAtomSuspense`. Keep `<WaterfallDetection mode="throw">` at the root and fix what it reports instead of turning it off. The full rules, with the reason for each: [For coding agents](https://raf-effect-atom.katt.dev/docs/coding-agents). The docs as markdown: [llms.txt](https://raf-effect-atom.katt.dev/llms.txt).
+
+## License
+
+MIT

package/dist/Hooks.d.mts

@@ -0,0 +1,68 @@
+import { SettledResult } from "./Loader.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+/**
+ * Reads an `AsyncResult` atom through React Suspense: a result streamed from
+ * the server, a hydrated one, or one a loader started.
+ *
+ * **When to use**
+ *
+ * Use for every atom a loader starts or the server renders, or for an atom
+ * derived from one with `initialValueTarget` pointing at it, such as an error
+ * boundary's wrapper.
+ *
+ * **Details**
+ *
+ * - A result the server was still loading when it dehydrated is awaited
+ *   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.
+ * - 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.
+ * - While a failed atom refreshes, such as after a boundary's `reset`, the
+ *   read suspends instead of returning the old failure again.
+ *
+ * **Gotchas**
+ *
+ * A read of an atom that nothing started starts it, and its request waits
+ * for the render: a request waterfall. In development, the read reports it
+ * as `WaterfallDetection` says, by default with a warning. Start the atom in
+ * a loader or a server component, with the state that picks it in the URL.
+ * For state that can't be in the URL, start it in the event handler that
+ * changes the state, or read it through `useWaterfall` when only the render
+ * knows its input.
+ *
+ * During server rendering, the registry must be a request registry (see
+ * `RequestRegistry.make`), or a module-level registry would share results
+ * between requests: in development, the hook throws without one.
+ *
+ * `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.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { AsyncResult } from "effect/reactivity"
+ * import { useAtomResult } from "raf-effect-atom"
+ *
+ * function IssueTitle(props: { readonly id: number }) {
+ *   const result = useAtomResult(issue(props.id))
+ *   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
+ * }
+ * ```
+ *
+ * @see {@link hydrated} for reading hydrated atoms with Atom's own hooks
+ *
+ * @stability unstable
+ * @category hooks
+ * @since 0.1.0
+ */
+export declare const useAtomResult: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => [E] extends [never] ? AsyncResult.Success<A, never> : SettledResult<A, E>;

package/dist/Hooks.mjs

@@ -0,0 +1,119 @@
+"use client";
+import { stream } from "./internal/pending.mjs";
+import { hydrated } from "./Hydration.mjs";
+import { isDevelopment } from "./internal/development.mjs";
+import { keyOf, release } from "./internal/leases.mjs";
+import { isRequestRegistry } from "./RequestRegistry.mjs";
+import { isServer } 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 Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import { RegistryContext, useAtomSuspense } from "@effect/atom-react";
+import * as React from "react";
+// src/Hooks.ts
+/**
+* The read hook for atoms started by loaders and streamed from the server.
+*
+* @stability unstable
+* @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 an `AsyncResult` atom through React Suspense: a result streamed from
+* the server, a hydrated one, or one a loader started.
+*
+* **When to use**
+*
+* Use for every atom a loader starts or the server renders, or for an atom
+* derived from one with `initialValueTarget` pointing at it, such as an error
+* boundary's wrapper.
+*
+* **Details**
+*
+* - A result the server was still loading when it dehydrated is awaited
+*   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.
+* - 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.
+* - While a failed atom refreshes, such as after a boundary's `reset`, the
+*   read suspends instead of returning the old failure again.
+*
+* **Gotchas**
+*
+* A read of an atom that nothing started starts it, and its request waits
+* for the render: a request waterfall. In development, the read reports it
+* as `WaterfallDetection` says, by default with a warning. Start the atom in
+* a loader or a server component, with the state that picks it in the URL.
+* For state that can't be in the URL, start it in the event handler that
+* changes the state, or read it through `useWaterfall` when only the render
+* knows its input.
+*
+* During server rendering, the registry must be a request registry (see
+* `RequestRegistry.make`), or a module-level registry would share results
+* between requests: in development, the hook throws without one.
+*
+* `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.
+*
+* **Example**
+*
+* ```tsx
+* import { AsyncResult } from "effect/reactivity"
+* import { useAtomResult } from "raf-effect-atom"
+*
+* function IssueTitle(props: { readonly id: number }) {
+*   const result = useAtomResult(issue(props.id))
+*   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
+* }
+* ```
+*
+* @see {@link hydrated} for reading hydrated atoms with Atom's own hooks
+*
+* @stability unstable
+* @category hooks
+* @since 0.1.0
+*/
+const useAtomResult = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	if (isServer() && !isRequestRegistry(registry) && Effect.runSync(isDevelopment)) throw new Error("raf-effect-atom: useAtomResult rendered on the server without a request registry, so results would be shared between requests. Provide RequestRegistry.make() through RegistryContext, as the framework integrations do.");
+	const target = sourceOf(atom);
+	const source = hydrated(target);
+	const read = target === atom ? hydrated(atom) : atom;
+	const key = keyOf(source);
+	const streamed = Predicate.isString(key) ? stream(registry, key) : void 0;
+	if (streamed !== void 0) React.use(streamed);
+	if (process.env.NODE_ENV !== "production") check(registry, source, React.use(ModeContext));
+	if (read !== source) registry.get(source);
+	const current = registry.get(read);
+	const result = useAtomSuspense(read, {
+		includeFailure: true,
+		suspendOnWaiting: AsyncResult.isFailure(current) && current.waiting
+	});
+	React.useEffect(() => {
+		release(registry, source);
+	}, [registry, source]);
+	if (AsyncResult.isFailure(result) && Option.isNone(Cause.findErrorOption(result.cause))) throw Cause.squash(result.cause);
+	return result;
+};
+export { useAtomResult };

package/dist/Hydration.d.mts

@@ -0,0 +1,93 @@
+import * as Atom from "effect/reactivity/Atom";
+import * as EffectHydration from "effect/reactivity/Hydration";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+declare namespace Hydration_d_exports {
+  export { dehydrate, hydrate, hydrated };
+}
+/**
+ * Returns a serializable atom that keeps its hydrated value on its first
+ * read, instead of running its effect again.
+ *
+ * **When to use**
+ *
+ * The loader verbs and `useAtomResult` already read through it. Use it when
+ * reading a hydrated atom with `@effect/atom-react`'s own hooks.
+ *
+ * **Details**
+ *
+ * The copy shares the atom's serialization key, so both read the same
+ * registry node. It sets `skipInitialRun` on the atom's `Serializable`
+ * metadata, and is memoized per atom, so every call returns the same copy.
+ * An atom that isn't serializable, or already skips its initial run, is
+ * returned as it is.
+ *
+ * **Gotchas**
+ *
+ * The copy keeps the hydrated value only for the first read: a refresh, or a
+ * change to a dependency, runs the effect as usual. An `Initial` value never
+ * skips the effect, which is why a result the server was still loading
+ * crosses as a promise that `useAtomResult` waits for.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { useAtomValue } from "@effect/atom-react"
+ * import { Hydration } from "raf-effect-atom"
+ *
+ * const result = useAtomValue(Hydration.hydrated(issue(1)))
+ * ```
+ *
+ * @see {@link Atom.serializable} for the metadata it copies
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const hydrated: <Self extends Atom.Atom<unknown>>(atom: Self) => Self;
+/**
+ * Encodes a request registry's serializable atoms for the browser.
+ *
+ * **Details**
+ *
+ * `Hydration.dehydrate` with `encodeInitialAs: "promise"`: a settled result
+ * crosses as its encoded value, and a result still loading crosses as a
+ * promise of its encoded value, which resolves when it settles. The
+ * framework's serializer carries the promises (TanStack Router's dehydrated
+ * state, React's server component props, React Router's Single Fetch).
+ *
+ * **Gotchas**
+ *
+ * Only atoms in the registry when it's called are included, so call it once
+ * the loaders have started theirs.
+ *
+ * @see {@link hydrate} for the browser side
+ *
+ * @stability unstable
+ * @category dehydration
+ * @since 0.1.0
+ */
+export declare const dehydrate: (registry: AtomRegistry.AtomRegistry) => Array<EffectHydration.DehydratedAtom>;
+/**
+ * Applies dehydrated state to the browser's registry.
+ *
+ * **When to use**
+ *
+ * Use outside React, such as in a router's `hydrate` hook, before the app
+ * renders. Inside React, use `HydrationBoundary`.
+ *
+ * **Details**
+ *
+ * Settled values go through `Hydration.hydrate`. A streamed result is held
+ * until its promise resolves, then hydrated; until then `useAtomResult`
+ * suspends on it instead of starting the atom, which would request it again.
+ * A streamed result that can't be decoded, or whose promise rejects, is
+ * dropped, and the atom runs in the browser.
+ *
+ * @see {@link dehydrate} for the server side
+ *
+ * @stability unstable
+ * @category hydration
+ * @since 0.1.0
+ */
+export declare const hydrate: (registry: AtomRegistry.AtomRegistry, state: Iterable<EffectHydration.DehydratedAtom>) => void;
+export { Hydration_d_exports };

package/dist/Hydration.mjs

@@ -0,0 +1,134 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { split } from "./internal/pending.mjs";
+import { remember } from "./internal/sources.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as EffectHydration from "effect/reactivity/Hydration";
+// src/Hydration.ts
+/**
+* Streams a server registry into the browser's, typed failures intact, and
+* hydrates it without requesting anything again.
+*
+* `dehydrate` encodes the request registry's serializable atoms. Settled
+* results cross as values; results still loading cross as promises that
+* resolve when they settle, carried by the framework's own streaming.
+* `hydrate` applies settled values at once and holds each streamed result
+* until its promise resolves, so `useAtomResult` waits for it instead of
+* starting the atom. `hydrated` keeps a hydrated value on the atom's first
+* read instead of running its effect again.
+*
+* Typed failures survive because a serializable `AsyncResult` atom, such as
+* an `AtomRpc` query with a `serializationKey`, encodes its `Cause` with the
+* procedure's error Schemas: a server-side `IssueNotFound` decodes as an
+* `IssueNotFound` in the browser.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+var Hydration_exports = /* @__PURE__ */ __exportAll({
+	dehydrate: () => dehydrate,
+	hydrate: () => hydrate,
+	hydrated: () => hydrated
+});
+const copies = /* @__PURE__ */ new WeakMap();
+/**
+* Returns a serializable atom that keeps its hydrated value on its first
+* read, instead of running its effect again.
+*
+* **When to use**
+*
+* The loader verbs and `useAtomResult` already read through it. Use it when
+* reading a hydrated atom with `@effect/atom-react`'s own hooks.
+*
+* **Details**
+*
+* The copy shares the atom's serialization key, so both read the same
+* registry node. It sets `skipInitialRun` on the atom's `Serializable`
+* metadata, and is memoized per atom, so every call returns the same copy.
+* An atom that isn't serializable, or already skips its initial run, is
+* returned as it is.
+*
+* **Gotchas**
+*
+* The copy keeps the hydrated value only for the first read: a refresh, or a
+* change to a dependency, runs the effect as usual. An `Initial` value never
+* skips the effect, which is why a result the server was still loading
+* crosses as a promise that `useAtomResult` waits for.
+*
+* **Example**
+*
+* ```ts
+* import { useAtomValue } from "@effect/atom-react"
+* import { Hydration } from "raf-effect-atom"
+*
+* const result = useAtomValue(Hydration.hydrated(issue(1)))
+* ```
+*
+* @see {@link Atom.serializable} for the metadata it copies
+*
+* @stability unstable
+* @category combinators
+* @since 0.1.0
+*/
+const hydrated = (atom) => {
+	if (!Atom.isSerializable(atom) || atom[Atom.SerializableTypeId].skipInitialRun === true) return atom;
+	const cached = copies.get(atom);
+	if (cached !== void 0) return cached;
+	const copy = Object.assign(Object.create(Object.getPrototypeOf(atom)), {
+		...atom,
+		[Atom.SerializableTypeId]: {
+			...atom[Atom.SerializableTypeId],
+			skipInitialRun: true
+		}
+	});
+	copies.set(atom, copy);
+	return copy;
+};
+/**
+* Encodes a request registry's serializable atoms for the browser.
+*
+* **Details**
+*
+* `Hydration.dehydrate` with `encodeInitialAs: "promise"`: a settled result
+* crosses as its encoded value, and a result still loading crosses as a
+* promise of its encoded value, which resolves when it settles. The
+* framework's serializer carries the promises (TanStack Router's dehydrated
+* state, React's server component props, React Router's Single Fetch).
+*
+* **Gotchas**
+*
+* Only atoms in the registry when it's called are included, so call it once
+* the loaders have started theirs.
+*
+* @see {@link hydrate} for the browser side
+*
+* @stability unstable
+* @category dehydration
+* @since 0.1.0
+*/
+const dehydrate = (registry) => remember(EffectHydration.dehydrate(registry, { encodeInitialAs: "promise" }), registry);
+/**
+* Applies dehydrated state to the browser's registry.
+*
+* **When to use**
+*
+* Use outside React, such as in a router's `hydrate` hook, before the app
+* renders. Inside React, use `HydrationBoundary`.
+*
+* **Details**
+*
+* Settled values go through `Hydration.hydrate`. A streamed result is held
+* until its promise resolves, then hydrated; until then `useAtomResult`
+* suspends on it instead of starting the atom, which would request it again.
+* A streamed result that can't be decoded, or whose promise rejects, is
+* dropped, and the atom runs in the browser.
+*
+* @see {@link dehydrate} for the server side
+*
+* @stability unstable
+* @category hydration
+* @since 0.1.0
+*/
+const hydrate = (registry, state) => {
+	EffectHydration.hydrate(registry, split(registry, state));
+};
+export { Hydration_exports, dehydrate, hydrate, hydrated };

package/dist/Loader.d.mts

@@ -0,0 +1,157 @@
+import * as Atom from "effect/reactivity/Atom";
+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 };
+}
+/**
+ * A settled `AsyncResult`: what `ensure` and `fetch` return.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type SettledResult<A, E> = AsyncResult.Failure<A, E> | AsyncResult.Success<A, E>;
+/**
+ * How long a loader's lease keeps an atom mounted when no component takes it
+ * over. Default 30 seconds.
+ *
+ * **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.
+ *
+ * @stability unstable
+ * @category references
+ * @since 0.1.0
+ */
+export declare const LeaseTTL: Context.Reference<Duration.Duration>;
+/**
+ * Starts an atom without waiting for it.
+ *
+ * **When to use**
+ *
+ * Use for data the route needs but its loader doesn't: it streams in while
+ * the route renders.
+ *
+ * **Details**
+ *
+ * Starts the atom if it isn't in the registry, and leaves it alone if it is.
+ * Takes a lease either way.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Loader } from "raf-effect-atom"
+ *
+ * const program = Loader.prefetch(comments(1))
+ * ```
+ *
+ * @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>;
+/**
+ * Starts an atom and returns its settled result, waiting only while it has
+ * none.
+ *
+ * **When to use**
+ *
+ * Use when the loader needs the result, such as to redirect on a tag, or
+ * when the route shouldn't render without it.
+ *
+ * **Details**
+ *
+ * An atom with a result returns it 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.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { AsyncResult } from "effect/reactivity"
+ * import { Loader } from "raf-effect-atom"
+ *
+ * const program = Effect.gen(function* () {
+ *   const result = yield* Loader.ensure(issue(1))
+ *   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @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>;
+/**
+ * Starts an atom, or refreshes it if it has a result, and returns the new
+ * settled result.
+ *
+ * **When to use**
+ *
+ * Use when the loader must not see a result from before it ran, such as
+ * after a mutation.
+ *
+ * **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.
+ *
+ * @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>;
+/**
+ * The loader verbs as Promises over one registry, as the framework
+ * integrations put them on the router context.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+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>>;
+  /** {@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;
+}
+/**
+ * Creates the Promise verbs over one registry.
+ *
+ * **When to use**
+ *
+ * Use in a framework integration, in loaders that are async functions, or
+ * in an event handler that starts an atom before the state change that
+ * renders its reader, for state that can't be in the URL, such as a
+ * search-as-you-type query. In Effect code, use
+ * the verbs directly with the `AtomRegistry` provided.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Loader, RequestRegistry } from "raf-effect-atom"
+ *
+ * const loader = Loader.make(RequestRegistry.make())
+ * loader.prefetch(comments(1))
+ * const result = await loader.ensure(issue(1))
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (registry: AtomRegistry.AtomRegistry, options?: {
+  readonly leaseTTL?: Duration.Input | undefined;
+}) => Loader;
+export { Loader_d_exports };