@ic-reactor/candid 3.0.7-beta.2 → 3.0.8-beta.0

package/src/visitor/arguments/index.ts

@@ -0,0 +1,405 @@
+import { isQuery } from "../helpers"
+import { IDL } from "../types"
+import type {
+  ArgumentField,
+  RecordArgumentField,
+  VariantArgumentField,
+  TupleArgumentField,
+  OptionalArgumentField,
+  VectorArgumentField,
+  BlobArgumentField,
+  RecursiveArgumentField,
+  PrincipalArgumentField,
+  NumberArgumentField,
+  BooleanArgumentField,
+  NullArgumentField,
+  TextArgumentField,
+  UnknownArgumentField,
+  MethodArgumentsMeta,
+  ServiceArgumentsMeta,
+} from "./types"
+import { BaseActor, FunctionName } from "@ic-reactor/core"
+
+export * from "./types"
+
+/**
+ * ArgumentFieldVisitor generates metadata for form input fields from Candid IDL types.
+ *
+ * ## Design Principles
+ *
+ * 1. **Works with raw IDL types** - generates metadata at initialization time
+ * 2. **No value dependencies** - metadata is independent of actual values
+ * 3. **Form-framework agnostic** - output can be used with TanStack, React Hook Form, etc.
+ * 4. **Efficient** - single traversal, no runtime type checking
+ *
+ * ## Output Structure
+ *
+ * Each field has:
+ * - `type`: The field type (record, variant, text, number, etc.)
+ * - `label`: Human-readable label from Candid
+ * - `path`: Dot-notation path for form binding (e.g., "0.owner")
+ * - `defaultValue`: Initial value for the form
+ * - Type-specific properties (options for variant, fields for record, etc.)
+ *
+ * @example
+ * ```typescript
+ * const visitor = new ArgumentFieldVisitor()
+ * const serviceMeta = service.accept(visitor, null)
+ *
+ * // For a specific method
+ * const methodMeta = serviceMeta["icrc1_transfer"]
+ * // methodMeta.fields = [{ type: "record", fields: [...] }]
+ * // methodMeta.defaultValues = [{ to: "", amount: "" }]
+ * ```
+ */
+export class ArgumentFieldVisitor<A = BaseActor> extends IDL.Visitor<
+  string,
+  ArgumentField | MethodArgumentsMeta<A> | ServiceArgumentsMeta<A>
+> {
+  private pathStack: string[] = []
+
+  private withPath<T>(path: string, fn: () => T): T {
+    this.pathStack.push(path)
+    try {
+      return fn()
+    } finally {
+      this.pathStack.pop()
+    }
+  }
+
+  private currentPath(): string {
+    return this.pathStack[this.pathStack.length - 1] ?? ""
+  }
+
+  private childPath(key: string | number): string {
+    const parent = this.currentPath()
+    if (typeof key === "number") {
+      return parent ? `${parent}[${key}]` : String(key)
+    }
+    return parent ? `${parent}.${key}` : key
+  }
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Service & Function Level
+  // ════════════════════════════════════════════════════════════════════════
+
+  public visitService(t: IDL.ServiceClass): ServiceArgumentsMeta<A> {
+    const result = {} as ServiceArgumentsMeta<A>
+
+    for (const [functionName, func] of t._fields) {
+      result[functionName as FunctionName<A>] = func.accept(
+        this,
+        functionName
+      ) as MethodArgumentsMeta<A>
+    }
+
+    return result
+  }
+
+  public visitFunc(
+    t: IDL.FuncClass,
+    functionName: FunctionName<A>
+  ): MethodArgumentsMeta<A> {
+    const functionType = isQuery(t) ? "query" : "update"
+
+    const fields = t.argTypes.map((arg, index) => {
+      return this.withPath(`[${index}]`, () =>
+        arg.accept(this, `__arg${index}`)
+      ) as ArgumentField
+    })
+
+    const defaultValues = fields.map((field) => this.extractDefaultValue(field))
+
+    return {
+      functionType,
+      functionName,
+      fields,
+      defaultValues,
+    }
+  }
+
+  private extractDefaultValue(field: ArgumentField): unknown {
+    if ("defaultValue" in field) {
+      return field.defaultValue
+    }
+    if ("defaultValues" in field) {
+      return field.defaultValues
+    }
+    return undefined
+  }
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Compound Types
+  // ════════════════════════════════════════════════════════════════════════
+
+  public visitRecord(
+    _t: IDL.RecordClass,
+    fields_: Array<[string, IDL.Type]>,
+    label: string
+  ): RecordArgumentField {
+    const path = this.currentPath()
+    const fields: ArgumentField[] = []
+    const defaultValues: Record<string, unknown> = {}
+
+    for (const [key, type] of fields_) {
+      const field = this.withPath(this.childPath(key), () =>
+        type.accept(this, key)
+      ) as ArgumentField
+
+      fields.push(field)
+      defaultValues[key] = this.extractDefaultValue(field)
+    }
+
+    return {
+      type: "record",
+      label,
+      path,
+      fields,
+      defaultValues,
+    }
+  }
+
+  public visitVariant(
+    _t: IDL.VariantClass,
+    fields_: Array<[string, IDL.Type]>,
+    label: string
+  ): VariantArgumentField {
+    const path = this.currentPath()
+    const fields: ArgumentField[] = []
+    const options: string[] = []
+
+    for (const [key, type] of fields_) {
+      const field = this.withPath(this.childPath(key), () =>
+        type.accept(this, key)
+      ) as ArgumentField
+
+      fields.push(field)
+      options.push(key)
+    }
+
+    const defaultOption = options[0]
+    const defaultValues = {
+      [defaultOption]: this.extractDefaultValue(fields[0]),
+    }
+
+    return {
+      type: "variant",
+      label,
+      path,
+      fields,
+      options,
+      defaultOption,
+      defaultValues,
+    }
+  }
+
+  public visitTuple<T extends IDL.Type[]>(
+    _t: IDL.TupleClass<T>,
+    components: IDL.Type[],
+    label: string
+  ): TupleArgumentField {
+    const path = this.currentPath()
+    const fields: ArgumentField[] = []
+    const defaultValues: unknown[] = []
+
+    for (let index = 0; index < components.length; index++) {
+      const type = components[index]
+      const field = this.withPath(this.childPath(index), () =>
+        type.accept(this, `_${index}_`)
+      ) as ArgumentField
+
+      fields.push(field)
+      defaultValues.push(this.extractDefaultValue(field))
+    }
+
+    return {
+      type: "tuple",
+      label,
+      path,
+      fields,
+      defaultValues,
+    }
+  }
+
+  public visitOpt<T>(
+    _t: IDL.OptClass<T>,
+    ty: IDL.Type<T>,
+    label: string
+  ): OptionalArgumentField {
+    const path = this.currentPath()
+
+    const innerField = this.withPath(this.childPath(0), () =>
+      ty.accept(this, label)
+    ) as ArgumentField
+
+    return {
+      type: "optional",
+      label,
+      path,
+      innerField,
+      defaultValue: null,
+    }
+  }
+
+  public visitVec<T>(
+    _t: IDL.VecClass<T>,
+    ty: IDL.Type<T>,
+    label: string
+  ): VectorArgumentField | BlobArgumentField {
+    const path = this.currentPath()
+
+    // Check if it's blob (vec nat8)
+    const isBlob = ty instanceof IDL.FixedNatClass && ty._bits === 8
+
+    const itemField = this.withPath(this.childPath(0), () =>
+      ty.accept(this, label)
+    ) as ArgumentField
+
+    if (isBlob) {
+      return {
+        type: "blob",
+        label,
+        path,
+        itemField,
+        defaultValue: "",
+      }
+    }
+
+    return {
+      type: "vector",
+      label,
+      path,
+      itemField,
+      defaultValue: [],
+    }
+  }
+
+  public visitRec<T>(
+    _t: IDL.RecClass<T>,
+    ty: IDL.ConstructType<T>,
+    label: string
+  ): RecursiveArgumentField {
+    const path = this.currentPath()
+
+    return {
+      type: "recursive",
+      label,
+      path,
+      // Lazy extraction to prevent infinite loops
+      extract: () =>
+        this.withPath(path, () => ty.accept(this, label)) as ArgumentField,
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════════════
+  // Primitive Types
+  // ════════════════════════════════════════════════════════════════════════
+
+  public visitPrincipal(
+    _t: IDL.PrincipalClass,
+    label: string
+  ): PrincipalArgumentField {
+    return {
+      type: "principal",
+      label,
+      path: this.currentPath(),
+      defaultValue: "",
+      maxLength: 64,
+      minLength: 7,
+    }
+  }
+
+  public visitText(_t: IDL.TextClass, label: string): TextArgumentField {
+    return {
+      type: "text",
+      label,
+      path: this.currentPath(),
+      defaultValue: "",
+    }
+  }
+
+  public visitBool(_t: IDL.BoolClass, label: string): BooleanArgumentField {
+    return {
+      type: "boolean",
+      label,
+      path: this.currentPath(),
+      defaultValue: false,
+    }
+  }
+
+  public visitNull(_t: IDL.NullClass, label: string): NullArgumentField {
+    return {
+      type: "null",
+      label,
+      path: this.currentPath(),
+      defaultValue: null,
+    }
+  }
+
+  // Numbers - all use string for display format
+  private visitNumberType(
+    label: string,
+    candidType: string
+  ): NumberArgumentField {
+    return {
+      type: "number",
+      label,
+      path: this.currentPath(),
+      defaultValue: "",
+      candidType,
+    }
+  }
+
+  public visitInt(_t: IDL.IntClass, label: string): NumberArgumentField {
+    return this.visitNumberType(label, "int")
+  }
+
+  public visitNat(_t: IDL.NatClass, label: string): NumberArgumentField {
+    return this.visitNumberType(label, "nat")
+  }
+
+  public visitFloat(_t: IDL.FloatClass, label: string): NumberArgumentField {
+    return this.visitNumberType(label, "float")
+  }
+
+  public visitFixedInt(
+    t: IDL.FixedIntClass,
+    label: string
+  ): NumberArgumentField {
+    return this.visitNumberType(label, `int${t._bits}`)
+  }
+
+  public visitFixedNat(
+    t: IDL.FixedNatClass,
+    label: string
+  ): NumberArgumentField {
+    return this.visitNumberType(label, `nat${t._bits}`)
+  }
+
+  public visitType<T>(_t: IDL.Type<T>, label: string): UnknownArgumentField {
+    return {
+      type: "unknown",
+      label,
+      path: this.currentPath(),
+      defaultValue: undefined,
+    }
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Legacy Exports (for backward compatibility)
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * @deprecated Use ArgumentFieldVisitor instead
+ */
+export { ArgumentFieldVisitor as VisitTanstackField }
+
+/**
+ * @deprecated Use ArgumentField instead
+ */
+export type {
+  ArgumentField as TanstackAllArgTypes,
+  MethodArgumentsMeta as TanstackMethodField,
+  ServiceArgumentsMeta as TanstackServiceField,
+}

package/src/visitor/arguments/types.ts

@@ -0,0 +1,168 @@
+import type { BaseActor, FunctionName, FunctionType } from "@ic-reactor/core"
+
+// ════════════════════════════════════════════════════════════════════════════
+// Field Type Union
+// ════════════════════════════════════════════════════════════════════════════
+
+export type ArgumentFieldType =
+  | "record"
+  | "variant"
+  | "tuple"
+  | "optional"
+  | "vector"
+  | "blob"
+  | "recursive"
+  | "principal"
+  | "number"
+  | "text"
+  | "boolean"
+  | "null"
+  | "unknown"
+
+// ════════════════════════════════════════════════════════════════════════════
+// Base Field Interface
+// ════════════════════════════════════════════════════════════════════════════
+
+export interface ArgumentFieldBase {
+  /** The field type */
+  type: ArgumentFieldType
+  /** Human-readable label from Candid */
+  label: string
+  /** Dot-notation path for form binding (e.g., "0.owner", "[0].to") */
+  path: string
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Compound Types
+// ════════════════════════════════════════════════════════════════════════════
+
+export interface RecordArgumentField extends ArgumentFieldBase {
+  type: "record"
+  fields: ArgumentField[]
+  defaultValues: Record<string, unknown>
+}
+
+export interface VariantArgumentField extends ArgumentFieldBase {
+  type: "variant"
+  fields: ArgumentField[]
+  options: string[]
+  defaultOption: string
+  defaultValues: Record<string, unknown>
+}
+
+export interface TupleArgumentField extends ArgumentFieldBase {
+  type: "tuple"
+  fields: ArgumentField[]
+  defaultValues: unknown[]
+}
+
+export interface OptionalArgumentField extends ArgumentFieldBase {
+  type: "optional"
+  innerField: ArgumentField
+  defaultValue: null
+}
+
+export interface VectorArgumentField extends ArgumentFieldBase {
+  type: "vector"
+  itemField: ArgumentField
+  defaultValue: []
+}
+
+export interface BlobArgumentField extends ArgumentFieldBase {
+  type: "blob"
+  itemField: ArgumentField
+  /** Default is empty hex string */
+  defaultValue: string
+}
+
+export interface RecursiveArgumentField extends ArgumentFieldBase {
+  type: "recursive"
+  /** Lazily extract the inner field to prevent infinite loops */
+  extract: () => ArgumentField
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Primitive Types
+// ════════════════════════════════════════════════════════════════════════════
+
+export interface PrincipalArgumentField extends ArgumentFieldBase {
+  type: "principal"
+  /** Display format: string */
+  defaultValue: string
+  maxLength: number
+  minLength: number
+}
+
+export interface NumberArgumentField extends ArgumentFieldBase {
+  type: "number"
+  /** Display format: string (for bigint compatibility) */
+  defaultValue: string
+  /** Original Candid type: nat, int, nat64, etc. */
+  candidType: string
+}
+
+export interface TextArgumentField extends ArgumentFieldBase {
+  type: "text"
+  defaultValue: string
+}
+
+export interface BooleanArgumentField extends ArgumentFieldBase {
+  type: "boolean"
+  defaultValue: boolean
+}
+
+export interface NullArgumentField extends ArgumentFieldBase {
+  type: "null"
+  defaultValue: null
+}
+
+export interface UnknownArgumentField extends ArgumentFieldBase {
+  type: "unknown"
+  defaultValue: undefined
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Union Type
+// ════════════════════════════════════════════════════════════════════════════
+
+export type ArgumentField =
+  | RecordArgumentField
+  | VariantArgumentField
+  | TupleArgumentField
+  | OptionalArgumentField
+  | VectorArgumentField
+  | BlobArgumentField
+  | RecursiveArgumentField
+  | PrincipalArgumentField
+  | NumberArgumentField
+  | TextArgumentField
+  | BooleanArgumentField
+  | NullArgumentField
+  | UnknownArgumentField
+
+// ════════════════════════════════════════════════════════════════════════════
+// Method & Service Level
+// ════════════════════════════════════════════════════════════════════════════
+
+export interface MethodArgumentsMeta<
+  A = BaseActor,
+  Name extends FunctionName<A> = FunctionName<A>,
+> {
+  functionType: FunctionType
+  functionName: Name
+  fields: ArgumentField[]
+  defaultValues: unknown[]
+}
+
+export type ServiceArgumentsMeta<A = BaseActor> = {
+  [K in FunctionName<A>]: MethodArgumentsMeta<A, K>
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Type Utilities
+// ════════════════════════════════════════════════════════════════════════════
+
+export type ArgumentFieldByType<T extends ArgumentFieldType> = Extract<
+  ArgumentField,
+  { type: T }
+>

package/src/visitor/constants.ts

@@ -0,0 +1,62 @@
+import type { TextFormat, NumberFormat } from "./returns/types"
+
+const TAMESTAMP_KEYS = [
+  "time",
+  "date",
+  "deadline",
+  "timestamp",
+  "timestamp_nanos",
+  "statusAt",
+  "createdAt",
+  "updatedAt",
+  "deletedAt",
+  "validUntil",
+  "status_at",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "valid_until",
+]
+
+const TAMESTAMP_KEYS_REGEX = new RegExp(
+  TAMESTAMP_KEYS.map((key) => `^[\\w-]*${key}[\\w-]*$`).join("|"),
+  "i"
+)
+
+const CYCLE_KEYS = ["cycle", "cycles"]
+
+const CYCLE_KEYS_REGEX = new RegExp(
+  CYCLE_KEYS.map((key) => `^[\\w-]*${key}[\\w-]*$`).join("|"),
+  "i"
+)
+
+const EMAIL_KEYS_REGEX = /email|mail/i
+const PHONE_KEYS_REGEX = /phone|tel|mobile/i
+const URL_KEYS_REGEX = /url|link|website/i
+const UUID_KEYS_REGEX = /uuid|guid/i
+const BITCOIN_KEYS_REGEX = /bitcoin|btc/i
+const ETHEREUM_KEYS_REGEX = /ethereum|eth/i
+const ACCOUNT_ID_KEYS_REGEX =
+  /account_id|account_identifier|ledger_account|block_hash|transaction_hash|tx_hash/i
+const PRINCIPAL_KEYS_REGEX = /canister|principal/i
+
+export const checkTextFormat = (label?: string): TextFormat => {
+  if (!label) return "plain"
+  if (TAMESTAMP_KEYS_REGEX.test(label)) return "timestamp"
+  if (EMAIL_KEYS_REGEX.test(label)) return "email"
+  if (PHONE_KEYS_REGEX.test(label)) return "phone"
+  if (URL_KEYS_REGEX.test(label)) return "url"
+  if (UUID_KEYS_REGEX.test(label)) return "uuid"
+  if (BITCOIN_KEYS_REGEX.test(label)) return "btc"
+  if (ETHEREUM_KEYS_REGEX.test(label)) return "eth"
+  if (ACCOUNT_ID_KEYS_REGEX.test(label)) return "account-id"
+  if (PRINCIPAL_KEYS_REGEX.test(label)) return "principal"
+  return "plain"
+}
+
+export const checkNumberFormat = (label?: string): NumberFormat => {
+  if (!label) return "normal"
+  if (TAMESTAMP_KEYS_REGEX.test(label)) return "timestamp"
+  if (CYCLE_KEYS_REGEX.test(label)) return "cycle"
+  return "normal"
+}