Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ActorClient<IndexCanisterType, ActorCanisterType>

The ActorClient allows for a frontend to interface with one or many canisters that share a specific Internet Computer Actor type.

example
// Example of creating an ActorClient for interfacing with one or many User Actor canisters

import { IndexCanister } from "..<path_to>/declarations/index/index.did"; // from generated index canister declaration files
import { UserCanister } from "..<path_to>/declarations/user/user.did"; // from generated user canister declaration files
import { idlFactory as UserCanisterIDL } from "..<path_to>/declarations/user"; // from generated user canister declaration files

const userActorClient = new ActorClient<IndexCanister, UserCanister>({
  actorOptions: {
    IDL: UserCanisterIDL,
    agentOptions: {
      host: <insert_host>,
      identity: <insert_identity>
    },
  },
  indexClient: <insert_index_client>
});

Type Parameters

  • IndexCanisterType extends BaseIndexCanisterType = never

    the canister interface (generated) for the index canister

  • ActorCanisterType extends BaseActorClientType = never

    the canister interface (generated) for this specific actor client

Hierarchy

  • ActorClient

Index

Constructors

Methods

Constructors

constructor

Methods

query

  • query<F>(PK: string, queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>), useCache?: boolean): Promise<PromiseSettledResult<Awaited<ReturnType<F>>>[]>

  • Use to call a query function on all canisters with a specific PK

    example
    // Example calling the getPK() method defined on canisters with a specific PK via the User Actor

    const responses = await userActorClient.query<UserCanister["getPK"]>(
      PK,
      (actor) => actor.getPK()
    );

    Type Parameters

    • F extends ((...args: any[]) => ReturnType<F>)

    Parameters

    • PK: string

      Partition Key

    • queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>)

      the query function that will be executed on the canister. Takes in an actor and returns the ReturnType of F

        • (actor: ActorSubclass<ActorCanisterType>): ReturnType<F>

        • Parameters

          • actor: ActorSubclass<ActorCanisterType>

          Returns ReturnType<F>

    • Optional useCache: boolean

      whether the index canister needs to be hit again to fetch relevant PK canisters, or if the request can use the PK to canister cache list to query directly without needing to do so

    Returns Promise<PromiseSettledResult<Awaited<ReturnType<F>>>[]>

    • An array of settled promises of the query ReturnType.

queryReduce

  • queryReduce<F, U>(PK: string, queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>), reducer: ((accumulator: U, current: PromiseSettledResult<Awaited<ReturnType<F>>>) => U), initialValue: U, useCache?: boolean): Promise<U>

  • Use to call a query function on all canisters with a specific PK, and then to reduce that result

    example
    // An example making a query call to a getCount endpoint that returns a count, and then passing a reducer function that will reduce the response from potentially multiple canisters

    function reducer(acc: bigint, settledResult: PromiseSettledResult<Awaited<bigint>>): bigint {
      if (settledResult.status === "rejected") { return acc; };
      return acc + settledResult.value;
    };

    const reducedResult = await userActorClient.queryReduce<UserCanister["getCount"], bigint>(
      PK,
      (actor) => actor.getCount(),
      reducer,
      BigInt(0)
    );

    console.log("reduced result", reducedResult);

    Type Parameters

    • F extends ((...args: any[]) => Promise<any>)

    • U

    Parameters

    • PK: string

      Partition Key

    • queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>)

      the query function that will be executed on the canister. Takes in an actor and returns the ReturnType of F

        • (actor: ActorSubclass<ActorCanisterType>): ReturnType<F>

        • Parameters

          • actor: ActorSubclass<ActorCanisterType>

          Returns ReturnType<F>

    • reducer: ((accumulator: U, current: PromiseSettledResult<Awaited<ReturnType<F>>>) => U)

      function to reduce the array result of the query function being called on one or more canisters

        • (accumulator: U, current: PromiseSettledResult<Awaited<ReturnType<F>>>): U

        • Parameters

          • accumulator: U
          • current: PromiseSettledResult<Awaited<ReturnType<F>>>

          Returns U

    • initialValue: U

      intial value for the reducer

    • Optional useCache: boolean

      whether the index canister needs to be hit again to fetch relevant PK canisters, or if the request can use the PK to canister cache list to query directly without needing to do so

    Returns Promise<U>

    • An array of settled promises of the query ReturnType.

queryWithCanisterIdMapping

  • queryWithCanisterIdMapping<F>(PK: string, queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>), useCache?: boolean): Promise<PromiseSettledResult<{}>[]>

  • Note: may remove this function depending on utilization - (originally wrote this to retrieve canister specific metrics for the hackathon demo)

    Similar to query, but returns a mapping of canisterId to the query result returned by that canister.

    Important if want canister level information for a pk and don't want to go through the indexing canister. This is because going through the indexing canister would slow it down massively in a large multi-canister application

    Type Parameters

    • F extends ((...args: any[]) => ReturnType<F>)

    Parameters

    • PK: string

      Partition Key

    • queryFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>)

      the query function that will be executed on the canister. Takes in an actor and returns the ReturnType of F

        • (actor: ActorSubclass<ActorCanisterType>): ReturnType<F>

        • Parameters

          • actor: ActorSubclass<ActorCanisterType>

          Returns ReturnType<F>

    • Optional useCache: boolean

      whether the index canister needs to be hit again to fetch relevant PK canisters, or if the request can use the PK to canister cache list to query directly without needing to do so

    Returns Promise<PromiseSettledResult<{}>[]>

    • a promise settled result mapping of canisterId to the result of the query (TypeDoc fail - see source code for return type)

update

  • update<F>(pk: string, sk: string, updateFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>)): Promise<ReturnType<F>>

  • Calls an update method on a single canister actor with the specific PK and SK.

    If multiple canisters with the PK exist, first makes a query call to each canister to see if the SK exists.

    example
    // An example making an update call to an updateUserAttributes endpoint that updates a specific user's attributes


    let updateUserAttributesResult = await userActorClient.update<UserCanister["updateUserAttributes"]>(
      <insert PK>,
      <insert SK>,
      (actor) => actor.updateUserAttributes(attributes)
    );

    console.log("result", updateUserAttributesResult);

    Type Parameters

    • F extends ((...args: any[]) => ReturnType<F>)

    Parameters

    • pk: string

      partition key

    • sk: string

      sort key

    • updateFn: ((actor: ActorSubclass<ActorCanisterType>) => ReturnType<F>)

      update function to be called on the given actor

        • (actor: ActorSubclass<ActorCanisterType>): ReturnType<F>

        • Parameters

          • actor: ActorSubclass<ActorCanisterType>

          Returns ReturnType<F>

    Returns Promise<ReturnType<F>>

    • a promise with the result of the update function

Generated using TypeDoc