@ic-reactor/candid 3.0.9-beta.0 → 3.0.10-beta.0

package/src/visitor/returns/types.ts

@@ -6,10 +6,10 @@ import type {
 } from "@ic-reactor/core"
 
 // ════════════════════════════════════════════════════════════════════════════
-// Field Type Union
+// Core Types & Formats
 // ════════════════════════════════════════════════════════════════════════════
 
-export type ResultFieldType =
+export type NodeType =
   | "record"
   | "variant"
   | "tuple"
@@ -24,35 +24,20 @@ export type ResultFieldType =
   | "null"
   | "unknown"
 
-// ════════════════════════════════════════════════════════════════════════════
-// Display Type (what it becomes after transformation)
-// ════════════════════════════════════════════════════════════════════════════
-
 export type DisplayType =
-  | "string" // Principal, nat, int, nat64, int64, blob, text
-  | "number" // float32, float64, nat8-nat32, int8-int32
-  | "boolean" // bool
-  | "null" // null
-  | "object" // record
-  | "array" // vec, tuple
-  | "variant" // variant (not Result)
-  | "result" // variant { Ok, Err } - unwrapped to Ok value
-  | "nullable" // opt T → T | null
-  | "recursive" // rec types
-  | "unknown" // fallback
-
-// ════════════════════════════════════════════════════════════════════════════
-// Format Hints
-// ════════════════════════════════════════════════════════════════════════════
+  | "string"
+  | "number"
+  | "boolean"
+  | "null"
+  | "object"
+  | "array"
+  | "variant"
+  | "result"
+  | "nullable"
+  | "recursive"
+  | "unknown"
 
-/**
- * Number-specific formatting hints derived from field names.
- */
 export type NumberFormat = "timestamp" | "cycle" | "value" | "token" | "normal"
-
-/**
- * Text-specific formatting hints derived from field names.
- */
 export type TextFormat =
   | "plain"
   | "timestamp"
@@ -65,305 +50,119 @@ export type TextFormat =
   | "account-id"
   | "principal"
 
-/**
- * Display hints for UI rendering.
- */
-export type DisplayHint =
-  | "copyable" // Show copy button
-  | "linkable" // Can be linked
-  | "truncate" // Truncate long values
-  | "hex" // Display as hex
-  | "code" // Display as code/monospace
-  | "none" // No special formatting
-
 // ════════════════════════════════════════════════════════════════════════════
-// Base Field Interface
+// Unified Result Node - Single Structure for Schema & Resolved Data
 // ════════════════════════════════════════════════════════════════════════════
 
