@ic-reactor/react 3.0.0-beta.7 → 3.0.0

package/src/types.ts

@@ -0,0 +1,435 @@
+/**
+ * Shared type definitions for query factories (createActorQuery, createActorSuspenseQuery, etc.)
+ */
+
+import type {
+  FunctionName,
+  ReactorReturnOk,
+  ReactorReturnErr,
+  ReactorArgs,
+  BaseActor,
+  TransformKey,
+  TransformReturnRegistry,
+  ErrResult,
+  ActorMethodReturnType,
+} from "@ic-reactor/core"
+import { CanisterError } from "@ic-reactor/core"
+import { CallConfig } from "@icp-sdk/core/agent"
+import {
+  QueryKey,
+  QueryObserverOptions,
+  UseQueryOptions,
+  UseQueryResult,
+  UseSuspenseQueryOptions,
+  UseSuspenseQueryResult,
+  UseMutationOptions,
+  UseMutationResult,
+} from "@tanstack/react-query"
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+// NoInfer prevents TypeScript from inferring a type parameter from a particular position
+// This is available in TypeScript 5.4+ natively, but we define it for compatibility
+export type NoInfer<T> = [T][T extends any ? 0 : never]
+// ============================================================================
+// Base Query Data Types
+// ============================================================================
+
+/** The raw data type returned by the query function (before select) */
+export type QueryFnData<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> = ReactorReturnOk<A, M, T>
+
+/** The error type for queries */
+export type QueryError<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> = ReactorReturnErr<A, M, T>
+
+// ============================================================================
+// Base Query Configuration
+// ============================================================================
+
+/**
+ * Base configuration for query wrappers (shared between regular and suspense).
+ *
+ * @template A - The actor interface type
+ * @template M - The method name on the actor
+ * @template T - The transformation key (identity, display, etc.)
+ * @template TSelected - The type returned after select transformation
+ */
+export interface BaseQueryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+> extends Omit<
+  QueryObserverOptions<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    TSelected,
+    ReactorReturnOk<A, M, T>,
+    QueryKey
+  >,
+  "queryFn" | "queryKey"
+> {
+  /** The method to call on the canister */
+  functionName: M
+  /** Arguments to pass to the method (if any) */
+  args?: ReactorArgs<A, M, T>
+  /** The query key to use for this query */
+  queryKey?: QueryKey
+  /** How long data stays fresh before refetching (default: 5 min) */
+  staleTime?: number
+  /** Transform the raw result before returning */
+  select?: (data: QueryFnData<A, M, T>) => TSelected
+}
+
+/**
+ * Configuration for createQuery (regular useQuery).
+ * Alias for BaseQueryConfig for clarity.
+ */
+export type QueryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+> = BaseQueryConfig<A, M, T, TSelected>
+
+/**
+ * Configuration for createSuspenseQuery (useSuspenseQuery).
+ * Alias for BaseQueryConfig for clarity.
+ */
+export type SuspenseQueryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+> = BaseQueryConfig<A, M, T, TSelected>
+
+// ============================================================================
+// Factory Configuration (without args)
+// ============================================================================
+
+/**
+ * Configuration for createQueryFactory (args are provided at call time).
+ */
+export type QueryFactoryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+> = Omit<QueryConfig<A, M, T, TSelected>, "args">
+
+/**
+ * Configuration for createSuspenseQueryFactory (args are provided at call time).
+ */
+export type SuspenseQueryFactoryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+> = Omit<SuspenseQueryConfig<A, M, T, TSelected>, "args">
+
+// ============================================================================
+// Hook Interfaces with Chained Select Support
+// ============================================================================
+
+/**
+ * useQuery hook with chained select support.
+ * - Without select: returns TSelected (from config.select)
+ * - With select: chains on top and returns TFinal
+ *
+ * Accepts all useQuery options from React Query documentation.
+ * Select is special: it chains on top of config.select.
+ */
+export interface UseQueryWithSelect<
+  TQueryFnData,
+  TSelected = TQueryFnData,
+  TError = Error,
+> {
+  // Overload 1: Without select - returns TSelected
+  // Note: select is included as optional (never type) to enable autocomplete suggestions
+  (
+    options?: Omit<
+      UseQueryOptions<TQueryFnData, TError, TSelected>,
+      "queryKey" | "queryFn"
+    > & {
+      select?: undefined
+    }
+  ): UseQueryResult<TSelected, TError>
+
+  // Overload 2: With select - chains on top of config.select and returns TFinal
+  <TFinal = TSelected>(
+    options: Omit<
+      UseQueryOptions<TQueryFnData, TError, TFinal>,
+      "queryKey" | "queryFn" | "select"
+    > & {
+      select: (data: TSelected) => TFinal
+    }
+  ): UseQueryResult<TFinal, TError>
+}
+
+/**
+ * useSuspenseQuery hook with chained select support.
+ * - Without select: returns TSelected (from config.select)
+ * - With select: chains on top and returns TFinal
+ *
+ * Accepts all useSuspenseQuery options from React Query documentation.
+ * Select is special: it chains on top of config.select.
+ * Data is always defined (never undefined).
+ * Does NOT support `enabled` option.
+ */
+export interface UseSuspenseQueryWithSelect<
+  TQueryFnData,
+  TSelected = TQueryFnData,
+  TError = Error,
+> {
+  // Overload 1: Without select - returns TSelected
+  // Note: select is included as optional (never type) to enable autocomplete suggestions
+  (
+    options?: Omit<
+      UseSuspenseQueryOptions<TQueryFnData, TError, TSelected>,
+      "queryKey" | "queryFn"
+    > & {
+      select?: undefined
+    }
+  ): UseSuspenseQueryResult<TSelected, TError>
+
+  // Overload 2: With select - chains on top of config.select and returns TFinal
+  <TFinal = TSelected>(
+    options: Omit<
+      UseSuspenseQueryOptions<TQueryFnData, TError, TFinal>,
+      "queryKey" | "queryFn" | "select"
+    > & {
+      select: (data: TSelected) => TFinal
+    }
+  ): UseSuspenseQueryResult<TFinal, TError>
+}
+
+// ============================================================================
+// Result Interfaces
+// ============================================================================
+
+/**
+ * Base result interface shared between createQuery and createSuspenseQuery.
+ *
+ * @template TQueryFnData - The raw data type
+ * @template TSelected - The type after select transformation
+ * @template TError - The error type
+ */
+export interface BaseQueryResult<
+  TQueryFnData,
+  TSelected = TQueryFnData,
+  _TError = Error,
+> {
+  /** Fetch data in loader (uses ensureQueryData for cache-first) */
+  fetch: () => Promise<TSelected>
+
+  /** Invalidate the cache (refetches if query is active) */
+  invalidate: () => Promise<void>
+
+  /** Get query key (for advanced React Query usage) */
+  getQueryKey: () => QueryKey
+
+  /**
+   * Read data directly from cache without fetching.
+   * Returns undefined if data is not in cache.
+   *
+   * @template TFinal - Type returned after optional select transformation
+   * @param select - Optional select function to transform cached data further
+   * @returns Cached data with select applied, or undefined if not in cache
+   *
+   * @example
+   * // Just get the cached data
+   * const user = userQuery.getCacheData()
+   *
+   * // With additional select transformation
+   * const name = userQuery.getCacheData((user) => user.name)
+   */
+  getCacheData: {
+    (): TSelected | undefined
+    <TFinal>(select: (data: TSelected) => TFinal): TFinal | undefined
+  }
+}
+
+/**
+ * Result from createQuery
+ *
+ * Includes useQuery hook that:
+ * - Supports `enabled` option for conditional fetching
+ * - Data may be `undefined` during loading
+ * - Uses regular `useQuery` with manual loading state handling
+ *
+ * @template TQueryFnData - The raw data type
+ * @template TSelected - The type after select transformation
+ * @template TError - The error type
+ */
+export interface QueryResult<
+  TQueryFnData,
+  TSelected = TQueryFnData,
+  TError = Error,
+> extends BaseQueryResult<TQueryFnData, TSelected, TError> {
+  /** React hook for components - supports chained select and enabled option */
+  useQuery: UseQueryWithSelect<TQueryFnData, TSelected, TError>
+}
+
+/**
+ * Result from createSuspenseQuery
+ *
+ * Includes useSuspenseQuery hook that:
+ * - Requires wrapping in <Suspense> boundary
+ * - Data is always defined (no undefined checks)
+ * - Does NOT support `enabled` option
+ *
+ * @template TQueryFnData - The raw data type
+ * @template TSelected - The type after select transformation
+ * @template TError - The error type
+ */
+export interface SuspenseQueryResult<
+  TQueryFnData,
+  TSelected = TQueryFnData,
+  TError = Error,
+> extends BaseQueryResult<TQueryFnData, TSelected, TError> {
+  /** React hook for components - data is always defined (wrap in Suspense) */
+  useSuspenseQuery: UseSuspenseQueryWithSelect<TQueryFnData, TSelected, TError>
+}
+
+// ============================================================================
+// Actor Mutation Types
+// ============================================================================
+
+/**
+ * Configuration for createMutation and useActorMutation.
+ */
+export interface MutationConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> extends Omit<
+  UseMutationOptions<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    ReactorArgs<A, M, T>
+  >,
+  "mutationFn"
+> {
+  /** The method to call on the canister */
+  functionName: M
+  /** Call configuration for the actor method */
+  callConfig?: CallConfig
+  /** Queries to invalidate upon successful mutation */
+  invalidateQueries?: QueryKey[]
+  /**
+   * Callback for canister-level business logic errors.
+   * Called when the canister returns a Result { Err: E } variant.
+   *
+   * This is separate from `onError` which handles all errors including
+   * network failures, agent errors, etc.
+   *
+   * @param error - The CanisterError containing the typed error value
+   * @param variables - The arguments passed to the mutation
+   *
+   * @example
+   * ```typescript
+   * createMutation(reactor, {
+   *   functionName: "transfer",
+   *   onCanisterError: (error, variables) => {
+   *     // error.err contains the typed Err value
+   *     // error.code contains the variant key (e.g., "InsufficientFunds")
+   *     console.error(`Transfer failed: ${error.code}`, error.err)
+   *   },
+   * })
+   * ```
+   */
+  onCanisterError?: (
+    error: CanisterError<unknown>,
+    variables: ReactorArgs<A, M, T>
+  ) => void
+}
+
+/**
+ * Configuration for createMutationFactory.
+ */
+export type MutationFactoryConfig<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> = Omit<MutationConfig<A, M, T>, "onSuccess">
+
+/**
+ * Options for useMutation hook.
+ * Extends React Query's UseMutationOptions with invalidateQueries support.
+ */
+export interface MutationHookOptions<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> extends Omit<
+  UseMutationOptions<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    ReactorArgs<A, M, T>
+  >,
+  "mutationFn"
+> {
+  /**
+   * Query keys to invalidate upon successful mutation.
+   * Use query.getQueryKey() to get the key from a query result.
+   *
+   * @example
+   * const balanceQuery = getIcpBalance(account)
+   * useMutation({
+   *   invalidateQueries: [balanceQuery.getQueryKey()],
+   * })
+   */
+  invalidateQueries?: (QueryKey | undefined)[]
+  /**
+   * Callback for canister-level business logic errors.
+   * Called when the canister returns a Result { Err: E } variant.
+   *
+   * @param error - The CanisterError containing the typed error value
+   * @param variables - The arguments passed to the mutation
+   */
+  onCanisterError?: (
+    error: CanisterError<
+      TransformReturnRegistry<ErrResult<ActorMethodReturnType<A[M]>>>[T]
+    >,
+    variables: ReactorArgs<A, M, T>
+  ) => void
+}
+
+/**
+ * Result from createMutation.
+ */
+export interface MutationResult<
+  A = BaseActor,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+> {
+  /**
+   * React hook for the mutation.
+   * Accepts options to override/extend the factory config.
+   *
+   * @example
+   * // With invalidateQueries to auto-update balance after transfer
+   * const { mutate } = icpTransferMutation.useMutation({
+   *   invalidateQueries: [userBalanceQuery], // Auto-invalidate after success!
+   * })
+   */
+  useMutation: (
+    options?: MutationHookOptions<A, M, T>
+  ) => UseMutationResult<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    ReactorArgs<A, M, T>
+  >
+
+  /** Execute the update call directly (outside of React) */
+  execute: (args: ReactorArgs<A, M, T>) => Promise<ReactorReturnOk<A, M, T>>
+}

