SkippableQueryConfig

Defined in: react/src/types.ts:165

Configuration for the non-suspense query hook of createActorHooks and defineReactor (useActorQuery): a QueryConfig whose args may also be TanStack Query’s skipToken, for a query whose arguments are not known yet.

A skipped query does not fetch. It has an entry of its own under its method’s key (at the canister and agent callConfig names), which no call’s key shares, so it shows no data until the arguments arrive, not even that of a call made without arguments. Once args holds arguments, the query is keyed and fetched as usual. Its refetch() has nothing to run: TanStack Query answers it with a “Missing queryFn” error, so offer a refresh only once the arguments exist.

The suspense hooks do not take skipToken: TanStack Query has no way to suspend on a query that cannot run.

Example

import { skipToken } from "@ic-reactor/react"

function Balance({ owner }: { owner?: string }) {
  // No `!`, no placeholder account, no `enabled`
  const { data } = useActorQuery({
    functionName: "icrc1_balance_of",
    args: owner ? [{ owner }] : skipToken,
  })
}

Extends

• Omit<QueryConfig<Service, Method, Transform, Selected>, "args">

Type Parameters

Service

Service = BaseActor

Method

Method extends FunctionName<Service> = FunctionName<Service>

Transform

Transform extends TransformKey = "candid"

Selected

Selected = QueryFnData<Service, Method, Transform>

Properties

functionName

functionName: Method

Defined in: react/src/types.ts:84

The method to call on the canister

Inherited from

Omit.functionName

---

callConfig?

optional callConfig?: CallConfig

Defined in: react/src/types.ts:105

Call configuration for the method, as Reactor.callMethod takes it: a canisterId sends the query to another canister of the same interface, an agent sends it through another agent, effectiveCanisterId routes it. The query key carries what it sets, as the hooks’ keys do, so the answer is cached apart from the reactor’s own canister and agent, and getQueryKey(), invalidate() and the other cache controls act on that entry.

Example

// The same ledger interface, another token's canister
const ckbtcSymbol = createQuery(ledger, {
  functionName: "icrc1_symbol",
  callConfig: { canisterId: "mxzaz-hqaaa-aaaar-qaada-cai" },
})

Inherited from

Omit.callConfig

---

queryKey?

optional queryKey?: readonly unknown[]

Defined in: react/src/types.ts:107

The query key to use for this query

Inherited from

Omit.queryKey

---

staleTime?

optional staleTime?: number

Defined in: react/src/types.ts:119

How long data stays fresh before refetching, in milliseconds.

createQuery, createSuspenseQuery and their factories default to 5 minutes. The bound useActorQuery and useActorSuspenseQuery hooks (from createActorHooks or defineReactor) set no default and leave it to TanStack Query, which reads the QueryClient’s defaultOptions.queries.staleTime. With that unset too, useActorQuery uses 0 and useActorSuspenseQuery uses 1 second, TanStack Query’s fallback for suspense queries.

Inherited from

BaseQueryConfig.staleTime

---

select?

optional select?: (data) => Selected

Defined in: react/src/types.ts:121

Transform the raw result before returning

Parameters

data

ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>

Returns

Selected

Inherited from

Omit.select

---

args?

optional args?: typeof skipToken | ReactorArgs<Service, Method, Transform>

Defined in: react/src/types.ts:175

Arguments to pass to the method, or skipToken while they are not known: the query then waits without fetching.