;
}
```
The loader verbs as Promises over one registry, as the framework
integrations put them on the router context.
### `Loader.MakeOptions`
interfacemodelssince 0.2.2Source
```ts
interface MakeOptions {
/** How long a lease lasts in the browser. See {@link LeaseTTL}. */
readonly leaseTTL?: Duration.Input | undefined;
/**
* The request's or the navigation's abort signal. Aborting it interrupts
* the `ensure`, `fetch` and `run` calls still waiting, which reject with
* its reason. The atoms they started keep loading.
*/
readonly signal?: AbortSignal | undefined;
}
```
Options for `make`.
### `Loader.make`
constconstructorssince 0.1.0Source
```ts
const make: (
registry: AtomRegistry.AtomRegistry,
options?: MakeOptions,
) => Loader;
```
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 a choice a click or a submit makes that doesn't
belong in the URL. In Effect code, use the verbs directly, and run
the Effect on the registry with `run`.
**Details**
With a `signal`, an aborted request or navigation stops waiting: `ensure`,
`fetch` and `run` reject with the signal's reason, and the atoms they
started keep loading. The React Router and Next.js integrations pass the
request's.
**Example**
```ts
import { Loader, RequestRegistry } from "raf-effect-atom"
const loader = Loader.make(RequestRegistry.make(), { signal: request.signal })
const comments = loader.prefetch(commentPage, 1, 0)
const issueHandle = await loader.ensure(issue, 1)
```
## `RequestRegistry`
namespaceSource
A registry per server request.
`@effect/atom-react`'s default `RegistryContext` is one registry for the
whole module, which on a server would share one user's results with every
other request. Each framework integration makes a request registry with
`make`, provides it through `RegistryContext`, and dehydrates it into the
response.
```ts
import { RequestRegistry } from "raf-effect-atom";
```
### `RequestRegistry.Seed`
typemodelssince 0.2.0Source
```ts
type Seed = Seeds.Seed;
```
Prepares a request registry before the loader verbs start atoms in it,
such as by setting an atom to the request's cookie.
### `RequestRegistry.InitialValues`
typemodelssince 0.2.4Source
```ts
type InitialValues = Iterable<
readonly [Atom.Atom, any, Atom.InitialValueOptions?]
>;
```
Atoms paired with the values a registry starts with, as
`AtomRegistry.make`'s `initialValues` takes them: build each pair with
`Atom.initialValue`.
### `RequestRegistry.Options`
interfacemodelssince 0.2.0Source
```ts
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`
* returns its handle at once and starts the atom once it resolves.
*/
readonly seed?: Seed | undefined;
}
```
Options for `make`.
### `RequestRegistry.make`
constconstructorssince 0.1.0Source
```ts
const make: (options?: Options) => AtomRegistry.AtomRegistry;
```
Creates the registry for one server request.
**Details**
- It's an ordinary `AtomRegistry`, marked as a request registry. On a
request registry, `ensure` waits like `fetch` does, nothing revalidates
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()`. It runs after `initialValues` are set.
**Gotchas**
With an async seed, a `prefetch` before it settles starts its atom later,
so `Hydration.dehydrate` would miss it: wait for `settled` first, as the
framework integrations do.
**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)
})
```
### `RequestRegistry.settled`
constgetterssince 0.2.0Source
```ts
const settled: (registry: AtomRegistry.AtomRegistry) => Promise;
```
Waits until a request registry's seed has settled and every atom a verb
started while it ran has started.
**When to use**
Use before `Hydration.dehydrate` on a registry with an async seed, outside
the framework integrations, which call it for you.
**Details**
Resolves at once for a registry without a seed, or whose seed was
synchronous. Rejects with the seed's error.
### `RequestRegistry.layer`
constlayerssince 0.1.0Source
```ts
const layer: Layer.Layer;
```
A layer that provides a request registry as the `AtomRegistry`, disposed
when the layer's scope closes.
**When to use**
Use when the request is handled in Effect, around the loaders' verbs and
`dehydrate`.
**See also**
- [`make`](https://raf-effect-atom.katt.dev/docs/api-raf-effect-atom.md#RequestRegistry.make) for the registry it provides
### `RequestRegistry.isRequestRegistry`
constguardssince 0.1.0Source
```ts
const isRequestRegistry: (
registry: AtomRegistry.AtomRegistry,
) => boolean;
```
Returns whether a registry was made by `make`, for one server request.
## Use atom result
The read hooks for atoms started by loaders and streamed from the server.
### `useAtomResult`
consthookssince 0.1.0Source
```ts
const useAtomResult: (
source: S,
handle: NoInfer>>,
) => [ErrorOf] extends [never]
? AsyncResult.Success, never>
: SettledResult, ErrorOf>;
```
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.
**When to use**
Use in the component a loader, a server component or `useWaterfall` gave
the handle to. The source can be the one the verb started, or one derived
from it whose atoms point at its atoms with `initialValueTarget`. To send
some failures to an error boundary, pass the result to the boundary's hook,
such as `useIssueBoundary(useAtomResult(issue, handle))`.
**Details**
- The atom is `source(...handle.args)`, or `source` itself for an atom.
In development, the read throws when the atom it hydrates has another
serialization key than the handle's: the handle came from another
source.
- A handle from `ensure` or `fetch` renders without suspending, unless
the registry dropped the result since; one from `prefetch` or
`useWaterfall` suspends until the result settles. The registry is the
source of truth either way: the read follows refreshes and mutations.
- 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 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.
- The settled result is returned, typed failures included. A defect is
thrown to the error boundaries above. With no typed failures, 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, such as one whose loader result the
registry dropped, 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,
and pass its handle down. For state that can't be in the URL, start it in
the event handler that changes the state, or make its handle with
`useWaterfall` when only the render knows its input.
Two sources with the same arguments and success type take each other's
handles as far as the types go; the development check catches it.
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.
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
`initialValueTarget` to its source itself, or it requests the source again
after hydration.
**Example**
```tsx
import { AsyncResult } from "effect/reactivity"
import { type Handle, useAtomResult } from "raf-effect-atom"
function IssueTitle(props: { readonly issue: Handle }) {
const result = useAtomResult(issue, props.issue)
return AsyncResult.isSuccess(result) ? {result.value.title}
: null
}
```
**See also**
- [`hydrated`](https://raf-effect-atom.katt.dev/docs/api-raf-effect-atom.md#Hydration.hydrated) for reading hydrated atoms with Atom's own hooks
### `useHandleValue`
consthookssince 0.3.1Source
```ts
const useHandleValue: (
source: S,
handle: NoInfer>>,
) => AsyncResult.AsyncResult, ErrorOf>;
```
Reads a handle without React Suspense, through the source that made it,
and returns the atom's current result as it is.
**When to use**
Use where a component renders every state of the read itself: its loading
state, a failure that stays on the page while the atom refreshes, or a
defect. Otherwise prefer `useAtomResult`, which suspends until the result
settles and sends defects to the error boundaries above.
**Details**
- It reads the atom as `useAtomResult` does: through `hydrated`, through
the serializable atom a derived source points at, and with the same
development checks on the handle's key and on request waterfalls.
- It returns `Initial` while the atom loads, and while a result the server
was still loading streams in. It doesn't read the atom until the stream
settles, so the browser doesn't request it a second time.
- 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. 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.
**Gotchas**
The server renders what the read returns, `Initial` for a result still
loading, and the browser's first render has to match it: render the same
loading state for every `Initial`.
During server rendering, the registry must be a request registry (see
`RequestRegistry.make`): in development, the hook throws without one.
**Example**
```tsx
import { AsyncResult } from "effect/reactivity"
import { type Handle, useHandleValue } from "raf-effect-atom"
function IssueTitle(props: { readonly issue: Handle }) {
const result = useHandleValue(issue, props.issue)
return AsyncResult.isSuccess(result) ? {result.value.title}
: Loading…
}
```
**See also**
- [`useAtomResult`](https://raf-effect-atom.katt.dev/docs/api-raf-effect-atom.md#useAtomResult) for a read that suspends until the result settles
## Hydration boundary
Applies a server registry's dehydrated state to the nearest
`RegistryContext`, while rendering.
### `HydrationBoundaryProps`
typemodelssince 0.1.0Source
```ts
type HydrationBoundaryProps =
| {
readonly children?: React.ReactNode | undefined;
/**
* The request registry of the server component render, such as
* `raf-effect-atom/rsc`'s `getRegistry()`. Server components only.
*/
readonly registry: AtomRegistry.AtomRegistry;
readonly state?: never;
}
| {
readonly children?: React.ReactNode | undefined;
readonly registry?: never;
/** The state `Hydration.dehydrate` returned on the server. */
readonly state?: Iterable | undefined;
};
```
Props for `HydrationBoundary`: the request's `registry` in a server
component, or the `state` it dehydrated anywhere else.
### `HydrationBoundary`
constcomponentssince 0.1.0Source
```ts
const HydrationBoundary: (
props: HydrationBoundaryProps,
) => React.ReactNode;
```
Hydrates the state a server registry dehydrated, streamed results
included.
**When to use**
Use where the server's state reaches the React tree through rendering
rather than a router: a server component's registry, or a React Router
loader's data. A router that hydrates before rendering calls
`Hydration.hydrate` instead.
**Details**
In a server component, pass the request's `registry`. Server components
get their own build of `HydrationBoundary` through the package's
`react-server` export condition: it waits for the registry's seed,
dehydrates it, and sends the state with the server component's payload,
so results still loading stream in as they settle.
Anywhere else, pass the `state` a loader dehydrated. Settled values go to
`@effect/atom-react`'s `HydrationBoundary`, which hydrates new atoms
during render and existing ones after commit. Each streamed result is
held until it arrives, so `useAtomResult` waits for it instead of
requesting it again.
During server rendering, when `state` is the array `dehydrate` returned,
as React Router passes a loader's data to the server render, the children
read the registry it came from instead of a copy. The loaders' atoms are
there, so an `effect-atom-boundary` boundary sees their failures before
its children read them and renders its handler on the server.
**Gotchas**
`registry` works only in server components: in a client component it
throws, since a registry can't cross to the browser. In development, it
throws during server rendering when the registry isn't a request
registry, such as `@effect/atom-react`'s default one, which every request
shares: one request's state would reach the others.
**Example**
```tsx
import { HydrationBoundary } from "raf-effect-atom"
import { ensure, getRegistry } from "raf-effect-atom/rsc"
// A server component
export default async function IssueRoute(props: { params: Promise<{ id: string }> }) {
const handle = await ensure(issue, Number((await props.params).id))
return (
)
}
// A React Router route component
```
## Registry provider
The registry provider for apps that render the server's state through
`HydrationBoundary`, such as React Server Components and React Router.
### `RegistryProvider`
constcomponentssince 0.1.0Source
```ts
const RegistryProvider: (props: {
readonly children?: React.ReactNode | undefined;
readonly defaultIdleTTL?: number | undefined;
}) => React.ReactNode;
```
Provides the app's registry: a request registry while the framework
renders the app on the server, and one registry for the page's lifetime
in the browser.
**When to use**
Put it in the root layout, around `children`, in place of
`@effect/atom-react`'s `RegistryProvider`, which would share one registry
between requests' server renders.
**Details**
`defaultIdleTTL` is how many milliseconds the browser's registry keeps an
atom no component reads, 400 by default, as `@effect/atom-react`'s default
registry does. An atom's own `Atom.setIdleTTL` or `Atom.keepAlive` wins.
It's read once, when the registry is made. The server's request registry
lives for one request, so it has none.
In the browser, React Router's `clientAtomsMiddleware` gives client
loaders the registry of the mounted provider.
**Example**
```tsx
import { RegistryProvider } from "raf-effect-atom"
export default function RootLayout(props: { children: React.ReactNode }) {
return (
{props.children}
)
}
```
## Waterfalls
Request waterfalls: the escape hatch for atoms only a render can start,
and the development check that finds the others.
### `WaterfallMode`
typemodelssince 0.1.0Source
```ts
type WaterfallMode = Waterfalls.Mode;
```
What `useAtomResult` does in development when a read starts an atom that
no loader, server component, event handler or `useWaterfall` started.
- `"warn"`: `console.warn` once per atom, naming it. The default.
- `"throw"`: throw to the nearest error boundary, so the page can't be
used until the atom starts before render.
- `"off"`: don't check.
### `WaterfallDetection`
constcomponentssince 0.1.0Source
```ts
const WaterfallDetection: (props: {
readonly children?: React.ReactNode | undefined;
readonly mode: WaterfallMode;
}) => React.ReactNode;
```
Sets how `useAtomResult` reports request waterfalls in the tree below.
**When to use**
Put it in the root layout, around the app. `"throw"` turns every atom a
component starts on its own into an error in development, which a person
or a coding agent can't miss.
**Details**
Production builds don't check: the check sits behind
`process.env.NODE_ENV !== "production"`, which bundlers replace at build
time, so it's left out of the bundle, and this component renders only its
children.
**Example**
```tsx
import { WaterfallDetection } from "raf-effect-atom"
function App(props: { readonly children: React.ReactNode }) {
return {props.children}
}
```
### `useWaterfall`
consthookssince 0.1.0Source
```ts
const useWaterfall: (
source: S,
...args: ArgsOf
) => Handle;
```
Starts a source's atom during render and returns its handle, for an input
only a render knows, such as an id read from another atom's result.
**When to use**
As an escape hatch, when no loader, server component or event handler can
start the atom: each call is a request waterfall, a round trip after the
render that found the input. Prefer putting the state that picks the data
in the URL, where a loader reads it, or a procedure that resolves the input
on the server. Searching a codebase for `useWaterfall` lists its
waterfalls.
**Details**
- Starts the atom like `Loader.prefetch`, with a lease that
`useAtomResult` takes over when the component mounts, and only if
nothing started it yet: re-renders start nothing.
- A result the server is still streaming is awaited by `useAtomResult`,
not started again.
- `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`.
- A derived source starts the serializable atom its `initialValueTarget`
chain points at, as `Loader.prefetch` does.
**Example**
```tsx
import { useAtomResult, useWaterfall } from "raf-effect-atom"
function Author(props: { readonly userId: UserId }) {
const result = useAtomResult(user, useWaterfall(user, props.userId))
// ...
}
```
**See also**
- [`WaterfallDetection`](https://raf-effect-atom.katt.dev/docs/api-raf-effect-atom.md#WaterfallDetection) for the development check it opts out of