DisplayReactor

Defined in: display-reactor.ts:135

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, "display">

Type Parameters

A

A = BaseActor

The actor service type

Constructors

Constructor

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

Defined in: display-reactor.ts:143

Parameters

config

DisplayReactorParameters<A>

Returns

DisplayReactor<A>

Overrides

Reactor.constructor

Properties

transform

readonly transform: "display" = "display"

Defined in: display-reactor.ts:136

Overrides

Reactor.transform

_actor

readonly _actor: A

Defined in: reactor.ts:44

Phantom type brand for inference - never assigned at runtime

Inherited from

Reactor._actor

clientManager

clientManager: ClientManager

Defined in: reactor.ts:46

Inherited from

Reactor.clientManager

name

name: string

Defined in: reactor.ts:47

Inherited from

Reactor.name

canisterId

canisterId: Principal

Defined in: reactor.ts:48

Inherited from

Reactor.canisterId

service

service: ServiceClass

Defined in: reactor.ts:49

Inherited from

Reactor.service

pollingOptions

pollingOptions: PollingOptions

Defined in: reactor.ts:50

Inherited from

Reactor.pollingOptions

Accessors

queryClient

Get Signature

get queryClient(): QueryClient

Defined in: reactor.ts:399

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

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

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

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

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

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

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

AsDisplayArgs<ActorMethodParameters<A[M]>>

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<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

Defined in: display-reactor.ts:309

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?

AsDisplayArgs<ActorMethodParameters<A[M]>>

callConfig?

CallConfig

Returns

Promise<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

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" }],
})

getServiceInterface()

getServiceInterface(): ServiceClass

Defined in: reactor.ts:86

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

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

Type Parameters

M

M extends string

Parameters

params

ReactorQueryParams<A, M, "display">

Returns

readonly unknown[]

Inherited from

Reactor.generateQueryKey

getQueryOptions()

getQueryOptions<M>(params): FetchQueryOptions<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

Defined in: reactor.ts:167

Type Parameters

M

M extends string

Parameters

params

ReactorCallParams<A, M, "display">

Returns

FetchQueryOptions<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

Inherited from

Reactor.getQueryOptions

invalidateQueries()

invalidateQueries<M>(params?): void

Defined in: reactor.ts:214

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, "display">>

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<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

Defined in: reactor.ts:254

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<DisplayOf<OkResult<ActorMethodReturnType<A[M]>>>>

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