package/src/validation.ts

@@ -0,0 +1,202 @@
+/**
+ * Validation utilities for React
+ *
+ * Helpers for working with ValidationError in React components,
+ * especially for form integration.
+ */
+
+import {
+  ValidationError,
+  isValidationError,
+  ValidationIssue,
+} from "@ic-reactor/core"
+
+// Re-export for convenience
+export { isValidationError, ValidationError }
+export type { ValidationIssue }
+
+/**
+ * A map of field names to error messages.
+ * This format is compatible with most form libraries.
+ */
+export type FieldErrors = Record<string, string>
+
+/**
+ * A map of field names to arrays of error messages.
+ * Use when you need to show multiple errors per field.
+ */
+export type FieldErrorsMultiple = Record<string, string[]>
+
+/**
+ * Options for mapValidationErrors
+ */
+export interface MapValidationErrorsOptions {
+  /**
+   * If true, returns all messages for each field as an array.
+   * If false (default), returns only the first message for each field.
+   */
+  multiple?: boolean
+}
+
+/**
+ * Maps validation error issues to a simple field -> message object.
+ * Returns the first error message for each field path.
+ *
+ * @example
+ * ```tsx
+ * const { mutate } = useActorMutation({
+ *   functionName: "transfer",
+ *   onError: (error) => {
+ *     if (isValidationError(error)) {
+ *       const fieldErrors = mapValidationErrors(error)
+ *       // { to: "Recipient is required", amount: "Must be a number" }
+ *
+ *       // Use with React Hook Form
+ *       Object.entries(fieldErrors).forEach(([field, message]) => {
+ *         form.setError(field, { message })
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export function mapValidationErrors(error: ValidationError): FieldErrors
+export function mapValidationErrors(
+  error: ValidationError,
+  options: { multiple: true }
+): FieldErrorsMultiple
+export function mapValidationErrors(
+  error: ValidationError,
+  options: { multiple: false }
+): FieldErrors
+export function mapValidationErrors(
+  error: ValidationError,
+  options?: MapValidationErrorsOptions
+): FieldErrors | FieldErrorsMultiple {
+  if (options?.multiple) {
+    const result: FieldErrorsMultiple = {}
+    for (const issue of error.issues) {
+      const fieldName = String(issue.path[0] ?? "")
+      if (!result[fieldName]) {
+        result[fieldName] = []
+      }
+      result[fieldName].push(issue.message)
+    }
+    return result
+  }
+
+  const result: FieldErrors = {}
+  for (const issue of error.issues) {
+    const fieldName = String(issue.path[0] ?? "")
+    if (!result[fieldName]) {
+      result[fieldName] = issue.message
+    }
+  }
+  return result
+}
+
+/**
+ * Gets error message for a specific field from a ValidationError.
+ * Returns undefined if no error exists for that field.
+ *
+ * @example
+ * ```tsx
+ * if (isValidationError(error)) {
+ *   const toError = getFieldError(error, "to")
+ *   const amountError = getFieldError(error, "amount")
+ * }
+ * ```
+ */
+export function getFieldError(
+  error: ValidationError,
+  fieldName: string
+): string | undefined {
+  const issue = error.issues.find((i) => String(i.path[0]) === fieldName)
+  return issue?.message
+}
+
+/**
+ * Gets all error messages for a specific field from a ValidationError.
+ * Returns empty array if no errors exist for that field.
+ *
+ * @example
+ * ```tsx
+ * if (isValidationError(error)) {
+ *   const amountErrors = getFieldErrors(error, "amount")
+ *   // ["Amount is required", "Amount must be positive"]
+ * }
+ * ```
+ */
+export function getFieldErrors(
+  error: ValidationError,
+  fieldName: string
+): string[] {
+  return error.issues
+    .filter((i) => String(i.path[0]) === fieldName)
+    .map((i) => i.message)
+}
+
+/**
+ * Checks if a given error is a ValidationError and optionally
+ * extracts field errors in one step.
+ *
+ * @example
+ * ```tsx
+ * const { mutateAsync } = useActorMutation({ functionName: "transfer" })
+ *
+ * const handleSubmit = async (data) => {
+ *   try {
+ *     await mutateAsync([data])
+ *   } catch (error) {
+ *     const fieldErrors = extractValidationErrors(error)
+ *     if (fieldErrors) {
+ *       // Handle validation errors
+ *       Object.entries(fieldErrors).forEach(([field, message]) => {
+ *         form.setError(field, { message })
+ *       })
+ *     } else {
+ *       // Handle other errors
+ *       console.error(error)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function extractValidationErrors(error: unknown): FieldErrors | null {
+  if (isValidationError(error)) {
+    return mapValidationErrors(error)
+  }
+  return null
+}
+
+/**
+ * React hook-friendly error handler that extracts validation errors.
+ * Returns a callback suitable for onError handlers.
+ *
+ * @example
+ * ```tsx
+ * const [fieldErrors, setFieldErrors] = useState<FieldErrors>({})
+ *
+ * const { mutate } = useActorMutation({
+ *   functionName: "transfer",
+ *   onError: handleValidationError(setFieldErrors),
+ * })
+ *
+ * // In JSX
+ * <input name="to" />
+ * {fieldErrors.to && <span className="error">{fieldErrors.to}</span>}
+ * ```
+ */
+export function handleValidationError(
+  setFieldErrors: (errors: FieldErrors) => void,
+  onOtherError?: (error: Error) => void
+): (error: Error) => void {
+  return (error: Error) => {
+    const fieldErrors = extractValidationErrors(error)
+    if (fieldErrors) {
+      setFieldErrors(fieldErrors)
+    } else if (onOtherError) {
+      onOtherError(error)
+    }
+  }
+}