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

package/src/visitor/arguments/types.ts

@@ -4,12 +4,32 @@ import type { VisitorDataType, TextFormat, NumberFormat } from "../types"
 
 export type { VisitorDataType, TextFormat, NumberFormat }
 
+// ════════════════════════════════════════════════════════════════════════════
+// Custom Error Class
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Custom error class for metadata-related errors.
+ * Provides additional context about the field path and Candid type.
+ */
+export class MetadataError extends Error {
+  constructor(
+    message: string,
+    public readonly fieldPath?: string,
+    public readonly candidType?: string
+  ) {
+    super(message)
+    this.name = "MetadataError"
+  }
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // Component & UI Types
 // ════════════════════════════════════════════════════════════════════════════
 
 /**
  * Suggested component type for rendering the field.
+ * Use this to map field types to your UI components.
  */
 export type FieldComponentType =
   | "record-container"
@@ -68,121 +88,187 @@ export interface PrimitiveInputProps {
 // Base Field Interface
 // ════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Base properties shared by all field nodes.
+ */
 interface FieldBase<T extends VisitorDataType = VisitorDataType> {
+  /** The Candid type category (record, variant, text, number, etc.) */
   type: T
+  /** Raw label from Candid definition */
   label: string
+  /** Human-readable formatted label for display */
   displayLabel: string
+  /** Form path compatible with TanStack Form (e.g., "[0]", "[0].owner") */
   name: string
+  /** Suggested component type for rendering */
   component: FieldComponentType
+  /** UI rendering hints */
   renderHint: RenderHint
+  /** Zod validation schema */
   schema: z.ZodTypeAny
+  /** Original Candid type name */
   candidType: string
+  /** Default value for form initialization */
   defaultValue: unknown
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Field Extras
+// Field Extras - Type-Specific Properties
 // ════════════════════════════════════════════════════════════════════════════
 
+/** Blob upload limits configuration */
 export interface BlobLimits {
   maxHexBytes: number
   maxFileBytes: number
   maxHexDisplayLength: number
 }
 
+/** Blob validation result */
 export interface BlobValidationResult {
   valid: boolean
   error?: string
 }
 
 interface RecordExtras {
+  /** Child fields of the record */
   fields: FieldNode[]
+  /** Default value as object with all field defaults */
   defaultValue: Record<string, unknown>
 }
 
 interface VariantExtras {
-  fields: FieldNode[]
+  /** All variant options as fields */
+  options: FieldNode[]
+  /** The default selected option key */
   defaultOption: string
+  /** Default value with the first option selected */
   defaultValue: Record<string, unknown>
+  /** Get default value for a specific option */
   getOptionDefault: (option: string) => Record<string, unknown>
-  getField: (option: string) => FieldNode
-  getSelectedOption: (value: Record<string, unknown>) => string
-  getSelectedField: (value: Record<string, unknown>) => FieldNode
+  /** Get field descriptor for a specific option */
+  getOption: (option: string) => FieldNode
+  /** Get currently selected option key from a value */
+  getSelectedKey: (value: Record<string, unknown>) => string
+  /** Get the field for the currently selected option */
+  getSelectedOption: (value: Record<string, unknown>) => FieldNode
 }
 
 interface TupleExtras {
+  /** Tuple element fields */
   fields: FieldNode[]
+  /** Default value as array of element defaults */
   defaultValue: unknown[]
 }
 
 interface OptionalExtras {
+  /** The inner type field */
   innerField: FieldNode
+  /** Default value is always null */
   defaultValue: null
+  /** Get default value of the inner type when enabling */
   getInnerDefault: () => unknown
+  /** Check if a value represents an enabled optional */
   isEnabled: (value: unknown) => boolean
 }
 
 interface VectorExtras {
+  /** Template field for vector items */
   itemField: FieldNode
+  /** Default value is empty array */
   defaultValue: unknown[]
+  /** Get default value for a new item */
   getItemDefault: () => unknown
+  /** Create a field node for an item at a specific index */
   createItemField: (index: number, overrides?: { label?: string }) => FieldNode
 }
 
 interface BlobExtras {
+  /** Template field for blob bytes */
   itemField: FieldNode
+  /** Accepted input formats */
   acceptedFormats: ("hex" | "base64" | "file")[]
+  /** Upload limits */
   limits: BlobLimits
+  /** Normalize hex input string */
   normalizeHex: (input: string) => string
+  /** Validate blob input */
   validateInput: (value: string | Uint8Array) => BlobValidationResult
+  /** Default value is empty string */
   defaultValue: string
 }
 
 interface RecursiveExtras {
+  /** The recursive type name */
   typeName: string
+  /** Lazily extract the inner type */
   extract: () => FieldNode
+  /** Get default value of the inner type */
   getInnerDefault: () => unknown
+  /** Default value is undefined */
   defaultValue: undefined
 }
 
 interface PrincipalExtras {
+  /** Maximum Principal string length */
   maxLength: number
+  /** Minimum Principal string length */
   minLength: number
+  /** Detected text format */
   format: TextFormat
+  /** Pre-computed HTML input props */
   inputProps: PrimitiveInputProps
+  /** Default value is empty string */
   defaultValue: string
 }
 
 interface NumberExtras {
+  /** Whether the number is unsigned (nat vs int) */
   unsigned: boolean
+  /** Whether the number is a float */
   isFloat: boolean
+  /** Bit width (8, 16, 32, 64) */
   bits?: number
+  /** Minimum value as string */
   min?: string
+  /** Maximum value as string */
   max?: string
+  /** Detected number format */
   format: NumberFormat
+  /** Pre-computed HTML input props */
   inputProps: PrimitiveInputProps
+  /** Default value is empty string */
   defaultValue: string
 }
 
 interface TextExtras {
+  /** Minimum text length */
   minLength?: number
+  /** Maximum text length */
   maxLength?: number
+  /** Whether to use multiline input */
   multiline?: boolean
+  /** Detected text format */
   format: TextFormat
+  /** Pre-computed HTML input props */
   inputProps: PrimitiveInputProps
+  /** Default value is empty string */
   defaultValue: string
 }
 
 interface BooleanExtras {
+  /** Pre-computed HTML input props */
   inputProps: PrimitiveInputProps
+  /** Default value is false */
   defaultValue: boolean
 }
 
 interface NullExtras {
+  /** Default value is null */
   defaultValue: null
 }
 
 interface UnknownExtras {
+  /** Default value is undefined */
   defaultValue: undefined
 }
 
@@ -238,27 +324,33 @@ export type UnknownField = FieldNode<"unknown">
 // Form Metadata
 // ════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Metadata for a single method's input arguments.
+ * Use this to generate dynamic forms for calling canister methods.
+ */
 export interface ArgumentsMeta<
   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
-  fields: FieldNode[]
-  defaultValues: unknown[]
+  /** Array of field descriptors, one per argument */
+  args: FieldNode[]
+  /** Default values suitable for form initialization */
+  defaults: unknown[]
+  /** Zod schema for validating all arguments together */
   schema: z.ZodTuple<[z.ZodTypeAny, ...z.ZodTypeAny[]]>
+  /** Number of arguments (0 for no-arg methods) */
   argCount: number
-  isNoArgs: boolean
-}
-
-export interface FormOptions {
-  defaultValues: unknown[]
-  validators: {
-    onChange: z.ZodTypeAny
-    onBlur: z.ZodTypeAny
-  }
+  /** True if this method takes no arguments */
+  isEmpty: boolean
 }
 
+/**
+ * Service-level metadata mapping method names to their argument metadata.
+ */
 export type ArgumentsServiceMeta<A = BaseActor> = {
   [K in FunctionName<A>]: ArgumentsMeta<A, K>
 }
@@ -267,16 +359,15 @@ export type ArgumentsServiceMeta<A = BaseActor> = {
 // Type Utilities
 // ════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Extract field type by VisitorDataType.
+ */
 export type FieldByType<T extends VisitorDataType> = Extract<
   FieldNode,
   { type: T }
 >
 
-export type FieldProps<T extends VisitorDataType> = {
-  field: FieldByType<T>
-  renderField?: (child: FieldNode) => React.ReactNode
-}
-
+/** Compound field types that contain other fields */
 export type CompoundField =
   | RecordField
   | VariantField
@@ -285,6 +376,7 @@ export type CompoundField =
   | VectorField
   | RecursiveField
 
+/** Primitive field types with direct values */
 export type PrimitiveField =
   | PrincipalField
   | NumberField

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

@@ -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")
     })