-export interface ResultFieldBase<
-  Type extends ResultFieldType = ResultFieldType,
-> {
+/**
+ * Base properties shared by all result nodes.
+ */
+interface ResultNodeBase<T extends NodeType = NodeType> {
   /** The Candid type category */
-  type: Type
-  /** Human-readable label from Candid */
+  type: T
+  /** Human-readable label */
   label: string
   /** Original Candid type name */
   candidType: string
   /** What it becomes after display transformation */
   displayType: DisplayType
-  /**
-   * Combine metadata with value to create a render-ready tree.
-   * This allows "zipping" the static schema with dynamic runtime data.
-   */
-  resolve(value: unknown): ResultFieldWithValue<Type>
-}
-
-// ════════════════════════════════════════════════════════════════════════════
-// Compound Types
-// ════════════════════════════════════════════════════════════════════════════
-
-export interface RecordResultField extends ResultFieldBase<"record"> {
-  type: "record"
-  displayType: "object"
-  fields: ResultField[]
-}
-
-export interface VariantResultField extends ResultFieldBase<"variant"> {
-  type: "variant"
-  displayType: "variant" | "result"
-  options: string[]
-  optionFields: ResultField[]
-}
-
-export interface TupleResultField extends ResultFieldBase<"tuple"> {
-  type: "tuple"
-  displayType: "array"
-  fields: ResultField[]
-}
-
-export interface OptionalResultField extends ResultFieldBase<"optional"> {
-  type: "optional"
-  displayType: "nullable"
-  innerField: ResultField
-}
-
-export interface VectorResultField extends ResultFieldBase<"vector"> {
-  type: "vector"
-  displayType: "array"
-  itemField: ResultField
-}
-
-export interface BlobResultField extends ResultFieldBase<"blob"> {
-  type: "blob"
-  displayType: "string"
-  displayHint: "hex"
-}
-
-export interface RecursiveResultField extends ResultFieldBase {
-  type: "recursive"
-  displayType: "recursive"
-  typeName: string
-  /** Lazily extract the inner field to prevent infinite loops */
-  extract: () => ResultField
-}
-
-// ════════════════════════════════════════════════════════════════════════════
-// Primitive Types
-// ════════════════════════════════════════════════════════════════════════════
-
-export interface PrincipalResultField extends ResultFieldBase<"principal"> {
-  type: "principal"
-  displayType: "string"
-  textFormat: TextFormat
-}
-
-export interface NumberResultField extends ResultFieldBase<"number"> {
-  type: "number"
-  displayType: "string" | "number"
-  numberFormat: NumberFormat
-}
-
-export interface TextResultField extends ResultFieldBase<"text"> {
-  type: "text"
-  displayType: "string"
-  textFormat: TextFormat
-}
-
-export interface BooleanResultField extends ResultFieldBase<"boolean"> {
-  type: "boolean"
-  displayType: "boolean"
-}
-
-export interface NullResultField extends ResultFieldBase<"null"> {
-  type: "null"
-  displayType: "null"
-}
-
-export interface UnknownResultField extends ResultFieldBase<"unknown"> {
-  type: "unknown"
-  displayType: "unknown"
-}
-
-// ════════════════════════════════════════════════════════════════════════════
-// Union Type
-// ════════════════════════════════════════════════════════════════════════════
-
-export type ResultField =
-  | RecordResultField
-  | VariantResultField
-  | TupleResultField
-  | OptionalResultField
-  | VectorResultField
-  | BlobResultField
-  | RecursiveResultField
-  | PrincipalResultField
-  | NumberResultField
-  | TextResultField
-  | BooleanResultField
-  | NullResultField
-  | UnknownResultField
-
-// ════════════════════════════════════════════════════════════════════════════
-// Result Field With Value Interfaces
-// ════════════════════════════════════════════════════════════════════════════
+  /** Original raw value before transformation (present after resolution) */
+  raw?: unknown
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Type-Specific Extras (embedded directly in node)
+// For compound types, children are stored directly in their respective fields
+// ════════════════════════════════════════════════════════════════════════════
+
+type NodeTypeExtras<T extends NodeType> = T extends "record"
+  ? { fields: Record<string, ResultNode> }
+  : 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 }
+            : 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
 
