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

package/src/visitor/returns/index.ts

@@ -1,12 +1,14 @@
 import { isQuery } from "../helpers"
 import { checkTextFormat, checkNumberFormat } from "../constants"
+import { formatLabel } from "../arguments/helpers"
+import { MetadataError } from "../arguments/types"
 import type {
   ResultNode,
   ResolvedNode,
-  NodeType,
+  VisitorDataType,
   MethodMeta,
   ServiceMeta,
-  ResolvedMethodResult,
+  MethodResult,
   NumberFormat,
   TextFormat,
 } from "./types"
@@ -32,7 +34,7 @@ type Codec = { decode: (v: unknown) => unknown }
 /**
  * Creates a primitive node with automatic resolve implementation.
  */
-function primitiveNode<T extends NodeType>(
+function primitiveNode<T extends VisitorDataType>(
   type: T,
   label: string,
   candidType: string,
@@ -43,6 +45,7 @@ function primitiveNode<T extends NodeType>(
   const node: ResultNode<T> = {
     type,
     label,
+    displayLabel: formatLabel(label),
     candidType,
     displayType,
     ...extras,
@@ -54,8 +57,10 @@ function primitiveNode<T extends NodeType>(
           raw: data,
         } as unknown as ResolvedNode<T>
       } catch (e) {
-        throw new Error(
-          `Failed to decode field "${label}" of type ${type} (${candidType}) with data: ${JSON.stringify(data)}. Error: ${e}`
+        throw new MetadataError(
+          `Failed to decode: ${e instanceof Error ? e.message : String(e)}`,
+          label,
+          candidType
         )
       }
     },
@@ -116,7 +121,7 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
       returnCount: t.retTypes.length,
       resolve: (
         data: ActorMethodReturnType<A[FunctionName<A>]>
-      ): ResolvedMethodResult<A> => {
+      ): MethodResult<A> => {
         const dataArray = returns.length <= 1 ? [data] : (data as unknown[])
         return {
           functionType,
@@ -145,12 +150,17 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     const node: ResultNode<"record"> = {
       type: "record",
       label,
+      displayLabel: formatLabel(label),
       candidType: "record",
       displayType: "object",
       fields,
       resolve(data: unknown): ResolvedNode<"record"> {
         if (data === null || data === undefined) {
-          throw new Error(`Expected record for field ${label}, but got ${data}`)
+          throw new MetadataError(
+            `Expected record, but got ${data === null ? "null" : "undefined"}`,
+            label,
+            "record"
+          )
         }
         const recordData = data as Record<string, unknown>
         const resolvedFields: Record<string, ResolvedNode> = {}
@@ -161,8 +171,10 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
             recordData[key] !== undefined ? recordData[key] : recordData[index]
 
           if (!field || typeof field.resolve !== "function") {
-            throw new Error(
-              `Field "${key}" in record "${label}" is not a valid ResultNode. Got: ${JSON.stringify(field)}`
+            throw new MetadataError(
+              `Field "${key}" is not a valid ResultNode`,
+              `${label}.${key}`,
+              "record"
             )
           }
 
@@ -180,38 +192,44 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     fields_: Array<[string, IDL.Type]>,
     label: string
   ): ResultNode<"variant"> {
-    const selectedOption: Record<string, ResultNode> = {}
+    const options: Record<string, ResultNode> = {}
     for (const [key, type] of fields_) {
-      selectedOption[key] = type.accept(this, key) as ResultNode
+      options[key] = type.accept(this, key) as ResultNode
     }
-    const isResult = "Ok" in selectedOption && "Err" in selectedOption
+    const isResult = "Ok" in options && "Err" in options
     const node: ResultNode<"variant"> = {
       type: "variant",
       label,
+      displayLabel: formatLabel(label),
       candidType: "variant",
       displayType: isResult ? "result" : "variant",
-      selectedOption: {} as ResultNode, // placeholder, populated on resolve
+      options,
+      selectedValue: {} as ResultNode, // placeholder, populated on resolve
       resolve(data: unknown): ResolvedNode<"variant"> {
         if (data === null || data === undefined) {
-          throw new Error(
-            `Expected variant for field ${label}, but got ${data}`
+          throw new MetadataError(
+            `Expected variant, but got ${data === null ? "null" : "undefined"}`,
+            label,
+            "variant"
           )
         }
         const variantData = data as Record<string, unknown>
         // Support both raw { Selected: value } and transformed { _type: 'Selected', Selected: value }
         const selected =
           (variantData._type as string) || Object.keys(variantData)[0]
-        const optionNode = selectedOption[selected]
+        const optionNode = options[selected]
 
         if (!optionNode) {
-          throw new Error(
-            `Option ${selected} not found in variant ${label}. Available options: ${Object.keys(selectedOption).join(", ")}`
+          throw new MetadataError(
+            `Option "${selected}" not found. Available: ${Object.keys(options).join(", ")}`,
+            label,
+            "variant"
           )
         }
         return {
           ...node,
           selected,
-          selectedOption: optionNode.resolve(variantData[selected]),
+          selectedValue: optionNode.resolve(variantData[selected]),
           raw: data,
         }
       },
@@ -231,12 +249,17 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     const node: ResultNode<"tuple"> = {
       type: "tuple",
       label,
+      displayLabel: formatLabel(label),
       candidType: "tuple",
       displayType: "array",
       items,
       resolve(data: unknown): ResolvedNode<"tuple"> {
         if (data === null || data === undefined) {
-          throw new Error(`Expected tuple for field ${label}, but got ${data}`)
+          throw new MetadataError(
+            `Expected tuple, but got ${data === null ? "null" : "undefined"}`,
+            label,
+            "tuple"
+          )
         }
         const tupleData = data as unknown[]
         return {
@@ -259,6 +282,7 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     const node: ResultNode<"optional"> = {
       type: "optional",
       label,
+      displayLabel: formatLabel(label),
       candidType: "opt",
       displayType: "nullable",
       value: null, // null until resolved
@@ -290,6 +314,7 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
       const node: ResultNode<"blob"> = {
         type: "blob",
         label,
+        displayLabel: formatLabel(label),
         candidType: "blob",
         displayType: "string",
         length: 0,
@@ -321,12 +346,17 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     const node: ResultNode<"vector"> = {
       type: "vector",
       label,
+      displayLabel: formatLabel(label),
       candidType: "vec",
       displayType: "array",
       items: [], // empty schema placeholder, populated on resolve
       resolve(data: unknown): ResolvedNode<"vector"> {
         if (data === null || data === undefined) {
-          throw new Error(`Expected vector for field ${label}, but got ${data}`)
+          throw new MetadataError(
+            `Expected vector, but got ${data === null ? "null" : "undefined"}`,
+            label,
+            "vec"
+          )
         }
         const vectorData = data as unknown[]
         return {
@@ -357,6 +387,7 @@ export class ResultFieldVisitor<A = BaseActor> extends IDL.Visitor<
     const node: ResultNode<"recursive"> = {
       type: "recursive",
       label,
+      displayLabel: formatLabel(label),
       candidType: "rec",
       displayType: "recursive",
       inner: {} as ResultNode, // placeholder, populated on resolve

package/src/visitor/returns/types.ts

@@ -6,14 +6,16 @@ import type {
 } from "@ic-reactor/core"
 import type { VisitorDataType, TextFormat, NumberFormat } from "../types"
 
-export type { TextFormat, NumberFormat }
+export type { VisitorDataType, TextFormat, NumberFormat }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Core Types & Formats
 // ════════════════════════════════════════════════════════════════════════════
 
-export type NodeType = VisitorDataType
-
+/**
+ * The display type category after transformation.
+ * Maps Candid types to JavaScript-friendly display types.
+ */
 export type DisplayType =
   | "string"
   | "number"
@@ -35,11 +37,13 @@ export type DisplayType =
 /**
  * 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 */
@@ -55,27 +59,112 @@ interface ResultNodeBase<T extends NodeType = NodeType> {
 // For compound types, children are stored directly in their respective fields
 // ════════════════════════════════════════════════════════════════════════════
 
-type NodeTypeExtras<T extends NodeType> = T extends "record"
-  ? { fields: Record<string, ResultNode> }
+interface RecordNodeExtras {
+  /** Child fields of the record */
+  fields: Record<string, ResultNode>
+}
+
+interface VariantNodeExtras {
+  /** 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
+}
+
+interface TupleNodeExtras {
+  /** Tuple element fields */
+  items: ResultNode[]
+}
+
+interface VectorNodeExtras {
+  /** Vector element fields */
+  items: ResultNode[]
+}
+
+interface OptionalNodeExtras {
+  /** The inner value, or null if not enabled */
+  value: ResultNode | null
+}
+
+interface RecursiveNodeExtras {
+  /** The resolved recursive inner type */
+  inner: ResultNode
+}
+
+interface BlobNodeExtras {
+  /** The blob value as hex/base64 or Uint8Array */
+  value: string | Uint8Array
+  /** Hash of the blob content */
+  hash: string
+  /** Length in bytes */
+  length: number
+}
+
+interface NumberNodeExtras {
+  /** Detected number format */
+  format: NumberFormat
+  /** The numeric value */
+  value: string | number
+}
+
+interface TextNodeExtras {
+  /** Detected text format */
+  format: TextFormat
+  /** The text value */
+  value: string
+}
+
+interface PrincipalNodeExtras {
+  /** Detected text format */
+  format: TextFormat
+  /** The principal value as string */
+  value: string
+}
+
+interface BooleanNodeExtras {
+  /** The boolean value */
+  value: boolean
+}
+
+interface NullNodeExtras {
+  /** The null value */
+  value: null
+}
+
+interface UnknownNodeExtras {
+  /** The unknown value */
+  value: unknown
+}
+
+type NodeTypeExtras<T extends VisitorDataType> = T extends "record"
+  ? RecordNodeExtras
   : T extends "variant"
-    ? { selectedOption: ResultNode; selected?: string }
-    : T extends "tuple" | "vector"
-      ? { items: ResultNode[] }
-      : T extends "optional"
-        ? { value: ResultNode | null }
-        : T extends "recursive"
-          ? { inner: ResultNode }
-          : T extends "blob"
-            ? { value: string | Uint8Array; hash: string; length: number }
-            : T extends "number"
-              ? { format: NumberFormat; value: string | number }
-              : T extends "text" | "principal"
-                ? { format: TextFormat; value: string }
-                : T extends "boolean"
-                  ? { value: boolean }
-                  : T extends "null"
-                    ? { value: null }
-                    : { value: unknown } // unknown
+    ? VariantNodeExtras
+    : T extends "tuple"
+      ? TupleNodeExtras
+      : T extends "vector"
+        ? VectorNodeExtras
+        : T extends "optional"
+          ? OptionalNodeExtras
+          : T extends "recursive"
+            ? RecursiveNodeExtras
+            : T extends "blob"
+              ? BlobNodeExtras
+              : T extends "number"
+                ? NumberNodeExtras
+                : T extends "text"
+                  ? TextNodeExtras
+                  : T extends "principal"
+                    ? PrincipalNodeExtras
+                    : T extends "boolean"
+                      ? BooleanNodeExtras
+                      : T extends "null"
+                        ? NullNodeExtras
+                        : T extends "unknown"
+                          ? UnknownNodeExtras
+                          : {}
 
 /**
  * A unified result node that contains both schema and resolved value.
@@ -86,18 +175,20 @@ 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> & {
-    /** Resolve this node with a value, returning a new resolved node */
-    resolve(data: unknown): ResolvedNode<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> & {
-  raw: unknown
-}
+export type ResolvedNode<T extends VisitorDataType = VisitorDataType> =
+  ResultNode<T> & {
+    raw: unknown
+  }
 
 // ════════════════════════════════════════════════════════════════════════════
 // Convenience Type Aliases
@@ -121,27 +212,57 @@ export type UnknownNode = ResultNode<"unknown">
 // Method & Service Level
 // ════════════════════════════════════════════════════════════════════════════
 
+/**
+ * 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
+}