Atoms
Look up the atom layer of @ensforge/react/atoms that the hooks are built on, for reading ENS data outside of React components.
Exports of @ensforge/react/atoms. See Atoms.
Exports
ensAtom
Unstable
The atom of one read: cached per client (chain, account and indexer), action and options, refreshed when a write touches a name or address in its options, and serializable for server rendering. Each freshness gets its own atom over the shared read.
function ensAtom<action extends Action>(client: Ensforge.Client, action: action, options: ActionOptions<action>, freshness: Freshness = {}): ReadAtom<ActionValue<action>, ActionError<action>>Use to compose ENS reads into your own atoms, or to read them outside React hooks. Hooks such
as useRead use the same atoms.
import { Actions } from "@ensforge/sdk"
import { ensAtom } from "@ensforge/react/atoms"
import { Atom } from "effect/reactivity"
const profile = Atom.make((get) => ({
address: get(ensAtom(ens, Actions.record.getAddress, { name: "nick.eth" })),
avatar: get(ensAtom(ens, Actions.record.getAvatar, { name: "nick.eth" })),
}))ensPagesAtom
Unstable
The paginated atom of an indexer list, such as indexer.getSubnames. Pages accumulate as
they load; a write touching the list's name or account starts it over.
function ensPagesAtom<action extends PageAction>(client: Ensforge.Client, action: action, options: Omit<ActionOptions<action>, "cursor">): PagesAtom<ActionValue<action>, ActionError<action>>import { Actions } from "@ensforge/sdk"
import { ensPagesAtom } from "@ensforge/react/atoms"
const subnames = ensPagesAtom(ens, Actions.indexer.getSubnames, { name: "ens.eth" })
registry.set(subnames, undefined) // load the next pageensWriteAtom
Unstable
Atoms for one write action. Each call makes new atoms, so every form or button has its own state; hooks keep one per component.
function ensWriteAtom<action extends Action>(client: Ensforge.Client, action: action): WriteAtom<ActionOptions<action>, ActionValue<action>, ActionError<action>>runandstepsshow the latest write started; mountrunwhile writing through it.- Writes never interrupt each other, and resetting interrupts none: a sent transaction cannot
be taken back. Each
sendstill ends with its own write's result. - Plan events (
waiting,submitted,confirmed,failed) collect insteps. - After a write, reads of the names and accounts it touched refresh: chain reads once its
transactions are mined, indexer reads once the indexer has caught up. A write that fails
after a step was confirmed refreshes them too. Signatures (
primaryName.signClaim) send no transaction and refresh nothing.
import { Actions } from "@ensforge/sdk"
import { ensWriteAtom } from "@ensforge/react/atoms"
const setRecords = ensWriteAtom(ens, Actions.record.set)
registry.mount(setRecords.run)
registry.set(setRecords.run, { name: "alice.eth", texts: { url: "https://alice.xyz" } })invalidate
Unstable
Refetches every cached read of the given names and accounts, chain and indexer reads alike.
function invalidate(registry: AtomRegistry.AtomRegistry, client: Ensforge.Client, subjects: { readonly names?: readonly string[]; readonly addresses?: readonly string[] }): voidUse after changes ensforge did not make, such as a transaction sent by another app. Writes made through ensforge refresh their reads on their own.
import { invalidate } from "@ensforge/react/atoms"
invalidate(registry, ens, { names: ["alice.eth"] })optionsKey
Unstable
A stable string for an action's options: keys sorted, undefined, callbacks and signal
dropped, the top-level name, names and parent normalized, top-level addresses lowercased
and bigints written as 123n. Nested fields are data (a text record called name), kept as
given.
function optionsKey(options: unknown): stringreadKey
Unstable
The key a read is cached, hydrated and invalidated under:
ensforge:<chainId>:<account>:<indexer>:<path>:<options>, with the client's account
(lowercase) and indexer key (Indexer.key) empty when it has none. It names the client by what changes a
read's answer, not by object, so it is the same on the server and in the browser.
function readKey(client: Ensforge.Client, action: Action, options: unknown): stringAction
Any ensforge action from @ensforge/sdk or @ensforge/sdk/effect, or one of a write's
.prepare, .simulate and .estimateGas: a function of a client and options, named by its
path.
type Action = ((client: Ensforge.Client, options: never) => unknown) & { readonly path: string; };| Field | Type | Description |
|---|---|---|
path | string |
ActionError
Error an action fails with: the Effect action's error channel, or any ensforge error for Promise actions.
type ActionError<action extends Action> = ReturnType<action> extends Effect.Effect<unknown, infer error, unknown> ? error : Errors.AnyError;ActionOptions
Options an action takes.
type ActionOptions<action extends Action> = Parameters<action>[1];ActionValue
Value an action resolves with.
type ActionValue<action extends Action> = ReturnType<action> extends Promise<infer value> ? value : ReturnType<action> extends Effect.Effect<infer value, unknown, unknown> ? value : never;Freshness
How long a read stays fresh and cached. Each hook's settings apply to it alone; hooks with other settings still share the read's value and requests.
type Freshness| Field | Type | Description |
|---|---|---|
staleTime (optional) | Duration.Input | After this long, the next mount or window focus refetches in the background while the cached value is shown (stale-while-revalidate). Duration.infinity never does. Without it, a value hydrated from the server is stale after 30 seconds; a failed read is always stale, so a remount retries it. |
idleTTL (optional) | Duration.Input | "forever" | How long an unused read stays cached; "forever" or Duration.infinity keeps it. With hooks of several settings, the longest applies. |
refetchInterval (optional) | Duration.Input | Refetch on this interval while the read is in use, in the browser only. |
refreshOnWindowFocus (optional) | boolean | Refetch when the window regains focus (respecting staleTime when set). |
PageAction
An indexer action that returns pages and takes a cursor, such as indexer.getSubnames.
type PageAction = Action & (( client: never, options: never, ) => | Promise<{ readonly items: readonly unknown[]; readonly cursor: string | null }> | Effect.Effect< { readonly items: readonly unknown[]; readonly cursor: string | null }, unknown >);| Field | Type | Description |
|---|---|---|
path | string |
PagesAtom
Unstable
Pages of an indexer list as an atom: its value holds every page loaded so far, and writing to it loads the next one.
type PagesAtom<page, error> = Atom.Writable<Atom.PullResult<page, error>, void>;ReadAtom
Unstable
A read atom: an Effect Atom holding the read's AsyncResult.
type ReadAtom<value, error> = Atom.Atom<AsyncResult.AsyncResult<value, error>>;WriteAtom
Unstable
A write as atoms: run holds the latest write's result and sends one when set; steps holds
that write's plan events; send sends one and ends with its own result.
type WriteAtom<options, value, error>| Field | Type | Description |
|---|---|---|
run | Atom.Writable<AsyncResult.AsyncResult<value, error>, options | Atom.Reset> | The latest write's result. Setting options sends a write; Atom.Reset clears the result. |
steps | Atom.Writable<readonly Plan.Event[]> | |
send | (options: options) => Effect.Effect<value, error, AtomRegistry.AtomRegistry> | Sends a write and ends with its own result, even when later writes start while it runs. run and steps show it until a later one starts. |
Was this page helpful?