@ic-reactor/core 0.5.2 → 1.0.0

package/README.md

@@ -1,22 +1,18 @@
-# IC-ReActor - Core
+# @ic-reactor/core
 
-ReActor is a JavaScript utility designed to streamline state management and interaction with actors in the Internet Computer (IC) blockchain environment. It provides a simple and effective way to handle asynchronous calls, state updates, and subscriptions, making it easier to build responsive and data-driven applications.
+The `@ic-reactor/core` package provides a streamlined way to interact with the Internet Computer (IC) by simplifying agent and actor management. It offers utilities for creating and managing IC agents, enabling seamless communication with canisters through a friendly API.
 
-## Features
+## Installation
 
-- **State Management**: Efficiently manage the state of your application with actor-based interactions.
-- **Asynchronous Handling**: Simplify asynchronous calls and data handling with built-in methods.
-- **Subscription Mechanism**: Subscribe to state changes and update your UI in real-time.
-- **Auto-Refresh Capability**: Automatically refresh data at specified intervals.
-- **Customizable**: Easily adaptable to various use cases within the IC ecosystem.
+To get started with `@ic-reactor/core`, you can install the package using npm or Yarn:
 
-## Installation
+**Using npm:**
 
 ```bash
 npm install @ic-reactor/core
 ```
 
-or
+**Using Yarn:**
 
 ```bash
 yarn add @ic-reactor/core
@@ -24,85 +20,191 @@ yarn add @ic-reactor/core
 
 ## Usage
 
-To get started with ReActor, you'll need to initialize it with your actor configurations. Here's a basic example:
+`@ic-reactor/core` can be utilized in two primary ways: automatic agent creation and manual agent management. Below are examples of both approaches to suit your project's needs.
 
-```javascript
-import { createReActor } from "@ic-reactor/core"
+### Automatic Agent Creation
 
