DisplayReactor

Defined in: display-reactor.ts:77

DisplayReactor provides automatic type transformations between Candid and display-friendly types, plus optional argument validation.

Type Transformations

bigint → string (for JSON/UI display)
Principal → string (text representation)
[T] | [] → T | null (optional unwrapping)
Small blobs → hex strings

Validation (Optional)

Register validators to check arguments before canister calls. Validators receive display types (strings), making them perfect for form validation.

Example

import { DisplayReactor } from "@ic-reactor/core"

const reactor = new DisplayReactor<_SERVICE>({
  clientManager,
  canisterId: "...",
  idlFactory,
})

// Optional: Add validation
reactor.registerValidator("transfer", ([input]) => {
  if (!input.to) {
    return {
      success: false,
      issues: [{ path: ["to"], message: "Recipient is required" }]
    }
  }
  return { success: true }
})

// Call with display types
await reactor.callMethod({
  functionName: "transfer",
  args: [{ to: "aaaaa-aa", amount: "100" }], // strings!
})

Extends

Reactor<A, T>

Type Parameters

A

A = BaseActor

The actor service type

T

T extends TransformKey = "display"

Constructors

Constructor

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

Defined in: display-reactor.ts:88

Parameters

config

DisplayReactorParameters<A>

Returns

DisplayReactor<A, T>

Overrides

Reactor.constructor

Properties

transform

readonly transform: T

Defined in: display-reactor.ts:81

Overrides

Reactor.transform

_actor

readonly _actor: A

Defined in: reactor.ts:46

Phantom type brand for inference - never assigned at runtime

Inherited from

Reactor._actor

clientManager

clientManager: ClientManager

Defined in: reactor.ts:48

Inherited from

Reactor.clientManager

name

name: string

Defined in: reactor.ts:49

Inherited from

Reactor.name

canisterId

canisterId: Principal

Defined in: reactor.ts:50

Inherited from

Reactor.canisterId

service

service: ServiceClass

Defined in: reactor.ts:51

Inherited from

Reactor.service

pollingOptions

pollingOptions: PollingOptions

Defined in: reactor.ts:52

Inherited from

Reactor.pollingOptions

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

Inherited from

Reactor.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

Inherited from

Reactor.agent

Methods

getCodec()

getCodec<M>(methodName): ActorMethodCodecs<A, M> | null

Defined in: display-reactor.ts:137

Get a codec for a specific method. Returns the args and result codecs for bidirectional transformation.

Type Parameters

M

M extends string

Parameters

methodName

M

The name of the method

Returns

ActorMethodCodecs<A, M> | null

Object with args and result codecs, or null if not found

registerValidator()

registerValidator<M>(methodName, validator): void

Defined in: display-reactor.ts:173

Type Parameters

M

M extends string

Parameters

methodName

M

The name of the method to validate

validator

DisplayValidator<A, M>

The validator function receiving display types

Returns

void

Example

// input.to is string, input.amount is string
reactor.registerValidator("transfer", ([input]) => {
  if (!/^\d+$/.test(input.amount)) {
    return {
      success: false,
      issues: [{ path: ["amount"], message: "Must be a valid number" }]
    }
  }
  return { success: true }
})

unregisterValidator()

unregisterValidator<M>(methodName): void

Defined in: display-reactor.ts:183

Unregister a validator for a specific method.

Type Parameters

M

M extends string

Parameters

methodName

M

Returns

void

hasValidator()

hasValidator<M>(methodName): boolean

Defined in: display-reactor.ts:190

Check if a method has a registered validator.

Type Parameters

M

M extends string

Parameters

methodName

M

Returns

boolean

validate()

validate<M>(methodName, args): Promise<ValidationResult>

Defined in: display-reactor.ts:218

Validate arguments without calling the canister. Arguments are in display format (strings for Principal/bigint). Useful for form validation before submission.

Type Parameters

M

M extends string

Parameters

methodName

M

The name of the method

args

ReactorArgs<A, M, T>

The display-type arguments to validate

Returns

Promise<ValidationResult>

ValidationResult indicating success or failure

Example

// Validate form data before submission
const result = await reactor.validate("transfer", [{
  to: formData.recipient,  // string
  amount: formData.amount, // string
}])

if (!result.success) {
  result.issues.forEach(issue => {
    form.setError(issue.path[0], issue.message)
  })
}

callMethodWithValidation()

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

Defined in: display-reactor.ts:254

Call a method with async validation support. Use this instead of callMethod() when you have async validators.

Type Parameters

M

M extends string

Parameters

params

functionName

M

args?

ReactorArgs<A, M, T>

callConfig?

CallConfig

Returns

Promise<ReactorReturnOk<A, M, T>>

Example

// Async validator (e.g., check if address is blocked)
reactor.registerValidator("transfer", async ([input]) => {
  const isBlocked = await checkBlocklist(input.to)
  if (isBlocked) {
    return {
      success: false,
      issues: [{ path: ["to"], message: "Address is blocked" }]
    }
  }
  return { success: true }
})

await reactor.callMethodWithValidation({
  functionName: "transfer",
  args: [{ to: "...", amount: "100" }],
})

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()

Inherited from

Reactor.setCanisterId

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()

Inherited from

Reactor.setCanisterName

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

Inherited from

Reactor.getServiceInterface

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

Inherited from

Reactor.isQueryMethod

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[]

Inherited from

Reactor.generateQueryKey

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>>

Inherited from

Reactor.getQueryOptions

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'] })

Inherited from

Reactor.invalidateQueries

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 },
});