-export interface RecordResultWithValue<V = unknown> {
-  field: RecordResultField
-  value: Record<string, ResultFieldWithValue>
-  raw: V
-}
-
-export interface VariantResultWithValue<V = unknown> {
-  field: VariantResultField
-  value: { option: string; value: ResultFieldWithValue }
-  raw: V
-}
-
-export interface TupleResultWithValue<V = unknown> {
-  field: TupleResultField
-  value: ResultFieldWithValue[]
-  raw: V
-}
-
-export interface OptionalResultWithValue<V = unknown> {
-  field: OptionalResultField
-  value: ResultFieldWithValue | null
-  raw: V
-}
-
-export interface VectorResultWithValue<V = unknown> {
-  field: VectorResultField
-  value: ResultFieldWithValue[]
-  raw: V
-}
-
-export interface BlobResultWithValue<V = unknown> {
-  field: BlobResultField
-  value: string
-  raw: V
-}
-
-export interface RecursiveResultWithValue<V = unknown> {
-  field: RecursiveResultField
-  // Resolves to the specific inner type which is also a ResultFieldWithValue
-  value: ResultFieldWithValue
-  raw: V
-}
-
-export interface PrincipalResultWithValue<V = unknown> {
-  field: PrincipalResultField
-  value: string
-  raw: V
-}
-
-export interface NumberResultWithValue<V = unknown> {
-  field: NumberResultField
-  value: string | number
-  raw: V
-}
-
-export interface TextResultWithValue<V = unknown> {
-  field: TextResultField
-  value: string
-  raw: V
-}
-
-export interface BooleanResultWithValue<V = unknown> {
-  field: BooleanResultField
-  value: boolean
-  raw: V
-}
-
-export interface NullResultWithValue<V = unknown> {
-  field: NullResultField
-  value: null
-  raw: V
-}
+/**
+ * A unified result node that contains both schema and resolved value.
+ * When used as schema only, `raw` is undefined.
+ * When resolved, `raw` contains the original data.
+ *
+ * Compound types (record, variant, tuple, optional, vector) store
+ * 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>
+    value?: unknown
+  }
 
-export interface UnknownResultWithValue<V = unknown> {
-  field: UnknownResultField
-  value: unknown
-  raw: V
+/**
+ * A resolved node has `raw` populated and children resolved.
+ */
+export type ResolvedNode<T extends NodeType = NodeType> = ResultNode<T> & {
+  raw: unknown
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Maps and Helper Types
+// Convenience Type Aliases
 // ════════════════════════════════════════════════════════════════════════════
 
-/**
- * Mapping from ResultFieldType string to the corresponding *ResultWithValue interface.
- */
-export type ResultWithValueMap<V = unknown> = {
-  record: RecordResultWithValue<V>
-  variant: VariantResultWithValue<V>
-  tuple: TupleResultWithValue<V>
-  optional: OptionalResultWithValue<V>
-  vector: VectorResultWithValue<V>
-  blob: BlobResultWithValue<V>
-  recursive: RecursiveResultWithValue<V>
-  principal: PrincipalResultWithValue<V>
-  number: NumberResultWithValue<V>
-  text: TextResultWithValue<V>
-  boolean: BooleanResultWithValue<V>
-  null: NullResultWithValue<V>
-  unknown: UnknownResultWithValue<V>
-}
-
-/**
- * A result field paired with its transformed value for rendering.
- * Can contain nested resolved fields for compound types.
- *
- * It is a discriminated union of all specific result types.
- */
-export type ResultFieldWithValue<
-  P = unknown,
-  V = unknown,
-> = P extends ResultFieldType
-  ? ResultWithValueMap<V>[P]
-  : ResultWithValueMap<V>[ResultFieldType]
+export type RecordNode = ResultNode<"record">
+export type VariantNode = ResultNode<"variant">
+export type TupleNode = ResultNode<"tuple">
+export type OptionalNode = ResultNode<"optional">
+export type VectorNode = ResultNode<"vector">
+export type BlobNode = ResultNode<"blob">
+export type RecursiveNode = ResultNode<"recursive">
+export type PrincipalNode = ResultNode<"principal">
+export type NumberNode = ResultNode<"number">
+export type TextNode = ResultNode<"text">
+export type BooleanNode = ResultNode<"boolean">
+export type NullNode = ResultNode<"null">
+export type UnknownNode = ResultNode<"unknown">
 
 // ════════════════════════════════════════════════════════════════════════════
 // Method & Service Level
 // ════════════════════════════════════════════════════════════════════════════
 
-/**
- * Resolved method result containing metadata and resolved field values.
- * This is the output of `generateMetadata()`.
- */
-export interface ResolvedMethodResult<A = BaseActor> {
-  functionType: FunctionType
-  functionName: FunctionName<A>
-  results: ResultFieldWithValue[]
-  raw: ActorMethodReturnType<A[FunctionName<A>]>
-}
-
-export interface MethodResultMeta<
+export interface MethodMeta<
   A = BaseActor,
   Name extends FunctionName<A> = FunctionName<A>,
 > {
   functionType: FunctionType
   functionName: Name
-  resultFields: ResultField[]
+  returns: ResultNode[]
   returnCount: number
   /**
-   * Generate metadata by resolving each result field with its corresponding display value.
-   * This "zips" the static schema with dynamic runtime data for easy rendering.
-   *
-   * @param data - Array of display-transformed return values from the canister method call
-   * @returns Resolved method result with metadata attached to each value
-   *
-   * @example
-   * ```ts
-   * const result = await reactor.callMethod({ functionName: "myMethod", args: [] })
-   * const resolved = methodMeta.generateMetadata(result)
-   * // resolved.results contains fields with their display values for rendering
-   * ```
+   * Resolve the method result schema with actual return data.
    */
-  generateMetadata(
-    data: ActorMethodReturnType<A[Name]>
-  ): ResolvedMethodResult<A>
+  resolve(data: ActorMethodReturnType<A[Name]>): ResolvedMethodResult<A>
+}
+
+export interface ResolvedMethodResult<A = BaseActor> {
+  functionType: FunctionType
+  functionName: FunctionName<A>
+  results: ResolvedNode[]
+  raw: ActorMethodReturnType<A[FunctionName<A>]>
 }
 
-export type ServiceResultMeta<A = BaseActor> = {
-  [K in FunctionName<A>]: MethodResultMeta<A, K>
+export type ServiceMeta<A = BaseActor> = {
+  [K in FunctionName<A>]: MethodMeta<A, K>
 }