@ic-reactor/candid 3.0.7-beta.1 → 3.0.8-beta.0

package/src/reactor.ts

@@ -0,0 +1,199 @@
+import type { BaseActor, ReactorParameters } from "@ic-reactor/core"
+import type { CandidReactorParameters, DynamicMethodOptions } from "./types"
+
+import { Reactor } from "@ic-reactor/core"
+import { CandidAdapter } from "./adapter"
+import { IDL } from "@icp-sdk/core/candid"
+
+export class CandidReactor<A = BaseActor> extends Reactor<A> {
+  public adapter: CandidAdapter
+  private candidSource?: string
+
+  constructor(config: CandidReactorParameters) {
+    const superConfig = { ...config }
+
+    if (!superConfig.idlFactory) {
+      superConfig.idlFactory = ({ IDL }) => IDL.Service({})
+    }
+
+    super(superConfig as ReactorParameters)
+
+    this.candidSource = config.candid
+    if (config.adapter) {
+      this.adapter = config.adapter
+    } else {
+      this.adapter = new CandidAdapter({
+        clientManager: this.clientManager,
+      })
+    }
+  }
+
+  /**
+   * Initializes the reactor by parsing the provided Candid string or fetching it from the network.
+   * This updates the internal service definition with the actual canister interface.
+   *
+   * After initialization, all standard Reactor methods (callMethod, fetchQuery, etc.) work.
+   */
+  public async initialize(): Promise<void> {
+    let idlFactory: IDL.InterfaceFactory
+
+    if (this.candidSource) {
+      const definition = await this.adapter.parseCandidSource(this.candidSource)
+      idlFactory = definition.idlFactory
+    } else {
+      const definition = await this.adapter.getCandidDefinition(this.canisterId)
+      idlFactory = definition.idlFactory
+    }
+
+    this.service = idlFactory({ IDL })
+  }
+
+  /**
+   * Register a dynamic method by its Candid signature.
+   * After registration, all standard Reactor methods work with this method name.
+   *
+   * @example
+   * ```typescript
+   * // Register a method
+   * await reactor.registerMethod({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query"
+   * })
+   *
+   * // Now use standard Reactor methods!
+   * const balance = await reactor.callMethod({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner }]
+   * })
+   *
+   * // Or with caching
+   * const cachedBalance = await reactor.fetchQuery({
+   *   functionName: "icrc1_balance_of",
+   *   args: [{ owner }]
+   * })
+   * ```
+   */
+  public async registerMethod(options: DynamicMethodOptions): Promise<void> {
+    const { functionName, candid } = options
+
+    // Check if method already registered
+    const existing = this.service._fields.find(
+      ([name]) => name === functionName
+    )
+    if (existing) return
+
+    // Parse the Candid signature
+    const serviceSource = candid.includes("service :")
+      ? candid
+      : `service : { ${functionName} : ${candid}; }`
+
+    const { idlFactory } = await this.adapter.parseCandidSource(serviceSource)
+    const parsedService = idlFactory({ IDL })
+
+    const funcField = parsedService._fields.find(
+      ([name]) => name === functionName
+    )
+    if (!funcField) {
+      throw new Error(
+        `Method "${functionName}" not found in the provided Candid signature`
+      )
+    }
+
+    // Inject into our service
+    this.service._fields.push(funcField)
+  }
+
+  /**
+   * Register multiple methods at once.
+   */
+  public async registerMethods(methods: DynamicMethodOptions[]): Promise<void> {
+    await Promise.all(methods.map((m) => this.registerMethod(m)))
+  }
+
+  /**
+   * Check if a method is registered (either from initialize or registerMethod).
+   */
+  public hasMethod(functionName: string): boolean {
+    return this.service._fields.some(([name]) => name === functionName)
+  }
+
+  /**
+   * Get all registered method names.
+   */
+  public getMethodNames(): string[] {
+    return this.service._fields.map(([name]) => name)
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // DYNAMIC CALL SHORTCUTS
+  // ══════════════════════════════════════════════════════════════════════
+
+  /**
+   * Perform a dynamic update call in one step.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const result = await reactor.callDynamic({
+   *   functionName: "transfer",
+   *   candid: "(record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text })",
+   *   args: [{ to: Principal.fromText("..."), amount: 100n }]
+   * })
+   * ```
+   */
+  public async callDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Perform a dynamic query call in one step.
+   * Registers the method if not already registered, then calls it.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.queryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner: Principal.fromText("...") }]
+   * })
+   * ```
+   */
+  public async queryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.callMethod({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+
+  /**
+   * Fetch with dynamic Candid and TanStack Query caching.
+   * Registers the method if not already registered, then fetches with caching.
+   *
+   * @example
+   * ```typescript
+   * const balance = await reactor.fetchQueryDynamic({
+   *   functionName: "icrc1_balance_of",
+   *   candid: "(record { owner : principal }) -> (nat) query",
+   *   args: [{ owner }]
+   * })
+   * ```
+   */
+  public async fetchQueryDynamic<T = unknown>(
+    options: DynamicMethodOptions & { args?: unknown[] }
+  ): Promise<T> {
+    await this.registerMethod(options)
+    return this.fetchQuery({
+      functionName: options.functionName as any,
+      args: options.args as any,
+    }) as T
+  }
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { HttpAgent, Identity } from "@icp-sdk/core/agent"
+import type { IDL } from "@icp-sdk/core/candid"
+import type {
+  BaseActor,
+  CanisterId,
+  DisplayReactorParameters,
+  ReactorParameters,
+} from "@ic-reactor/core"
+import type { CandidAdapter } from "./adapter"
+
+export interface DynamicMethodOptions {
+  /** The method name to register. */
+  functionName: string
+  /**
+   * The Candid signature for the method.
+   * Can be either a method signature like "(text) -> (text) query"
+   * or a full service definition like "service : { greet: (text) -> (text) query }".
+   */
+  candid: string
+}
+
+export interface CandidReactorParameters extends Omit<
+  ReactorParameters,
+  "idlFactory"
+> {
+  /** The canister ID. */
+  canisterId?: CanisterId
+  /** The Candid source code. If not provided, the canister's Candid will be fetched. */
+  candid?: string
+  /** The IDL interface factory. */
+  idlFactory?: (IDL: any) => any
+  /** The Candid adapter. */
+  adapter?: CandidAdapter
+}
+
+// ============================================================================
+// CandidDisplayReactor Parameters
+// ============================================================================
+
+export interface CandidDisplayReactorParameters<A = BaseActor> extends Omit<
+  DisplayReactorParameters<A>,
+  "idlFactory"
+> {
+  /** The canister ID. */
+  canisterId?: CanisterId
+  /** The Candid source code. If not provided, the canister's Candid will be fetched. */
+  candid?: string
+  /** The IDL interface factory. */
+  idlFactory?: (IDL: any) => any
+  /** The Candid adapter. */
+  adapter?: CandidAdapter
+}
+
+/**
+ * Minimal interface for ClientManager that CandidAdapter depends on.
+ * This allows the candid package to work with ClientManager without importing the full core package.
+ */
+export interface CandidClientManager {
+  /** The HTTP agent used for making requests. */
+  agent: HttpAgent
+  /** Whether the agent is connected to a local network. */
+  isLocal: boolean
+  /** Subscribe to identity changes. Returns an unsubscribe function. */
+  subscribe(callback: (identity: Identity) => void): () => void
+}
+
+/**
+ * Parameters for initializing the CandidAdapter.
+ */
+export interface CandidAdapterParameters {
+  /** The client manager that provides agent and identity access. */
+  clientManager: CandidClientManager
+  /** The canister ID of the didjs canister for compiling Candid to JavaScript. */
+  didjsCanisterId?: CanisterId
+}
+
+/**
+ * Represents a parsed Candid definition with IDL factory and initialization.
+ */
+export interface CandidDefinition {
+  /** The IDL interface factory. */
+  idlFactory: IDL.InterfaceFactory
+  /** Optional init function for the canister. */
+  init?: (args: { IDL: typeof IDL }) => IDL.Type<unknown>[]
+}
+
+/**
+ * Interface for the optional parser module (@ic-reactor/parser).
+ */
+export interface ReactorParser {
+  /**
+   * Default function to initialize the WASM module.
+   */
+  default?: () => Promise<void>
+  /**
+   * Converts Candid (DID) source to JavaScript code.
+   * @param candidSource - The Candid source code.
+   * @returns The JavaScript code.
+   */
+  didToJs(candidSource: string): string
+  /**
+   * Validates the Candid (IDL) source.
+   * @param candidSource - The Candid source code.
+   * @returns True if valid, false otherwise.
+   */
+  validateIDL(candidSource: string): boolean
+}

package/src/utils.ts

@@ -0,0 +1,28 @@
+import type { CandidDefinition } from "./types"
+
+/**
+ * Imports and evaluates a Candid definition from JavaScript code.
+ *
+ * @param candidJs - The JavaScript code containing the Candid definition.
+ * @returns A promise that resolves to the CandidDefinition.
+ * @throws Error if the import fails.
+ */
+export async function importCandidDefinition(
+  candidJs: string
+): Promise<CandidDefinition> {
+  try {
+    // Create a data URL with the JavaScript code
+    const dataUri =
+      "data:text/javascript;charset=utf-8," + encodeURIComponent(candidJs)
+
+    // Dynamically import the module
+    const module = await import(/* webpackIgnore: true */ dataUri)
+
+    return {
+      idlFactory: module.idlFactory,
+      init: module.init,
+    }
+  } catch (error) {
+    throw new Error(`Failed to import Candid definition: ${error}`)
+  }
+}