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

package/src/visitor/returns/index.test.ts

@@ -58,7 +58,7 @@ describe("ResultFieldVisitor", () => {
       const ethField = visitor.visitText(IDL.Text, "ethereum_address")
       expect(ethField.format).toBe("eth")
 
-      const accountIdField = visitor.visitText(IDL.Text, "account_id")
+      const accountIdField = visitor.visitText(IDL.Text, "account_identifier")
       expect(accountIdField.format).toBe("account-id")
 
       const principalField = visitor.visitText(IDL.Text, "canister_id")
@@ -347,7 +347,7 @@ describe("ResultFieldVisitor", () => {
       // Validate options by resolving each option
       const resolvedActive = field.resolve({ Active: null })
       expect(resolvedActive.selected).toBe("Active")
-      expect(resolvedActive.selectedOption.type).toBe("null")
+      expect(resolvedActive.selectedValue.type).toBe("null")
       const resolvedInactive = field.resolve({ Inactive: null })
       expect(resolvedInactive.selected).toBe("Inactive")
       const resolvedPending = field.resolve({ Pending: null })
@@ -396,14 +396,14 @@ describe("ResultFieldVisitor", () => {
         Transfer: { from: "aaaaa-aa", to: "bbbbb-bb", amount: BigInt(1) },
       })
       expect(transferResolved.selected).toBe("Transfer")
-      expect(transferResolved.selectedOption.type).toBe("record")
+      expect(transferResolved.selectedValue.type).toBe("record")
       expect(
-        Object.keys((transferResolved.selectedOption as RecordNode).fields)
+        Object.keys((transferResolved.selectedValue as RecordNode).fields)
       ).toHaveLength(3)
 
       const approveResolved = field.resolve({ Approve: BigInt(5) })
       expect(approveResolved.selected).toBe("Approve")
-      expect(approveResolved.selectedOption.type).toBe("number")
+      expect(approveResolved.selectedValue.type).toBe("number")
     })
 
     it("should detect Result variant (Ok/Err)", () => {
@@ -425,13 +425,13 @@ describe("ResultFieldVisitor", () => {
 
       const okResolved = field.resolve({ Ok: BigInt(1) })
       expect(okResolved.selected).toBe("Ok")
-      expect(okResolved.selectedOption.type).toBe("number")
-      expect(okResolved.selectedOption.displayType).toBe("string")
+      expect(okResolved.selectedValue.type).toBe("number")
+      expect(okResolved.selectedValue.displayType).toBe("string")
 
       const errResolved = field.resolve({ Err: "error" })
       expect(errResolved.selected).toBe("Err")
-      expect(errResolved.selectedOption.type).toBe("text")
-      expect(errResolved.selectedOption.displayType).toBe("string")
+      expect(errResolved.selectedValue.type).toBe("text")
+      expect(errResolved.selectedValue.displayType).toBe("string")
     })
 
     it("should detect complex Result variant", () => {
@@ -474,11 +474,11 @@ describe("ResultFieldVisitor", () => {
         Ok: { id: BigInt(1), data: new Uint8Array([1, 2, 3]) },
       })
       expect(okResolved.selected).toBe("Ok")
-      expect(okResolved.selectedOption.type).toBe("record")
+      expect(okResolved.selectedValue.type).toBe("record")
 
       const errResolved = field.resolve({ Err: { NotFound: null } })
       expect(errResolved.selected).toBe("Err")
-      expect(errResolved.selectedOption.type).toBe("variant")
+      expect(errResolved.selectedValue.type).toBe("variant")
     })
 
     it("should not detect non-Result variant with Ok and other options", () => {
@@ -944,18 +944,18 @@ describe("ResultFieldVisitor", () => {
       expect(field.displayType).toBe("result")
 
       const okResolved = field.resolve({ Ok: BigInt(123) })
-      if ((okResolved.selectedOption as ResolvedNode).type !== "number") {
+      if ((okResolved.selectedValue as ResolvedNode).type !== "number") {
         throw new Error("Ok field is not number")
       }
-      expect((okResolved.selectedOption as ResolvedNode).candidType).toBe("nat")
-      expect((okResolved.selectedOption as ResolvedNode).displayType).toBe(
+      expect((okResolved.selectedValue as ResolvedNode).candidType).toBe("nat")
+      expect((okResolved.selectedValue as ResolvedNode).displayType).toBe(
         "string"
       )
 
       const errResolved = field.resolve({
         Err: { InsufficientFunds: { balance: BigInt(0) } },
       })
-      const innerErr = errResolved.selectedOption as ResolvedNode
+      const innerErr = errResolved.selectedValue as ResolvedNode
       expect(innerErr.type).toBe("variant")
       const insufficient = (innerErr as any).resolve({
         InsufficientFunds: { balance: BigInt(0) },
@@ -1269,7 +1269,7 @@ describe("ResultFieldVisitor", () => {
         )
 
         expect(() => field.resolve(null)).toThrow(
-          "Expected record for field user, but got null"
+          "Expected record, but got null"
         )
       })
     })
@@ -1292,7 +1292,7 @@ describe("ResultFieldVisitor", () => {
         const resolved = field.resolve({ Ok: "Success" })
         expect(resolved.type).toBe(field.type)
         expect(resolved.selected).toBe("Ok")
-        const data = resolved.selectedOption as ResolvedNode
+        const data = resolved.selectedValue as ResolvedNode
         expect(data.value).toBe("Success")
       })
 
@@ -1313,7 +1313,7 @@ describe("ResultFieldVisitor", () => {
         const resolved = field.resolve({ Err: "Something went wrong" })
 
         expect(resolved.selected).toBe("Err")
-        const data = resolved.selectedOption as ResolvedNode
+        const data = resolved.selectedValue as ResolvedNode
         expect(data.value).toBe("Something went wrong")
       })
 
@@ -1329,7 +1329,7 @@ describe("ResultFieldVisitor", () => {
         )
 
         expect(() => field.resolve(null)).toThrow(
-          "Expected variant for field choice, but got null"
+          "Expected variant, but got null"
         )
       })
     })
@@ -1358,7 +1358,7 @@ describe("ResultFieldVisitor", () => {
         const field = visitor.visitTuple(tupleType, [IDL.Text, IDL.Nat], "pair")
 
         expect(() => field.resolve(null)).toThrow(
-          "Expected tuple for field pair, but got null"
+          "Expected tuple, but got null"
         )
       })
     })
@@ -1416,7 +1416,7 @@ describe("ResultFieldVisitor", () => {
         const field = visitor.visitVec(vecType, IDL.Text, "items")
 
         expect(() => field.resolve(null)).toThrow(
-          "Expected vector for field items, but got null"
+          "Expected vector, but got null"
         )
       })
     })
@@ -1612,7 +1612,7 @@ describe("ResultFieldVisitor", () => {
 
       const okValue = okResult.results[0] as ResolvedNode
       expect((okValue as any).selected).toBe("Ok")
-      expect(((okValue as any).selectedOption as ResolvedNode).value).toBe(
+      expect(((okValue as any).selectedValue as ResolvedNode).value).toBe(
         "12345"
       )
 
@@ -1622,7 +1622,7 @@ describe("ResultFieldVisitor", () => {
       })
       const errValue = errResult.results[0] as ResolvedNode
       expect((errValue as any).selected).toBe("Err")
-      expect(((errValue as any).selectedOption as ResolvedNode).value).toBe(
+      expect(((errValue as any).selectedValue as ResolvedNode).value).toBe(
         "Insufficient funds"
       )
     })
@@ -1727,7 +1727,7 @@ describe("ResultFieldVisitor", () => {
 
       const successValue = successResult.results[0] as ResolvedNode
       expect((successValue as any).selected).toBe("Ok")
-      expect(((successValue as any).selectedOption as ResolvedNode).value).toBe(
+      expect(((successValue as any).selectedValue as ResolvedNode).value).toBe(
         "1000"
       )
 
@@ -1738,7 +1738,7 @@ describe("ResultFieldVisitor", () => {
       const errorValue = errorResult.results[0] as ResolvedNode
       expect((errorValue as any).selected).toBe("Err")
 
-      const val = (errorValue as any).selectedOption as ResolvedNode
+      const val = (errorValue as any).selectedValue as ResolvedNode
       if (typeof val !== "object" || val === null || !("selected" in val)) {
         throw new Error("Expected variant value object")
       }
@@ -1876,7 +1876,7 @@ describe("ResultFieldVisitor", () => {
 
       const variantValue = result.results[0] as ResolvedNode
       expect((variantValue as any).selected).toBe("Ok")
-      const innerVal = (variantValue as any).selectedOption as ResolvedNode
+      const innerVal = (variantValue as any).selectedValue as ResolvedNode
       expect(innerVal.value).toBe("12345")
     })
 
@@ -2042,7 +2042,7 @@ describe("ResultFieldVisitor Reproduction - User reported issue", () => {
     const resolved = field.resolve(transformedData)
 
     expect(resolved.selected).toBe("Quorum")
-    expect(resolved.selectedOption.value).toBe("some text")
+    expect(resolved.selectedValue.value).toBe("some text")
   })
 
   it("should handle already transformed optional data (unwrapped)", () => {
@@ -2071,7 +2071,7 @@ describe("ResultFieldVisitor Reproduction - User reported issue", () => {
     )
 
     expect(() => field.resolve({ C: null })).toThrow(
-      /Option C not found in variant MyVariant. Available options: A, B/
+      /Option "C" not found. Available: A, B/
     )
   })
 
@@ -2101,7 +2101,7 @@ describe("ResultFieldVisitor Reproduction - User reported issue", () => {
       const variantNode = resolved.inner as VariantNode
 
       expect(variantNode.selected).toBe("Quorum")
-      expect(variantNode.selectedOption.type).toBe("record")
+      expect(variantNode.selectedValue.type).toBe("record")
     })
 
     it("should handle deeply nested recursive variant with transformed data", () => {
@@ -2130,7 +2130,7 @@ describe("ResultFieldVisitor Reproduction - User reported issue", () => {
       const variantNode = resolved.inner as VariantNode
       expect(variantNode.selected).toBe("Nested")
 
-      const nestedResolved = variantNode.selectedOption as RecursiveNode
+      const nestedResolved = variantNode.selectedValue as RecursiveNode
       const innerVariant = nestedResolved.inner as VariantNode
       expect(innerVariant.selected).toBe("Quorum")
     })

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,10 +59,17 @@ 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"
+type NodeTypeExtras<T extends VisitorDataType> = T extends "record"
   ? { fields: Record<string, ResultNode> }
   : T extends "variant"
-    ? { selectedOption: ResultNode; selected?: string }
+    ? {
+        /** 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[] }
       : T extends "optional"
@@ -86,18 +97,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 +134,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
+}