@ic-reactor/core 3.0.3-beta.4 → 3.0.3

package/src/display-reactor.ts

@@ -0,0 +1,361 @@
+import { Reactor } from "./reactor"
+import {
+  didToDisplayCodec,
+  transformArgsWithCodec,
+  transformResultWithCodec,
+  didTypeFromArray,
+  ActorDisplayCodec,
+} from "./display"
+import {
+  ActorMethodParameters,
+  ActorMethodReturnType,
+  FunctionName,
+  ReactorArgs,
+  ReactorReturnOk,
+  ActorMethodCodecs,
+  BaseActor,
+  TransformKey,
+} from "./types/reactor"
+import { extractOkResult } from "./utils/helper"
+import { ValidationError } from "./errors"
+import {
+  DisplayReactorParameters,
+  DisplayValidator,
+  ValidationResult,
+  Validator,
+} from "./types/display-reactor"
+
+// ============================================================================
+// DisplayReactor
+// ============================================================================
+
+/**
+ * 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.
+ *
+ * @typeParam A - The actor service type
+ *
+ * @example
+ * ```typescript
+ * 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!
+ * })
+ * ```
+ */
+export class DisplayReactor<
+  A = BaseActor,
+  T extends TransformKey = "display",
+> extends Reactor<A, T> {
+  public readonly transform = "display" as T
+  private codecs: Map<
+    string,
+    { args: ActorDisplayCodec; result: ActorDisplayCodec }
+  > = new Map()
+  private validators: Map<string, Validator<any>> = new Map()
+
+  constructor(config: DisplayReactorParameters<A>) {
+    super(config)
+    this.initializeCodecs()
+
+    // Register initial validators if provided
+    if (config.validators) {
+      for (const [methodName, validator] of Object.entries(config.validators)) {
+        if (validator) {
+          this.validators.set(methodName, validator as Validator)
+        }
+      }
+    }
+  }
+
+  /**
+   * Initialize codecs from IDL factory for automatic type transformations
+   */
+  private initializeCodecs() {
+    try {
+      const fields = this.getServiceInterface()?._fields
+      if (!fields) {
+        throw new Error("No fields found")
+      }
+      for (const [methodName, funcType] of fields) {
+        // Generate args codec
+        const argsIdlType = didTypeFromArray(funcType.argTypes)
+        // Generate result codec
+        const retIdlType = didTypeFromArray(funcType.retTypes)
+        // Set codec in map
+        this.codecs.set(methodName, {
+          args: didToDisplayCodec(argsIdlType),
+          result: didToDisplayCodec(retIdlType),
+        })
+      }
+    } catch (error) {
+      console.error("Failed to initialize codecs:", error)
+    }
+  }
+
+  // ============================================================================
+  // Codec Methods
+  // ============================================================================
+
+  /**
+   * Get a codec for a specific method.
+   * Returns the args and result codecs for bidirectional transformation.
+   * @param methodName - The name of the method
+   * @returns Object with args and result codecs, or null if not found
+   */
+  public getCodec<M extends FunctionName<A>>(
+    methodName: M
+  ): ActorMethodCodecs<A, M> | null {
+    const cached = this.codecs.get(methodName)
+    if (cached) {
+      return cached as ActorMethodCodecs<A, M>
+    }
+
+    return null
+  }
+
+  // ============================================================================
+  // Validation Methods
+  // ============================================================================
+
+  /**
+   * Register a validator for a specific method.
+   * Validators receive display types (strings for Principal/bigint).
+   *
+   * @param methodName - The name of the method to validate
+   * @param validator - The validator function receiving display types
+   *
+   * @example
+   * ```typescript
+   * // 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 }
+   * })
+   * ```
+   */
+  registerValidator<M extends FunctionName<A>>(
+    methodName: M,
+    validator: DisplayValidator<A, M>
+  ): void {
+    this.validators.set(methodName, validator)
+  }
+
+  /**
+   * Unregister a validator for a specific method.
+   */
+  unregisterValidator<M extends FunctionName<A>>(methodName: M): void {
+    this.validators.delete(methodName)
+  }
+
+  /**
+   * Check if a method has a registered validator.
+   */
+  hasValidator<M extends FunctionName<A>>(methodName: M): boolean {
+    return this.validators.has(methodName)
+  }
+
+  /**
+   * Validate arguments without calling the canister.
+   * Arguments are in display format (strings for Principal/bigint).
+   * Useful for form validation before submission.
+   *
+   * @param methodName - The name of the method
+   * @param args - The display-type arguments to validate
+   * @returns ValidationResult indicating success or failure
+   *
+   * @example
+   * ```typescript
+   * // 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)
+   *   })
+   * }
+   * ```
+   */
+  async validate<M extends FunctionName<A>>(
+    methodName: M,
+    args: ReactorArgs<A, M, T>
+  ): Promise<ValidationResult> {
+    const validator = this.validators.get(methodName)
+    if (!validator) {
+      return { success: true }
+    }
+
+    return validator(args)
+  }
+
+  /**
+   * Call a method with async validation support.
+   * Use this instead of callMethod() when you have async validators.
+   *
+   * @example
+   * ```typescript
+   * // 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" }],
+   * })
+   * ```
+   */
+  async callMethodWithValidation<M extends FunctionName<A>>(params: {
+    functionName: M
+    args?: ReactorArgs<A, M, T>
+    callConfig?: Parameters<
+      Reactor<A, "display">["callMethod"]
+    >[0]["callConfig"]
+  }): Promise<ReactorReturnOk<A, M, T>> {
+    // Run async validation first (on display types)
+    if (params.args) {
+      const result = await this.validate(params.functionName, params.args)
+      if (!result.success) {
+        throw new ValidationError(String(params.functionName), result.issues)
+      }
+    }
+
+    // Skip synchronous validation in transformArgs by temporarily removing validator
+    const validator = this.validators.get(params.functionName)
+    if (validator) {
+      this.validators.delete(params.functionName)
+    }
+
+    try {
+      // @ts-ignore
+      return await this.callMethod(params)
+    } finally {
+      // Restore validator
+      if (validator) {
+        this.validators.set(params.functionName, validator)
+      }
+    }
+  }
+
+  // ============================================================================
+  // Transform Methods
+  // ============================================================================
+
+  /**
+   * Transform arguments before calling the actor method.
+   * 1. Validates display-type args (if validator registered)
+   * 2. Converts Display → Candid
+   */
+  protected transformArgs<M extends FunctionName<A>>(
+    methodName: M,
+    args?: ReactorArgs<A, M, T>
+  ): ActorMethodParameters<A[M]> {
+    // 1. Validate FIRST (on display types)
+    const validator = this.validators.get(methodName)
+    const displayArgs = args as unknown as ReactorArgs<A, M, "display">
+
+    if (validator && displayArgs) {
+      const result = validator(displayArgs)
+
+      // Handle Promise (async validator)
+      if (
+        result &&
+        typeof (result as Promise<ValidationResult>).then === "function"
+      ) {
+        throw new Error(
+          `Async validators are not supported in callMethod(). ` +
+            `Use reactor.callMethodWithValidation() for async validation.`
+        )
+      }
+
+      const syncResult = result as ValidationResult
+      if (!syncResult.success) {
+        throw new ValidationError(String(methodName), syncResult.issues)
+      }
+    }
+
+    // 2. THEN transform: Display → Candid
+    if (this.codecs.has(methodName)) {
+      const codec = this.codecs.get(methodName)!
+      return transformArgsWithCodec<ActorMethodParameters<A[M]>>(
+        codec.args,
+        displayArgs
+      )
+    }
+    if (!args) {
+      return [] as unknown as ActorMethodParameters<A[M]>
+    }
+    return args as ActorMethodParameters<A[M]>
+  }
+
+  /**
+   * Transform the result after calling the actor method.
+   * Always extracts the Ok value from Result types (throws CanisterError on Err).
+   * Also converts Candid → Display format.
+   */
+  protected transformResult<M extends FunctionName<A>>(
+    methodName: M,
+    result: ActorMethodReturnType<A[M]>
+  ): ReactorReturnOk<A, M, T> {
+    let transformedResult = result
+    // 1. Apply display transformation to the FULL result
+    if (this.codecs.has(methodName)) {
+      const codec = this.codecs.get(methodName)!
+      transformedResult = transformResultWithCodec(codec.result, result)
+    }
+
+    // 2. Extract Ok value from the TRANSFORMED (or raw) result
+    //    This handles { ok: T } / { err: E } from Motoko/Rust canisters
+    return extractOkResult(transformedResult) as unknown as ReactorReturnOk<
+      A,
+      M,
+      T
+    >
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,246 @@
+import { NullishType } from "../display/types"
+
+/**
+ * Interface representing the generic shape of an API error.
+ */
+export interface ApiError {
+  code: string
+  message: NullishType<string>
+  details: NullishType<Map<string, string>>
+}
+
+/**
+ * Error thrown when there's an issue calling the canister.
+ * This includes network errors, agent errors, canister not found, etc.
+ */
+export class CallError extends Error {
+  public readonly cause?: unknown
+
+  constructor(message: string, cause?: unknown) {
+    super(message)
+    this.name = "CallError"
+    this.cause = cause
+
+    // Maintains proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CallError)
+    }
+  }
+}
+
+/**
+ * Error thrown when the canister returns an Err result.
+ * The `err` property contains the typed error value from the canister.
+ *
+ * It also supports accessing `code`, `message`, and `details` directly
+ * if the error object follows the common API error format or is a variant.
+ *
+ * @typeParam E - The type of the error value from the canister
+ */
+export class CanisterError<E = unknown> extends Error {
+  /** The raw error value from the canister */
+  public readonly err: E
+  /** The error code, extracted from the error object or variant key */
+  public readonly code: string
+  /** Optional error details Map */
+  public readonly details: NullishType<Map<string, string>>
+
+  constructor(err: E) {
+    let code: string | undefined
+    let message: string | undefined
+    let details: NullishType<Map<string, string>> = undefined
+    let isApiShape = false
+
+    if (typeof err === "object" && err !== null) {
+      // 1. Check for structured ApiError shape (has code)
+      if ("code" in err && typeof err.code === "string") {
+        code = err.code
+        isApiShape = true
+        if ("message" in err && typeof err.message === "string") {
+          message = err.message
+        }
+        if ("details" in err) {
+          details = err.details as any
+        }
+      }
+      // 2. Check for ic-reactor transformed variant shape (_type)
+      else if ("_type" in err && typeof err._type === "string") {
+        code = err._type
+      }
+      // 3. Simple variant check (single key object)
+      else {
+        const keys = Object.keys(err)
+        if (keys.length === 1) {
+          code = keys[0]
+        }
+      }
+    }
+
+    const finalCode = code ?? "UNKNOWN_ERROR"
+    const finalMessage =
+      message ??
+      (typeof err === "object" && err !== null
+        ? JSON.stringify(
+            err,
+            (_, v) => (typeof v === "bigint" ? v.toString() : v),
+            2
+          )
+        : String(err))
+
+    super(isApiShape ? finalMessage : `Canister Error: ${finalMessage}`)
+    this.name = "CanisterError"
+    this.err = err
+    this.code = finalCode
+    this.details = details
+
+    // Maintains proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CanisterError)
+    }
+  }
+
+  /**
+   * Type guard to check if an error object follows the API error format.
+   */
+  static isApiError(error: unknown): error is ApiError {
+    if (typeof error !== "object" || error === null) {
+      return false
+    }
+
+    return "code" in error && "message" in error && "details" in error
+  }
+
+  /**
+   * Factory method to create a CanisterError from any error.
+   * If the input is already a CanisterError, it returns it.
+   * If it's an API error shape, it wraps it.
+   * Otherwise, it creates a new CanisterError with an "UNKNOWN_ERROR" code.
+   */
+  static create(error: unknown, message?: string): CanisterError {
+    if (error instanceof CanisterError) {
+      return error
+    }
+
+    if (CanisterError.isApiError(error)) {
+      return new CanisterError(error)
+    }
+
+    return new CanisterError({
+      code: "UNKNOWN_ERROR",
+      message:
+        error instanceof Error
+          ? error.message
+          : message || "An unknown error occurred",
+      details: undefined,
+    } as any)
+  }
+}
+
+/**
+ * Type guard to check if an error is a CanisterError.
+ * Preserves the generic type E from the input when used in type narrowing.
+ *
+ * @example
+ * ```typescript
+ * // err is typed as CanisterError<TransferError> | CallError
+ * if (isCanisterError(err)) {
+ *   // err.err is typed as TransferError (preserved!)
+ *   console.log(err.err)
+ * }
+ * ```
+ */
+export function isCanisterError<E>(
+  error: CanisterError<E> | CallError
+): error is CanisterError<E>
+export function isCanisterError(error: unknown): error is CanisterError<unknown>
+export function isCanisterError(
+  error: unknown
+): error is CanisterError<unknown> {
+  return error instanceof CanisterError
+}
+
+/**
+ * Type guard to check if an error is a CallError
+ */
+export function isCallError(error: unknown): error is CallError {
+  return error instanceof CallError
+}
+
+// ============================================================================
+// Validation Errors
+// ============================================================================
+
+/**
+ * Represents a single validation issue
+ */
+export interface ValidationIssue {
+  /** Path to the invalid field (e.g., ["to", "amount"]) */
+  path: (string | number)[]
+  /** Human-readable error message */
+  message: string
+  /** Validation code (e.g., "required", "min_length") */
+  code?: string
+}
+
+/**
+ * Error thrown when argument validation fails before calling the canister.
+ * Contains detailed information about which fields failed validation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await reactor.callMethod({
+ *     functionName: "transfer",
+ *     args: [{ to: "", amount: -100 }],
+ *   })
+ * } catch (error) {
+ *   if (isValidationError(error)) {
+ *     console.log(error.issues)
+ *     // [
+ *     //   { path: ["to"], message: "Recipient is required" },
+ *     //   { path: ["amount"], message: "Amount must be positive" }
+ *     // ]
+ *   }
+ * }
+ * ```
+ */
+export class ValidationError extends Error {
+  /** Array of validation issues */
+  public readonly issues: ValidationIssue[]
+  /** The method name that failed validation */
+  public readonly methodName: string
+
+  constructor(methodName: string, issues: ValidationIssue[]) {
+    const messages = issues.map((i) => i.message).join(", ")
+    super(`Validation failed for "${methodName}": ${messages}`)
+    this.name = "ValidationError"
+    this.methodName = methodName
+    this.issues = issues
+
+    // Maintains proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError)
+    }
+  }
+
+  /**
+   * Get issues for a specific field path
+   */
+  getIssuesForPath(path: string): ValidationIssue[] {
+    return this.issues.filter((issue) => issue.path.includes(path))
+  }
+
+  /**
+   * Check if a specific field has errors
+   */
+  hasErrorForPath(path: string): boolean {
+    return this.issues.some((issue) => issue.path.includes(path))
+  }
+}
+
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./reactor"
+export * from "./client"
+export * from "./utils"
+export * from "./display"
+export * from "./display-reactor"
+export * from "./types"
+export * from "./errors"
+export * from "./version"