Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

batch

Runs several reads together, in as few round trips as possible. Parameters, return value, errors and examples for batch in @ensforge/sdk.

Readstable
Since v1.0.0View source

Runs several reads together, in as few round trips as possible.

When to use

Use to load a page's data at once: profiles, names, prices, permissions.

Details

  • requests is a list (results come back as a tuple) or a record (results keep its keys).
  • Contract reads coalesce into Multicall3 calls, per block; resolution reads (records, primary names) keep their Universal Resolver call, so CCIP-Read and off-chain names work.
  • With allowFailure (default) each result is { status: "success", result } or { status: "failure", error }; with allowFailure: false the first failure rejects.
  • Only reads with .request can be batched; writes combine with Plan.merge.

Signature

function batch<const requests extends Requests, allowFailure extends boolean = true>(
  client: Like,
  options: BatchOptions<requests, allowFailure>,
): Promise<batch.ReturnType<requests, allowFailure>>

Call it as ens.batch(options) on a client, or Actions.batch(client, options).

Parameters

OptionTypeDefaultDescription
requests (required)RequestsDeferred reads from action.request(options), as a list or a record.
allowFailurebooleantrueReport each request's failure in its result instead of failing the batch.
signalAbortSignalCancels the batch; the Promise rejects with signal.reason.

Returns

Resolves to { readonly results: Results<requests, allowFailure>; }. Results in the requests' shape.

FieldTypeDescription
resultsResults<Requests, boolean>

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_RECORD_VALUEa request that cannot be batched.
The first request's error with allowFailure: false.

It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).

See How errors work.

Examples

Loading a profile
import { Actions } from "@ensforge/sdk"

const { results } = await ens.batch({
  requests: {
    address: Actions.record.getAddress.request({ name: "nick.eth" }),
    avatar: Actions.record.getText.request({ name: "nick.eth", key: "avatar" }),
  },
})
A list with a standalone call
import { Actions } from "@ensforge/sdk"

const { results: [state, primary] } = await Actions.batch(publicClient, {
  requests: [Actions.name.get.request({ name: "nick.eth" }), Actions.primaryName.get.request({ address })],
  allowFailure: false,
})

See also

  • name.get and every other read's .request

Was this page helpful?