Reactor

Defined in: reactor.ts:44

Reactor class for interacting with IC canisters.

This class provides core functionality for:

• Direct agent calls using agent.call() and agent.query()
• Query caching with TanStack Query integration
• Method calls with result unwrapping

Extended by

• DisplayReactor

Type Parameters

A

A = BaseActor

The actor service type

T

T extends TransformKey = "candid"

The type transformation to apply (default: candid = raw Candid types)

Constructors

Constructor

new Reactor<A, T>(config): Reactor<A, T>

Defined in: reactor.ts:54

Parameters

config

ReactorParameters

Returns

Reactor<A, T>

Properties

_actor

readonly _actor: A

Defined in: reactor.ts:46

Phantom type brand for inference - never assigned at runtime

---

transform

readonly transform: keyof TransformArgsRegistry<unknown> = "candid"

Defined in: reactor.ts:47

---

clientManager

clientManager: ClientManager

Defined in: reactor.ts:48

---

name

name: string

Defined in: reactor.ts:49

---

canisterId

canisterId: Principal

Defined in: reactor.ts:50

---

service

service: ServiceClass

Defined in: reactor.ts:51

---

pollingOptions

pollingOptions: PollingOptions

Defined in: reactor.ts:52

Accessors

queryClient

Get Signature

get queryClient(): QueryClient

Defined in: reactor.ts:450

Get the query client from clientManager. This is the recommended way to access the query client for direct queries.

Returns

QueryClient

---

agent

Get Signature

get agent(): HttpAgent

Defined in: reactor.ts:458

Get the agent from clientManager. This is the recommended way to access the agent for direct calls.

Returns

HttpAgent

Methods

setCanisterId()

setCanisterId(canisterId): void

Defined in: reactor.ts:104

Set the canister ID for this reactor. Useful for dynamically switching between canisters of the same type (e.g., multiple ICRC tokens).

Parameters

canisterId

CanisterId

The new canister ID (as string or Principal)

Returns

void

Example

// Switch to a different ledger canister
ledgerReactor.setCanisterId("ryjl3-tyaaa-aaaaa-aaaba-cai")

// Then use queries/mutations as normal
const { data } = icrc1NameQuery.useQuery()

---

setCanisterName()

setCanisterName(name): void

Defined in: reactor.ts:125

Set the canister name for this reactor. Useful for dynamically switching between canisters of the same type (e.g., multiple ICRC tokens).

Parameters

name

string

The new canister name

Returns

void

Example

// Switch to a different ledger canister
ledgerReactor.setCanisterName("icrc1")

// Then use queries/mutations as normal
const { data } = icrc1NameQuery.useQuery()

---

getServiceInterface()

getServiceInterface(): ServiceClass

Defined in: reactor.ts:138

Get the service interface (IDL.ServiceClass) for this reactor. Useful for introspection and codec generation.

Returns

ServiceClass

The service interface

---

isQueryMethod()

isQueryMethod<M>(methodName): boolean

Defined in: reactor.ts:157

Check if a method is a query method (query or composite_query).

Type Parameters

M

M extends string

Parameters

methodName

M

Returns

boolean

---

generateQueryKey()

generateQueryKey<M>(params): readonly unknown[]

Defined in: reactor.ts:199

Type Parameters

M

M extends string

Parameters

params

ReactorQueryParams<A, M, T>

Returns

readonly unknown[]

---

getQueryOptions()

getQueryOptions<M>(params): FetchQueryOptions<ReactorReturnOk<A, M, T>>

Defined in: reactor.ts:219

Type Parameters

M

M extends string

Parameters

params

ReactorCallParams<A, M, T>

Returns

FetchQueryOptions<ReactorReturnOk<A, M, T>>

---

invalidateQueries()

invalidateQueries<M>(params?): void

Defined in: reactor.ts:246

Invalidate cached queries for this canister. This will mark matching queries as stale and trigger a refetch for any active queries.

Type Parameters

M

M extends string

Parameters

params?

Partial<ReactorQueryParams<A, M, T>>

Optional parameters to filter the invalidation

Returns

void

Example

// Invalidate all queries for this canister
reactor.invalidateQueries()

// Invalidate only 'getUser' queries
reactor.invalidateQueries({ functionName: 'getUser' })

// Invalidate 'getUser' query for specific user
reactor.invalidateQueries({ functionName: 'getUser', args: ['user-1'] })

---

callMethod()

callMethod<M>(params): Promise<ReactorReturnOk<A, M, T>>

Defined in: reactor.ts:286

Call a canister method directly using agent.call() or agent.query(). This is the recommended approach for interacting with canisters.

Type Parameters

M

M extends string

Parameters

params

Omit<ReactorCallParams<A, M, T>, "queryKey">

Returns

Promise<ReactorReturnOk<A, M, T>>

Example

// Query method
const result = await reactor.callMethod({
  functionName: 'greet',
  args: ['world'],
});

// Update method with options
const result = await reactor.callMethod({
  functionName: 'transfer',
  args: [{ to: principal, amount: 100n }],
  callConfig: { effectiveCanisterId: principal },
});

---

fetchQuery()

fetchQuery<M>(params): Promise<ReactorReturnOk<A, M, T>>

Defined in: reactor.ts:359

Fetch data from the canister and cache it using React Query. This method ensures the data is in the cache and returns it.

Type Parameters

M

M extends string

Parameters

params

ReactorCallParams<A, M, T>

Returns

Promise<ReactorReturnOk<A, M, T>>

---

getQueryData()

getQueryData<M>(params): ReactorReturnOk<A, M, T> | undefined

Defined in: reactor.ts:369

Get the current data from the cache without fetching.

Type Parameters

M

M extends string

Parameters

params

ReactorQueryParams<A, M, T>

Returns

ReactorReturnOk<A, M, T> | undefined

---

subnetId()

subnetId(): Promise<Principal>

Defined in: reactor.ts:430

Get the subnet ID for this canister.

Returns

Promise<Principal>

---

subnetState()

subnetState(options): Promise<ReadStateResponse>

Defined in: reactor.ts:437

Get the subnet state for this canister.

Parameters

options

ReadStateOptions

Returns

Promise<ReadStateResponse>