@ic-reactor/candid 3.0.2-beta.0 → 3.0.2

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,127 @@
+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
+  /**
+   * An IDL.FuncClass to register as a single-method service.
+   * Use this to create a reactor for a funcRecord callback.
+   * When provided, the reactor is ready to use immediately (no `initialize()` needed).
+   *
+   * @example
+   * ```typescript
+   * const archiveReactor = new CandidDisplayReactor({
+   *   canisterId: archived.canisterId,
+   *   clientManager,
+   *   funcClass: { methodName: "get_blocks", func: archiveFuncClass },
+   * })
+   * ```
+   */
+  funcClass?: {
+    /** The method name to register */
+    methodName: string
+    /** The IDL.FuncClass describing the function signature */
+    func: import("@icp-sdk/core/candid").IDL.FuncClass
+  }
+}
+
+/**
+ * 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,60 @@
+import type { CandidDefinition } from "./types"
+import { IDL } from "@icp-sdk/core/candid"
+
+/**
+ * Imports and evaluates a Candid definition from JavaScript code.
+ *
+ * This function evaluates JavaScript code in a controlled manner to extract
+ * the idlFactory and init exports. The evaluation is done using Function constructor
+ * which is safer than dynamic imports with data URLs and more CSP-friendly.
+ *
+ * @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 module exports object
+    const exports: Record<string, unknown> = {}
+
+    // Transform ES6 export statements to assignments
+    // This is safe because we're only transforming the syntax pattern,
+    // not evaluating arbitrary code
+    const transformedJs = candidJs
+      // Replace 'export const name = value' with 'const name = value; exports.name = name'
+      .replace(/export\s+const\s+(\w+)\s*=/g, "const $1 =")
+      // Replace 'export function name' with 'function name'
+      .replace(/export\s+function\s+(\w+)/g, "function $1")
+
+    // Create a safe evaluation context with necessary globals
+    // We provide IDL from the trusted @icp-sdk/core/candid package
+    const evalFunction = new Function(
+      "exports",
+      "IDL",
+      `
+      ${transformedJs}
+      
+      // Capture exports
+      if (typeof idlFactory !== 'undefined') {
+        exports.idlFactory = idlFactory;
+      }
+      if (typeof init !== 'undefined') {
+        exports.init = init;
+      }
+      return exports;
+      `
+    )
+
+    // Execute the function with the exports object and IDL
+    const result = evalFunction(exports, IDL)
+
+    return {
+      idlFactory: result.idlFactory as CandidDefinition["idlFactory"],
+      init: result.init as CandidDefinition["init"],
+    }
+  } catch (error) {
+    throw new Error(`Failed to import Candid definition: ${error}`)
+  }
+}

package/src/visitor/arguments/helpers.ts

@@ -0,0 +1,153 @@
+import {
+  VisitorDataType,
+  CompoundField,
+  FieldNode,
+  FieldByType,
+  PrimitiveField,
+  RecordField,
+  TupleField,
+  VariantField,
+} from "./types"
+
+// ════════════════════════════════════════════════════════════════════════════
+// Type Guards
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Type guard for checking specific field types.
+ *
+ * @example
+ * ```tsx
+ * function FieldInput({ field }: { field: FieldNode }) {
+ *   if (isFieldType(field, 'record')) {
+ *     // field is now typed as RecordField
+ *     return <RecordInput field={field} />
+ *   }
+ *   if (isFieldType(field, 'text')) {
+ *     // field is now typed as TextField
+ *     return <TextInput field={field} />
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export function isFieldType<T extends VisitorDataType>(
+  field: FieldNode,
+  type: T
+): field is FieldByType<T> {
+  return field.type === type
+}
+
+/**
+ * Check if a field is a compound type (contains other fields).
+ * Compound types: record, variant, tuple, optional, vector, recursive
+ */
+export function isCompoundField(field: FieldNode): field is CompoundField {
+  return [
+    "record",
+    "variant",
+    "tuple",
+    "optional",
+    "vector",
+    "recursive",
+  ].includes(field.type)
+}
+
+/**
+ * Check if a field is a primitive type.
+ * Primitive types: principal, number, text, boolean, null
+ */
+export function isPrimitiveField(field: FieldNode): field is PrimitiveField {
+  return ["principal", "number", "text", "boolean", "null"].includes(field.type)
+}
+
+/**
+ * Check if a field has child fields array (for iteration).
+ * Applies to: record (fields), tuple (fields)
+ */
+export function hasChildFields(
+  field: FieldNode
+): field is RecordField | TupleField {
+  return (
+    (field.type === "record" || field.type === "tuple") &&
+    "fields" in field &&
+    Array.isArray((field as RecordField).fields)
+  )
+}
+
+/**
+ * Check if a field has variant options (for iteration).
+ * Applies to: variant (options)
+ */
+export function hasOptions(field: FieldNode): field is VariantField {
+  return (
+    field.type === "variant" &&
+    "options" in field &&
+    Array.isArray((field as VariantField).options)
+  )
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Label Formatting Utilities
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Format a raw Candid label into a human-readable display label.
+ * Handles common patterns like "__arg0", "_0_", "snake_case", etc.
+ *
+ * @example
+ * ```ts
+ * formatLabel("__arg0")        // "Arg 0"
+ * formatLabel("_0_")           // "Item 0"
+ * formatLabel("created_at")    // "Created At"
+ * formatLabel("userAddress")   // "User Address"
+ * formatLabel("__ret0")        // "Result 0"
+ * ```
+ */
+export function formatLabel(label: string): string {
+  // Handle argument labels: __arg0 -> Arg 0
+  if (label.startsWith("__arg")) {
+    const num = label.slice(5)
+    return `Arg ${num}`
+  }
+
+  // Handle return labels: __ret0 -> Result 0
+  if (label.startsWith("__ret")) {
+    const num = label.slice(5)
+    return `Result ${num}`
+  }
+
+  // Handle tuple index labels: _0_ -> Item 0
+  if (/^_\d+_$/.test(label)) {
+    const num = label.slice(1, -1)
+    return `Item ${num}`
+  }
+
+  // Handle simple index labels: _0 -> Item 0
+  if (/^_\d+$/.test(label)) {
+    const num = label.slice(1)
+    return `Item ${num}`
+  }
+
+  // Handle item labels for vectors: label_item -> Item
+  if (label.endsWith("_item")) {
+    return "Item"
+  }
+
+  // Convert snake_case or just clean up underscores
+  // and capitalize each word
+  const trimmed = (() => {
+    let start = 0
+    let end = label.length
+    while (start < end && label[start] === "_") start++
+    while (end > start && label[end - 1] === "_") end--
+    return label.slice(start, end)
+  })()
+
+  return trimmed
+    .replace(/_/g, " ") // Replace underscores with spaces
+    .replace(/([a-z])([A-Z])/g, "$1 $2") // Add space before capitals (camelCase)
+    .split(" ")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ")
+}