@ic-reactor/candid 3.0.14-beta.1 → 3.0.14-beta.2

package/dist/visitor/returns/types.d.ts

@@ -1,16 +1,21 @@
 import type { BaseActor, FunctionName, FunctionType, ActorMethodReturnType } from "@ic-reactor/core";
 import type { VisitorDataType, TextFormat, NumberFormat } from "../types";
-export type { TextFormat, NumberFormat };
-export type NodeType = VisitorDataType;
+export type { VisitorDataType, TextFormat, NumberFormat };
+/**
+ * The display type category after transformation.
+ * Maps Candid types to JavaScript-friendly display types.
+ */
 export type DisplayType = "string" | "number" | "boolean" | "null" | "object" | "array" | "variant" | "result" | "nullable" | "recursive" | "blob" | "unknown";
 /**
  * Base properties shared by all result nodes.
  */
-interface ResultNodeBase<T extends NodeType = NodeType> {
+interface ResultNodeBase<T extends VisitorDataType = VisitorDataType> {
     /** The Candid type category */
     type: T;
-    /** Human-readable label */
+    /** Raw label from Candid definition */
     label: string;
+    /** Human-readable formatted label for display */
+    displayLabel: string;
     /** Original Candid type name */
     candidType: string;
     /** What it becomes after display transformation */
@@ -20,10 +25,14 @@ interface ResultNodeBase<T extends NodeType = NodeType> {
     /** Value after display transformation (present after resolution) */
     value?: unknown;
 }
-type NodeTypeExtras<T extends NodeType> = T extends "record" ? {
+type NodeTypeExtras<T extends VisitorDataType> = T extends "record" ? {
     fields: Record<string, ResultNode>;
 } : T extends "variant" ? {
-    selectedOption: ResultNode;
+    /** All variant options as schema */
+    options: Record<string, ResultNode>;
+    /** The resolved selected option value */
+    selectedValue: ResultNode;
+    /** The selected option key (populated after resolution) */
     selected?: string;
 } : T extends "tuple" | "vector" ? {
     items: ResultNode[];
@@ -57,14 +66,14 @@ type NodeTypeExtras<T extends NodeType> = T extends "record" ? {
  * resolved children directly in their structure fields.
  * Primitive types store the display value in `value`.
  */
-export type ResultNode<T extends NodeType = NodeType> = ResultNodeBase<T> & NodeTypeExtras<T> & {
+export type ResultNode<T extends VisitorDataType = VisitorDataType> = ResultNodeBase<T> & NodeTypeExtras<T> & {
     /** Resolve this node with a value, returning a new resolved node */
     resolve(data: unknown): ResolvedNode<T>;
 };
 /**
  * A resolved node has `raw` populated and children resolved.
  */
-export type ResolvedNode<T extends NodeType = NodeType> = ResultNode<T> & {
+export type ResolvedNode<T extends VisitorDataType = VisitorDataType> = ResultNode<T> & {
     raw: unknown;
 };
 export type RecordNode = ResultNode<"record">;
@@ -80,23 +89,52 @@ export type TextNode = ResultNode<"text">;
 export type BooleanNode = ResultNode<"boolean">;
 export type NullNode = ResultNode<"null">;
 export type UnknownNode = ResultNode<"unknown">;
+/**
+ * Metadata for a single method's return values.
+ * Use this to render method results.
+ */
 export interface MethodMeta<A = BaseActor, Name extends FunctionName<A> = FunctionName<A>> {
+    /** Whether this is a "query" or "update" call */
     functionType: FunctionType;
+    /** The method name as defined in the Candid interface */
     functionName: Name;
+    /** Array of result node descriptors, one per return value */
     returns: ResultNode[];
+    /** Number of return values */
     returnCount: number;
     /**
      * Resolve the method result schema with actual return data.
+     * @param data The raw return data from the canister
+     * @returns A resolved result with display-friendly values
      */
-    resolve(data: ActorMethodReturnType<A[Name]>): ResolvedMethodResult<A>;
+    resolve(data: ActorMethodReturnType<A[Name]>): MethodResult<A>;
 }
-export interface ResolvedMethodResult<A = BaseActor> {
+/**
+ * A resolved method result with display-friendly values.
+ */
+export interface MethodResult<A = BaseActor> {
+    /** Whether this is a "query" or "update" call */
     functionType: FunctionType;
+    /** The method name */
     functionName: FunctionName<A>;
+    /** Resolved return values */
     results: ResolvedNode[];
+    /** Original raw data from the canister */
     raw: ActorMethodReturnType<A[FunctionName<A>]>;
 }
+/**
+ * Service-level metadata mapping method names to their return metadata.
+ */
 export type ServiceMeta<A = BaseActor> = {
     [K in FunctionName<A>]: MethodMeta<A, K>;
 };
+/**
+ * Props type for result display components.
+ */
+export type ResultDisplayProps<T extends VisitorDataType = VisitorDataType> = {
+    /** The resolved result node */
+    node: ResolvedNode<T>;
+    /** Nesting depth for indentation */
+    depth?: number;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/visitor/returns/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/visitor/returns/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/visitor/returns/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/candid",
-  "version": "3.0.14-beta.1",
+  "version": "3.0.14-beta.2",
   "description": "IC Reactor Candid Adapter - Fetch and parse Candid definitions from Internet Computer canisters",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@noble/hashes": "^2.0.1",
     "zod": "^4.3.5",
-    "@ic-reactor/core": "^3.0.14-beta.1"
+    "@ic-reactor/core": "^3.0.14-beta.2"
   },
   "peerDependencies": {
     "zod": "^4.3.5",

package/src/metadata-display-reactor.ts

@@ -12,10 +12,11 @@ import {
   FieldVisitor,
   ArgumentsMeta,
   ArgumentsServiceMeta,
+  MetadataError,
 } from "./visitor/arguments"
 import {
   MethodMeta,
-  ResolvedMethodResult,
+  MethodResult,
   ResultFieldVisitor,
   ServiceMeta,
 } from "./visitor/returns"
@@ -33,13 +34,39 @@ import {
  * It extends the base Reactor and adds metadata generation capabilities.
  * Unlike DisplayReactor, it does not use a separate codec for transformation.
  * Instead, it uses the metadata visitor to resolve raw values into display-ready structures.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const reactor = new MetadataDisplayReactor({
+ *   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+ *   clientManager,
+ *   name: "ICPLedger",
+ * })
+ *
+ * await reactor.initialize()
+ *
+ * // Get form metadata
+ * const argMeta = reactor.getInputMeta("icrc1_transfer")
+ * console.log(argMeta.args)     // Field descriptors
+ * console.log(argMeta.defaults) // Default values
+ *
+ * // Get result metadata
+ * const resultMeta = reactor.getOutputMeta("icrc1_transfer")
+ *
+ * // Call with display types
+ * const result = await reactor.callMethod({
+ *   functionName: "icrc1_transfer",
+ *   args: [{ to: { owner: "aaaaa-aa" }, amount: "1000000" }]
+ * })
+ * ```
  */
 declare module "@ic-reactor/core" {
   interface TransformArgsRegistry<T> {
     metadata: TransformArgsRegistry<T>["display"]
   }
   interface TransformReturnRegistry<T, A = BaseActor> {
-    metadata: ResolvedMethodResult<A>
+    metadata: MethodResult<A>
   }
 }
 
@@ -98,37 +125,44 @@ export class MetadataDisplayReactor<A = BaseActor> extends CandidDisplayReactor<
   // ══════════════════════════════════════════════════════════════════════════
   // METADATA ACCESS
   // ══════════════════════════════════════════════════════════════════════════
+
   /**
-   * Get argument field metadata for a method.
+   * Get input field metadata for a method.
    * Use this to generate input forms.
+   *
+   * @param methodName The method name to get metadata for
+   * @returns ArgumentsMeta containing args, defaults, and validation schema
    */
-  public getArgumentMeta<M extends FunctionName<A>>(
+  public getInputMeta<M extends FunctionName<A>>(
     methodName: M
   ): ArgumentsMeta<A, M> | undefined {
     return this.argumentMeta?.[methodName]
   }
 
   /**
-   * Get result field metadata for a method.
+   * Get output field metadata for a method.
    * Use this to render results.
+   *
+   * @param methodName The method name to get metadata for
+   * @returns MethodMeta containing return schema and resolve function
    */
-  public getResultMeta<M extends FunctionName<A>>(
+  public getOutputMeta<M extends FunctionName<A>>(
     methodName: M
   ): MethodMeta<A, M> | undefined {
     return this.resultMeta?.[methodName]
   }
 
   /**
-   * Get all argument metadata.
+   * Get all input metadata for all methods.
    */
-  public getAllArgumentMeta(): ArgumentsServiceMeta<A> | null {
+  public getAllInputMeta(): ArgumentsServiceMeta<A> | null {
     return this.argumentMeta
   }
 
   /**
-   * Get all result metadata.
+   * Get all output metadata for all methods.
    */
-  public getAllResultMeta(): ServiceMeta<A> | null {
+  public getAllOutputMeta(): ServiceMeta<A> | null {
     return this.resultMeta
   }
 
@@ -154,11 +188,15 @@ export class MetadataDisplayReactor<A = BaseActor> extends CandidDisplayReactor<
   protected override transformResult<M extends FunctionName<A>>(
     methodName: M,
     result: ActorMethodReturnType<A[M]>
-  ): ResolvedMethodResult<A> {
+  ): MethodResult<A> {
     // Get metadata and generate resolved result
-    const meta = this.getResultMeta(methodName)
+    const meta = this.getOutputMeta(methodName)
     if (!meta) {
-      throw new Error(`No metadata found for method "${methodName}"`)
+      throw new MetadataError(
+        `No output metadata found for method`,
+        String(methodName),
+        "method"
+      )
     }
 
     return meta.resolve(result)
@@ -166,6 +204,9 @@ export class MetadataDisplayReactor<A = BaseActor> extends CandidDisplayReactor<
 
   /**
    * Perform a dynamic call and return result with metadata.
+   *
+   * @param options Method registration and call options
+   * @returns Object containing the result and metadata
    */
   public async callDynamicWithMeta<T = unknown>(
     options: DynamicMethodOptions & { args?: unknown[] }
@@ -177,8 +218,39 @@ export class MetadataDisplayReactor<A = BaseActor> extends CandidDisplayReactor<
       args: options.args as any,
     })) as T
 
-    const meta = this.getResultMeta(options.functionName as any)!
+    const meta = this.getOutputMeta(options.functionName as any)!
 
     return { result, meta }
   }
 }
+
+// ════════════════════════════════════════════════════════════════════════════
+// Factory Function
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create and initialize a MetadataDisplayReactor.
+ * This is a convenience function that creates the reactor and calls initialize().
+ *
+ * @param options Reactor configuration options
+ * @returns Initialized MetadataDisplayReactor
+ *
+ * @example
+ * ```typescript
+ * const reactor = await createMetadataReactor({
+ *   canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+ *   clientManager,
+ *   name: "ICPLedger",
+ * })
+ *
+ * // Reactor is ready to use
+ * const methods = reactor.getMethodNames()
+ * ```
+ */
+export async function createMetadataReactor<A = BaseActor>(
+  options: CandidDisplayReactorParameters<A>
+): Promise<MetadataDisplayReactor<A>> {
+  const reactor = new MetadataDisplayReactor<A>(options)
+  await reactor.initialize()
+  return reactor
+}

package/src/visitor/arguments/helpers.ts

@@ -9,12 +9,16 @@ import {
   VariantField,
 } from "./types"
 
+// ════════════════════════════════════════════════════════════════════════════
+// Type Guards
+// ════════════════════════════════════════════════════════════════════════════
+
 /**
  * Type guard for checking specific field types.
  *
  * @example
  * ```tsx
- * function FieldInput({ field }: { field: Field }) {
+ * function FieldInput({ field }: { field: FieldNode }) {
  *   if (isFieldType(field, 'record')) {
  *     // field is now typed as RecordField
  *     return <RecordInput field={field} />
@@ -34,7 +38,10 @@ export function isFieldType<T extends VisitorDataType>(
   return field.type === type
 }
 
-/** Check if a field is a compound type (contains other fields) */
+/**
+ * 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",
@@ -46,16 +53,38 @@ export function isCompoundField(field: FieldNode): field is CompoundField {
   ].includes(field.type)
 }
 
-/** Check if a field is a primitive 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 children (for iteration) */
+/**
+ * Check if a field has child fields array (for iteration).
+ * Applies to: record (fields), tuple (fields)
+ */
 export function hasChildFields(
   field: FieldNode
-): field is RecordField | VariantField | TupleField {
-  return "fields" in field && Array.isArray((field as RecordField).fields)
+): 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)
+  )
 }
 
 // ════════════════════════════════════════════════════════════════════════════
@@ -72,6 +101,7 @@ export function hasChildFields(
  * formatLabel("_0_")           // "Item 0"
  * formatLabel("created_at")    // "Created At"
  * formatLabel("userAddress")   // "User Address"
+ * formatLabel("__ret0")        // "Result 0"
  * ```
  */
 export function formatLabel(label: string): string {
@@ -81,12 +111,24 @@ export function formatLabel(label: string): string {
     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"