-const { actorStore, authStore, queryCall, updateCall } = createReActor(
-  (agent) => createActor("bd3sg-teaaa-aaaaa-qaaba-cai", { agent }),
-  {
-    host: "https://localhost:4943",
-    initializeOnMount: true,
-  }
-)
-```
+For ease of use, the `createReActorStore` factory function automatically sets up a new ReActor store instance, managing the agent and its state internally.
 
-### Querying Data
+**Example:**
 
-```javascript
-const { recall, subscribe, getState, initialData, intervalId } = queryCall({
-  functionName: "yourFunctionName",
-  args: ["arg1", "arg2"],
-  autoRefresh: true,
-  refreshInterval: 3000,
+```typescript
+import { createReActorStore } from "@ic-reactor/core"
+import { candid, canisterId, idlFactory } from "./candid"
+
+type Candid = typeof candid
+
+const { callMethod, authenticate } = createReActor<Candid>({
+  canisterId,
+  idlFactory,
 })
 
-// Subscribe to changes
-const unsubscribe = subscribe((newState) => {
-  // Handle new state
+// Usage example
+const identity = await authenticate()
+const data = await callMethod("version")
+console.log(data)
+```
+
+### Manual Agent Creation
+
+If you require more control over the agent's lifecycle or configuration, `@ic-reactor/core` provides the `createAgentManager` function for manual agent instantiation.
+
+**IC Agent Example:**
+
+```typescript
+// agent.ts
+import { createAgentManager } from "@ic-reactor/core"
+
+export const agentManager = createAgentManager() // Connects to IC network by default
+
+// Usage example
+await agentManager.authenticate()
+// Then use the store to access the authClient, identity, and more...
+const { authClient, identity, authenticating } =
+  agentManager.authStore.getState()
+```
+
+**Local Agent Example:**
+
+For development purposes, you might want to connect to a local instance of the IC network:
+
+```typescript
+// agent.ts
+import { createAgentManager } from "@ic-reactor/core"
+
+export const agentManager = createAgentManager({
+  isLocalEnv: true,
+  port: 8000, // Default port is 4943
 })
+```
 
-// Fetch data
-recall().then((data) => {
-  // Handle initial data
+Alternatively, you can specify a host directly:
+
+```typescript
+export const agentManager = createAgentManager({
+  host: "http://localhost:8000",
 })
+```
+
+### Creating an Actor Manager
+
+Once you have an agent manager, use `createActorManager` to instantiate an actor manager for calling methods on your canisters.
+
+```typescript
+// actor.ts
+import { createActorManager } from "@ic-reactor/core"
+import { candid, canisterId, idlFactory } from "./candid"
+import { agentManager } from "./agent"
+
+type Candid = typeof candid
 
-// Get initial data
-initialData.then((data) => {
-  // Handle initial data
+const candidActor = createActorManager<Candid>({
+  agentManager,
+  canisterId,
+  idlFactory,
 })
 
-// Clear interval if autoRefresh is enabled
-if (intervalId) {
-  clearInterval(intervalId)
-}
+// Usage example
+const data = await candidActor.callMethod("version")
+console.log(data)
 ```
 
-### Updating Data
+### Managing Multiple Actors
+
+When interacting with multiple canisters using `@ic-reactor/core`, you can create separate actor managers for each canister. This enables modular interaction with different services on the Internet Computer. Here's how to adjust the example to handle methods that require multiple arguments:
+
+**Creating Actor Managers:**
+
+First, ensure you have your actor managers set up for each canister:
+
+```typescript
+// Assuming you've already set up `candidA`, `candidB`, `canisterIdA`, `canisterIdB`, and `agentManager`
+
+import { createActorManager } from "@ic-reactor/core"
+import { candidA, canisterIdA } from "./candidA"
+import { candidB, canisterIdB } from "./candidB"
+import { agentManager } from "./agent"
 
-```javascript
-const { call, getState, subscribe } = updateCall({
-  functionName: "yourUpdateFunction",
-  args: ["arg1", "arg2"],
+type CandidA = typeof candidA
+type CandidB = typeof candidB
+
+const actorA = createActorManager<CandidA>({
+  agentManager,
+  canisterId: canisterIdA,
+  idlFactory: candidA.idlFactory,
 })
 
-call().then((result) => {
-  // Handle result
+const actorB = createActorManager<CandidB>({
+  agentManager,
+  canisterId: canisterIdB,
+  idlFactory: candidB.idlFactory,
 })
+```
 
-// Get state
-const state = getState()
+### Using `callMethod` with Multiple Arguments
 
-// Subscribe to changes
-const unsubscribe = subscribe((newState) => {
-  // Handle new state
-})
+To call a method on a canister that requires multiple arguments, pass the method name followed by the arguments as separate parameters to `callMethod`:
+
+```typescript
+// Example usage with CanisterA calling a method that requires one argument
+const responseA = await actorA.callMethod("otherMethod", "arg1")
+console.log("Response from CanisterA method:", responseA)
+
+// Example usage with CanisterB calling a different method also with two arguments
+const responseB = await actorB.callMethod("anotherMethod", "arg1", "arg2")
+console.log("Response from CanisterB method:", responseB)
 ```
 
-## API Reference
+### Using Candid Adapter
+
+The `CandidAdapter` class is used to interact with a canister and retrieve its Candid interface definition. It provides methods to fetch the Candid definition either from the canister's metadata or by using a temporary hack method.
+If both methods fail, it throws an error.
 
-- `queryCall`: Fetches and subscribes to data from an actor method. Returns an object containing methods for recalling data, subscribing to changes, getting the current state, and the initial data promise.
-- `updateCall`: Updates data and handles state changes for an actor method. Returns an object containing methods for calling the update function, subscribing to changes, and getting the current state.
-- `getState`: Retrieves the current state based on the request hash.
-- `subscribe`: Allows subscription to state changes.
+```typescript
+import { createCandidAdapter } from "@ic-reactor/core"
+import { agentManager } from "./agent"
 
-For more detailed API usage and options, please refer to the [documentation](#).
+const candidAdapter = createCandidAdapter({ agentManager })
 
-## Contributing
+const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai"
 
-Contributions are welcome! Please read our [contributing guidelines](#) to get started.
+// Usage example
+try {
+  const definition = await candidAdapter.getCandidDefinition(canisterId)
+  console.log(definition)
+} catch (error) {
+  console.error(error)
+}
+```
+
+### Using `createReActorStore` with `CandidAdapter`
+
+You can use the `candidAdapter` to fetch the Candid definition and then pass it to the `createReActorStore` function.
+
+```typescript
+import { createReActorStore, createCandidAdapter } from "@ic-reactor/core"
+import { agentManager } from "./agent"
+
+const candidAdapter = createCandidAdapter({ agentManager })
+
+const canisterId = "ryjl3-tyaaa-aaaaa-aaaba-cai" // NNS ICP Ledger Canister
+
+// Usage example
+try {
+  const { idlFactory } = await candidAdapter.getCandidDefinition(canisterId)
+  const { callMethod } = createReActorStore({
+    agentManager,
+    canisterId,
+    idlFactory,
+  })
+
+  const name = await callMethod("name")
+  console.log(name) // { name: 'Internet Computer' }
+} catch (error) {
+  console.error(error)
+}
+```
 
-## License
+## Conclusion
 
-This project is licensed under [MIT License](LICENSE).
+The `@ic-reactor/core` package offers a flexible and powerful way to interact with the Internet Computer, catering to both straightforward use cases with automatic agent management and more complex scenarios requiring manual control. By abstracting away some of the intricacies of agent and actor management, it enables developers to focus more on building their applications.

package/dist/actor/index.d.ts

@@ -0,0 +1,31 @@
+import type { HttpAgent } from "@dfinity/agent";
+import type { CanisterId, ActorMethodArgs, ActorMethodReturnType, ActorStore, ActorManagerOptions, FunctionName, VisitService, BaseActor, ActorMethodState } from "./types";
+import type { AgentManager, UpdateAgentOptions } from "../agent";
+export * from "./types";
+export declare class ActorManager<A = BaseActor> {
+    private _actor;
+    private _idlFactory;
+    private _agentManager;
+    canisterId: CanisterId;
+    actorStore: ActorStore<A>;
+    visitFunction: VisitService<A>;
+    private initialState;
+    unsubscribeActor: () => void;
+    private updateState;
+    updateMethodState: (method: FunctionName<A>, hash: string, newState: Partial<{
+        data: ActorMethodReturnType<A[FunctionName<A>]> | undefined;
+        loading: boolean;
+        error: Error | undefined;
+    }>) => void;
+    constructor(actorConfig: ActorManagerOptions);
+    initialize: (options?: UpdateAgentOptions) => Promise<void>;
+    extractService(): VisitService<A>;
+    private initializeActor;
+    callMethod: <M extends FunctionName<A>>(functionName: M, ...args: ActorMethodArgs<A[M]>) => Promise<ActorMethodReturnType<A[M]>>;
+    get agentManager(): AgentManager;
+    getAgent: () => HttpAgent;
+    getActor: () => A | null;
+    getState: ActorStore<A>["getState"];
+    subscribeActorState: ActorStore<A>["subscribe"];
+    setState: ActorStore<A>["setState"];
+}

package/dist/actor/index.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActorManager = void 0;
+/* eslint-disable no-console */
+const agent_1 = require("@dfinity/agent");
+const helper_1 = require("../tools/helper");
+const candid_1 = require("@dfinity/candid");
+__exportStar(require("./types"), exports);
+class ActorManager {
+    constructor(actorConfig) {
+        this._actor = null;
+        this.initialState = {
+            methodState: {},
+            initializing: false,
+            initialized: false,
+            error: undefined,
+        };
+        this.updateState = (newState) => {
+            this.actorStore.setState((state) => (Object.assign(Object.assign({}, state), newState)));
+        };
+        this.updateMethodState = (method, hash, newState) => {
+            this.actorStore.setState((state) => {
+                const methodState = state.methodState[method] || {};
+                const currentMethodState = methodState[hash] || {
+                    loading: false,
+                    data: undefined,
+                    error: undefined,
+                };
+                const updatedMethodState = Object.assign(Object.assign({}, methodState), { [hash]: Object.assign(Object.assign({}, currentMethodState), newState) });
+                return Object.assign(Object.assign({}, state), { methodState: Object.assign(Object.assign({}, state.methodState), { [method]: updatedMethodState }) });
+            });
+        };
+        this.initialize = (options) => __awaiter(this, void 0, void 0, function* () {
+            yield this._agentManager.updateAgent(options);
+        });
+        this.initializeActor = (agent) => {
+            console.info(`Initializing actor ${this.canisterId} on ${agent.isLocal() ? "local" : "ic"} network`);
+            const { _idlFactory: idlFactory, canisterId } = this;
+            this.updateState({
+                initializing: true,
+                initialized: false,
+                methodState: {},
+            });
+            try {
+                if (!agent) {
+                    throw new Error("Agent not initialized");
+                }
+                this._actor = agent_1.Actor.createActor(idlFactory, {
+                    agent,
+                    canisterId,
+                });
+                if (!this._actor) {
+                    throw new Error("Failed to initialize actor");
+                }
+                this.updateState({
+                    initializing: false,
+                    initialized: true,
+                });
+            }
+            catch (error) {
+                console.error("Error in initializeActor:", error);
+                this.updateState({ error: error, initializing: false });
+            }
+        };
+        this.callMethod = (functionName, ...args) => __awaiter(this, void 0, void 0, function* () {
+            if (!this._actor) {
+                throw new Error("Actor not initialized");
+            }
+            if (!this._actor[functionName] ||
+                typeof this._actor[functionName] !== "function") {
+                throw new Error(`Method ${String(functionName)} not found`);
+            }
+            const method = this._actor[functionName];
+            const data = yield method(...args);
+            return data;
+        });
+        this.getAgent = () => {
+            return this._agentManager.getAgent();
+        };
+        // actor store
+        this.getActor = () => {
+            return this._actor;
+        };
+        this.getState = () => {
+            return this.actorStore.getState();
+        };
+        this.subscribeActorState = (listener) => {
+            return this.actorStore.subscribe(listener);
+        };
+        this.setState = (updater) => {
+            return this.actorStore.setState(updater);
+        };
+        const { agentManager, canisterId, idlFactory, withVisitor = false, withDevtools = false, initializeOnCreate = true, } = actorConfig;
+        this._agentManager = agentManager;
+        this.unsubscribeActor = this._agentManager.subscribeAgent(this.initializeActor);
+        this.canisterId = canisterId;
+        this._idlFactory = idlFactory;
+        if (withVisitor) {
+            this.visitFunction = this.extractService();
+        }
+        else {
+            this.visitFunction = emptyVisitor;
+        }
+        // Initialize stores
+        this.actorStore = (0, helper_1.createStoreWithOptionalDevtools)(this.initialState, {
+            withDevtools,
+            store: `actor-${String(canisterId)}`,
+        });
+        if (initializeOnCreate) {
+            this.initializeActor(agentManager.getAgent());
+        }
+    }
+    extractService() {
+        return this._idlFactory({ IDL: candid_1.IDL })._fields.reduce((acc, service) => {
+            const functionName = service[0];
+            const type = service[1];
+            const visit = ((extractorClass, data) => {
+                return type.accept(extractorClass, data || functionName);
+            });
+            acc[functionName] = visit;
+            return acc;
+        }, {});
+    }
+    // agent store
+    get agentManager() {
+        return this._agentManager;
+    }
+}
+exports.ActorManager = ActorManager;
+const emptyVisitor = new Proxy({}, {
+    get: function (_, prop) {
+        throw new Error(`Cannot visit function "${String(prop)}" without initializing the actor with the visitor option, please set the withVisitor option to true when creating the actor manager.`);
+    },
+});

package/dist/actor/types.d.ts

@@ -0,0 +1,46 @@
+import type { IDL } from "@dfinity/candid";
+import type { StoreApi } from "zustand";
+import type { AgentManager } from "../agent";
+import type { ActorMethod, ActorSubclass, Principal } from "../types";
+export interface DefaultActorType {
+    [key: string]: ActorMethod;
+}
+export type BaseActor<T = DefaultActorType> = ActorSubclass<T>;
+export type FunctionName<A = BaseActor> = keyof A & string;
+export type FunctionType = "query" | "update";
+export type CanisterId = string | Principal;
+export interface ActorManagerOptions {
+    agentManager: AgentManager;
+    idlFactory: IDL.InterfaceFactory;
+    canisterId: CanisterId;
+    withVisitor?: boolean;
+    withDevtools?: boolean;
+    initializeOnCreate?: boolean;
+}
+export type VisitorType<V> = V extends IDL.Visitor<infer D, infer R> ? {
+    data: D;
+    returnType: R;
+} : never;
+export type VisitService<A = BaseActor, M extends FunctionName<A> = FunctionName<A>> = {
+    [K in M]: <V extends IDL.Visitor<unknown, unknown>>(extractorClass: V, data?: VisitorType<V>["data"]) => ReturnType<V["visitFunc"]>;
+};
+export type ActorMethodArgs<T> = T extends ActorMethod<infer Args, any> ? Args : never;
+export type ActorMethodReturnType<T> = T extends ActorMethod<any, infer Ret> ? Ret : never;
+export interface ActorMethodState<A, M extends keyof A> {
+    [key: string]: {
+        data: ActorMethodReturnType<A[M]> | undefined;
+        loading: boolean;
+        error: Error | undefined;
+    };
+}
+export type ActorMethodStates<A> = {
+    [M in keyof A]: ActorMethodState<A, M>;
+};
+export type ActorState<A> = {
+    initialized: boolean;
+    initializing: boolean;
+    error: Error | undefined;
+    methodState: ActorMethodStates<A>;
+};
+export type ActorStore<A = BaseActor> = StoreApi<ActorState<A>>;
+export type CallActorMethod<A = BaseActor> = <M extends keyof A>(functionName: M, ...args: ActorMethodArgs<A[M]>) => Promise<ActorMethodReturnType<A[M]>>;

package/dist/actor/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/agent/index.d.ts

@@ -0,0 +1,32 @@
+import { HttpAgent } from "@dfinity/agent";
+import type { AgentStore, AgentManagerOptions, UpdateAgentOptions, AuthStore } from "./types";
+export * from "./types";
+export declare const IC_HOST_NETWORK_URI = "https://ic0.app";
+export declare const LOCAL_HOST_NETWORK_URI = "http://127.0.0.1:4943";
+export declare class AgentManager {
+    private _agent;
+    private _subscribers;
+    agentStore: AgentStore;
+    authStore: AuthStore;
+    isLocalEnv: boolean;
+    private initialAgentState;
+    private initialAuthState;
+    private updateAgentState;
+    private updateAuthState;
+    constructor(options?: AgentManagerOptions);
+    private initializeAgent;
+    subscribeAgent: (callback: (agent: HttpAgent) => void) => () => void;
+    unsubscribeAgent: (callback: (agent: HttpAgent) => void) => void;
+    private notifySubscribers;
+    updateAgent: (options?: UpdateAgentOptions) => Promise<void>;
+    authenticate: () => Promise<import("@dfinity/agent").Identity>;
+    getAgent: () => HttpAgent;
+    getAgentStore: () => AgentStore;
+    getAgentState: AgentStore["getState"];
+    subscribeAgentState: AgentStore["subscribe"];
+    getAuthState: AuthStore["getState"];
+    subscribeAuthState: AuthStore["subscribe"];
+    getAuthClient: () => import("@dfinity/auth-client").AuthClient | null;
+    getIdentity: () => import("@dfinity/agent").Identity | null;
+    getPrincipal: () => import("@dfinity/principal").Principal | null;
+}