The Effect API
Run every ensforge action as an Effect with typed errors, a client service and streams, when your app already uses Effect.
The Effect API is optional. Everything in ensforge works with Promises. Use @ensforge/sdk/effect
when your program is already written with Effect: you get typed errors in
the error channel, interruption, services and streams.
Prerequisites
effectversion 4 (^4.1.4) installed. It is a peer dependency of@ensforge/sdk.- Familiarity with
Effect.gen.
Same actions, returned as Effects
@ensforge/sdk/effect exports the same action tree as the root entry. Each action takes a client
first and returns an Effect whose error channel is the action's documented error union.
Example (Reading an Address in an Effect Program)
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient });
const program = Actions.record.getAddress(ens, { name: "nick.eth" });
const address = await Effect.runPromise(program);- The Effect client has no
ens.record.*methods. Pass the client toActions.<domain>.<action>. - Reads accept a bare viem client too, as in the Promise API.
Provide the client as a service
Ensforge.Ensforge is an Effect Context.Service, and Ensforge.layer(options) builds a Layer
for it. The layer fails with ConfigError when the options are invalid, such as an unknown chain.
Example (Using the Service)
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const program = Effect.gen(function* () {
const ens = yield* Ensforge.Ensforge;
return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" });
});
await Effect.runPromise(program.pipe(Effect.provide(Ensforge.layer({ publicClient }))));The service key is @ensforge/sdk/Ensforge. In tests, provide a different client with
Layer.succeed(Ensforge.Ensforge, client).
Handle typed errors
Errors are the same instances Promise users catch, so _tag matches the class name. Use
Effect.catchTag to handle one class and let the others stay in the error type.
Example (Recovering from a Missing Record)
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient });
const program = Actions.record
.getAddress(ens, { name: "nobody-here.eth", strict: true })
.pipe(Effect.catchTag("NotFoundError", () => Effect.succeed(null)));After catchTag, NotFoundError is gone from the error type. See
Handle errors for the codes.
Example (Retrying Only What Is Retryable)
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient });
const program = Actions.record
.getAddress(ens, { name: "nick.eth" })
.pipe(Effect.retry({ times: 3, while: (error) => error.retryable }));Write, preview and resume
Writes keep their methods as Effects: Actions.record.set, Actions.record.set.prepare,
.simulate and .estimateGas, and the …Sync forms. Plans are plain data, so they are the same
values as in the Promise API.
Example (Preparing, Simulating and Sending)
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { Effect } from "effect";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const ens = Ensforge.create({
publicClient,
account: "0x225f137127d9067788314bc7fcc1f36746a3c3B5",
});
const options = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } };
const program = Effect.gen(function* () {
const simulation = yield* Actions.record.set.simulate(ens, options);
if (!simulation.ok) return simulation;
const plan = yield* Actions.record.set.prepare(ens, options);
return yield* Actions.plan.send(ens, { plan });
});See Preview before sending and Continue after a failure.
Batch reads
Actions.batch is an Effect too. Build the requests with the Promise entry's .request helpers.
Example (Batching Reads in an Effect Program)
import { Actions as Requests } from "@ensforge/sdk";
import { Actions, Ensforge } from "@ensforge/sdk/effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient });
const program = Actions.batch(ens, {
requests: [Requests.name.get.request({ name: "nick.eth" })],
});Validate names with a schema
Name.Normalized is a branded Schema for names that are already normalised (ENSIP-15). It
exists only in the Effect entry.
Example (Decoding a Normalised Name)
import { Name } from "@ensforge/sdk/effect";
import { Schema } from "effect";
const name = Schema.decodeUnknownSync(Name.Normalized)("nick.eth");Stream indexer pages
Indexer.paginate turns a list into a Stream of pages, following cursor until the last page.
Indexer.define is the Effect form of defineIndexer. See
Custom indexers and Load more results.
Example (Streaming Three Pages of Subnames)
import { Actions, Ensforge, Indexer } from "@ensforge/sdk/effect";
import { bigname } from "@ensforge/sdk/indexer";
import { Effect, Stream } from "effect";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient, indexer: bigname() });
const subnames = Indexer.paginate((cursor) =>
Actions.indexer.getSubnames(ens, { name: "ens.eth", namespace: "ens", limit: 200, cursor }),
).pipe(Stream.take(3));
const pages = await Effect.runPromise(Stream.runCollect(subnames));Check the result
Run the program with Effect.runPromise. A failure rejects with the error instance, with its
code and context.
Troubleshooting
ens.record is undefined
The Effect client does not carry action methods. Call Actions.record.<action>(ens, options).
The error type is a long union
Each action declares only the classes it can fail with, plus the common ones. Narrow with
Effect.catchTag, or map to your own error at a boundary.
Was this page helpful?