@ic-reactor/react 3.6.0 → 3.8.0

package/src/hooks/useActorInfiniteQuery.ts

@@ -12,36 +12,41 @@ import {
   TransformKey,
   ReactorArgs,
   ReactorReturnOk,
+  ReactorQueryData,
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import { normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorInfiniteQuery hook.
  * Extends react-query's UseInfiniteQueryOptions with custom reactor params.
  */
 export interface UseActorInfiniteQueryParameters<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
-  TSelected = InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 > extends Omit<
   UseInfiniteQueryOptions<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    TSelected,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    ReactorReturnErr<Service, Method, Transform>,
+    Selected,
     QueryKey,
     TPageParam
   >,
   "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"
 > {
   /** The reactor instance to use for method calls */
-  reactor: Reactor<A, T>
+  reactor: Reactor<Service, Transform>
   /** The method name to call on the canister */
-  functionName: M
+  functionName: Method
   /** Function to get args from page parameter */
-  getArgs: (pageParam: TPageParam) => ReactorArgs<A, M, T>
+  getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   /** Agent call configuration (effectiveCanisterId, etc.) */
   callConfig?: CallConfig
   /** Custom query key (auto-generated if not provided) */
@@ -50,28 +55,34 @@ export interface UseActorInfiniteQueryParameters<
   initialPageParam: TPageParam
   /** Function to determine next page parameter */
   getNextPageParam: (
-    lastPage: ReactorReturnOk<A, M, T>,
-    allPages: ReactorReturnOk<A, M, T>[],
+    lastPage: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    allPages: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>[],
     lastPageParam: TPageParam,
     allPageParams: TPageParam[]
   ) => TPageParam | undefined | null
 }
 
 export type UseActorInfiniteQueryConfig<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
-> = Omit<UseActorInfiniteQueryParameters<A, M, T, TPageParam>, "reactor">
+> = Omit<
+  UseActorInfiniteQueryParameters<Service, Method, Transform, TPageParam>,
+  "reactor"
+>
 
 export type UseActorInfiniteQueryResult<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
 > = UseInfiniteQueryResult<
-  InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
-  ReactorReturnErr<A, M, T>
+  InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
+  ReactorReturnErr<Service, Method, Transform>
 >
 
 /**
@@ -87,9 +98,9 @@ export type UseActorInfiniteQueryResult<
  * })
  */
 export const useActorInfiniteQuery = <
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
 >({
   reactor,
@@ -99,11 +110,11 @@ export const useActorInfiniteQuery = <
   queryKey,
   ...options
 }: UseActorInfiniteQueryParameters<
-  A,
-  M,
-  T,
+  Service,
+  Method,
+  Transform,
   TPageParam
->): UseActorInfiniteQueryResult<A, M, T, TPageParam> => {
+>): UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam> => {
   // Always pass queryKey through generateQueryKey so it is merged with the
   // reactor/function identity. Using the custom key verbatim would cause cache
   // collisions if two different actors or methods share the same key string.
@@ -116,11 +127,14 @@ export const useActorInfiniteQuery = <
   const queryFn = useCallback(
     async ({ pageParam }: { pageParam: TPageParam }) => {
       const args = getArgs(pageParam)
-      return reactor.callMethod({
+      const result = await reactor.callMethod({
         functionName,
         args,
         callConfig,
       })
+      return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
+        result as ReactorReturnOk<Service, Method, Transform>
+      )
     },
     [reactor, functionName, getArgs, callConfig]
   )
@@ -132,5 +146,5 @@ export const useActorInfiniteQuery = <
       ...options,
     } as any,
     reactor.queryClient
-  ) as UseActorInfiniteQueryResult<A, M, T, TPageParam>
+  ) as UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam>
 }

package/src/hooks/useActorMethod.ts

@@ -28,27 +28,27 @@ import { CallConfig } from "@icp-sdk/core/agent"
  * Mutation-specific options (like invalidateQueries) only apply to mutation methods.
  */
 export interface UseActorMethodParameters<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 > extends Omit<
   QueryObserverOptions<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnOk<A, M, T>,
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>,
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnOk<Service, Method, Transform>,
     QueryKey
   >,
   "queryKey" | "queryFn"
 > {
   /** The reactor instance to use for method calls */
-  reactor: Reactor<A, T>
+  reactor: Reactor<Service, Transform>
 
   /** The method name to call on the canister */
-  functionName: M
+  functionName: Method
 
   /** Arguments to pass to the method (optional for parameterless methods) */
-  args?: ReactorArgs<A, M, T>
+  args?: ReactorArgs<Service, Method, Transform>
 
   /** Agent call configuration (effectiveCanisterId, etc.) */
   callConfig?: CallConfig
@@ -60,13 +60,13 @@ export interface UseActorMethodParameters<
    * Callback when the method call succeeds.
    * Works for both query and mutation methods.
    */
-  onSuccess?: (data: ReactorReturnOk<A, M, T>) => void
+  onSuccess?: (data: ReactorReturnOk<Service, Method, Transform>) => void
 
   /**
    * Callback when the method call fails.
    * Works for both query and mutation methods.
    */
-  onError?: (error: ReactorReturnErr<A, M, T>) => void
+  onError?: (error: ReactorReturnErr<Service, Method, Transform>) => void
 
   /**
    * Query keys to invalidate after a successful mutation.
@@ -80,22 +80,22 @@ export interface UseActorMethodParameters<
  * For use with createActorHooks.
  */
 export type UseActorMethodConfig<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
-> = Omit<UseActorMethodParameters<A, M, T>, "reactor">
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+> = Omit<UseActorMethodParameters<Service, Method, Transform>, "reactor">
 
 /**
  * Result type for useActorMethod hook.
  * Provides a unified interface for both query and mutation methods.
  */
 export interface UseActorMethodResult<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 > {
   /** The returned data from the method call */
-  data: ReactorReturnOk<A, M, T> | undefined
+  data: ReactorReturnOk<Service, Method, Transform> | undefined
 
   /** Whether the method is currently executing */
   isLoading: boolean
@@ -110,7 +110,7 @@ export interface UseActorMethodResult<
   isSuccess: boolean
 
   /** The error if one occurred */
-  error: ReactorReturnErr<A, M, T> | null
+  error: ReactorReturnErr<Service, Method, Transform> | null
 
   /** Whether this is a query method (true) or mutation method (false) */
   isQuery: boolean
@@ -124,8 +124,8 @@ export interface UseActorMethodResult<
    * For mutations: executes the mutation with the provided args
    */
   call: (
-    args?: ReactorArgs<A, M, T>
-  ) => Promise<ReactorReturnOk<A, M, T> | undefined>
+    args?: ReactorArgs<Service, Method, Transform>
+  ) => Promise<ReactorReturnOk<Service, Method, Transform> | undefined>
 
   /**
    * Reset the state (clear data and error).
@@ -137,20 +137,22 @@ export interface UseActorMethodResult<
   /**
    * For queries only: Refetch the query
    */
-  refetch: () => Promise<ReactorReturnOk<A, M, T> | undefined>
+  refetch: () => Promise<
+    ReactorReturnOk<Service, Method, Transform> | undefined
+  >
 
   // Expose underlying results for advanced use cases
   /** The raw query result (only available for query methods) */
   queryResult?: UseQueryResult<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>
   >
 
   /** The raw mutation result (only available for mutation methods) */
   mutationResult?: UseMutationResult<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    ReactorArgs<A, M, T>
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>,
+    ReactorArgs<Service, Method, Transform>
   >
 }
 
@@ -159,9 +161,9 @@ export interface UseActorMethodResult<
  * both query and mutation methods based on the Candid interface.
  */
 export function useActorMethod<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 >({
   reactor,
   functionName,
@@ -173,7 +175,11 @@ export function useActorMethod<
   onError,
   invalidateQueries,
   ...queryOptions
-}: UseActorMethodParameters<A, M, T>): UseActorMethodResult<A, M, T> {
+}: UseActorMethodParameters<Service, Method, Transform>): UseActorMethodResult<
+  Service,
+  Method,
+  Transform
+> {
   // Determine if this is a query method by checking the IDL
   const isQuery = useMemo(() => {
     if (!reactor) throw new Error("Reactor instance is required")
@@ -199,8 +205,8 @@ export function useActorMethod<
   // ============================================================================
 
   const queryResult = useQuery<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>
   >(
     {
       queryKey,
@@ -214,7 +220,7 @@ export function useActorMethod<
           onSuccess?.(result)
           return result
         } catch (error) {
-          onError?.(error as ReactorReturnErr<A, M, T>)
+          onError?.(error as ReactorReturnErr<Service, Method, Transform>)
           throw error
         }
       },
@@ -229,9 +235,9 @@ export function useActorMethod<
   // ============================================================================
 
   const mutationResult = useMutation<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    ReactorArgs<A, M, T>
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>,
+    ReactorArgs<Service, Method, Transform>
   >(
     {
       mutationKey: queryKey,
@@ -265,8 +271,8 @@ export function useActorMethod<
 
   const call = useCallback(
     async (
-      callArgs?: ReactorArgs<A, M, T>
-    ): Promise<ReactorReturnOk<A, M, T> | undefined> => {
+      callArgs?: ReactorArgs<Service, Method, Transform>
+    ): Promise<ReactorReturnOk<Service, Method, Transform> | undefined> => {
       if (isQuery) {
         // For queries, refetch with new args if provided
         if (callArgs !== undefined) {
@@ -284,7 +290,7 @@ export function useActorMethod<
             onSuccess?.(result)
             return result
           } catch (error) {
-            onError?.(error as ReactorReturnErr<A, M, T>)
+            onError?.(error as ReactorReturnErr<Service, Method, Transform>)
             return undefined
           }
         }
@@ -294,7 +300,7 @@ export function useActorMethod<
       } else {
         // For mutations, execute with provided args
         return mutationResult
-          .mutateAsync(callArgs as ReactorArgs<A, M, T>)
+          .mutateAsync(callArgs as ReactorArgs<Service, Method, Transform>)
           .catch(() => undefined)
       }
     },
@@ -353,7 +359,7 @@ export function useActorMethod<
       reset,
       refetch,
       queryResult,
-    } as UseActorMethodResult<A, M, T>
+    } as UseActorMethodResult<Service, Method, Transform>
   } else {
     return {
       data: mutationResult.data,
@@ -368,7 +374,7 @@ export function useActorMethod<
       reset,
       refetch,
       mutationResult,
-    } as UseActorMethodResult<A, M, T>
+    } as UseActorMethodResult<Service, Method, Transform>
   }
 }
 
@@ -381,20 +387,23 @@ export function useActorMethod<
  * ```
  */
 export function createActorMethodHooks<
-  A = BaseActor,
-  T extends TransformKey = "candid",
->(reactor: Reactor<A, T>) {
+  Service = BaseActor,
+  Transform extends TransformKey = "candid",
+>(reactor: Reactor<Service, Transform>) {
   return {
     /**
      * Hook for calling methods on the bound reactor.
      */
-    useMethod: <M extends FunctionName<A>>(
-      config: Omit<UseActorMethodParameters<A, M, T>, "reactor">
+    useMethod: <Method extends FunctionName<Service>>(
+      config: Omit<
+        UseActorMethodParameters<Service, Method, Transform>,
+        "reactor"
+      >
     ) =>
       useActorMethod({ ...config, reactor } as UseActorMethodParameters<
-        A,
-        M,
-        T
+        Service,
+        Method,
+        Transform
       >),
   }
 }

package/src/hooks/useActorMutation.ts

@@ -21,19 +21,19 @@ import {
 import { CallConfig } from "@icp-sdk/core/agent"
 
 export interface UseActorMutationParameters<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 > extends Omit<
   UseMutationOptions<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    ReactorArgs<A, M, T>
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>,
+    ReactorArgs<Service, Method, Transform>
   >,
   "mutationFn"
 > {
-  reactor: Reactor<A, T>
-  functionName: M
+  reactor: Reactor<Service, Transform>
+  functionName: Method
   callConfig?: CallConfig
   invalidateQueries?: QueryKey[]
   /**
@@ -43,30 +43,34 @@ export interface UseActorMutationParameters<
    */
   onCanisterError?: (
     error: CanisterError<
-      TransformReturnRegistry<ErrResult<ActorMethodReturnType<A[M]>>>[T]
+      TransformReturnRegistry<
+        ErrResult<ActorMethodReturnType<Service[Method]>>
+      >[Transform]
     >,
-    variables: ReactorArgs<A, M, T>
+    variables: ReactorArgs<Service, Method, Transform>
   ) => void
 }
 
 export type UseActorMutationConfig<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
-> = Omit<UseActorMutationParameters<A, M, T>, "reactor">
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+> = Omit<UseActorMutationParameters<Service, Method, Transform>, "reactor">
 
 export type UseActorMutationResult<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 > = UseMutationResult<
-  ReactorReturnOk<A, M, T>,
-  ReactorReturnErr<A, M, T>,
-  ReactorArgs<A, M, T>
+  ReactorReturnOk<Service, Method, Transform>,
+  ReactorReturnErr<Service, Method, Transform>,
+  ReactorArgs<Service, Method, Transform>
 >
 
 /**
  * Hook for executing mutation calls on a canister.
+ * Use this for component-level mutation flows.
+ * For non-React usage, prefer `createMutation(...).execute(args)`.
  *
  * @example
  * const { mutate, isPending } = useActorMutation({
@@ -75,11 +79,20 @@ export type UseActorMutationResult<
  *   onSuccess: () => console.log("Success!"),
  *   onCanisterError: (err) => console.error("Canister Err:", err.code),
  * })
+ *
+ * @example
+ * const transferMutation = createMutation(reactor, {
+ *   functionName: "transfer",
+ *   onCanisterError: (err) => console.error(err.code),
+ * })
+ *
+ * // Non-React execution path
+ * await transferMutation.execute([{ to: "aaaaa-aa", amount: "100" }])
  */
 export const useActorMutation = <
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 >({
   reactor,
   functionName,
@@ -89,9 +102,13 @@ export const useActorMutation = <
   onCanisterError,
   callConfig,
   ...options
-}: UseActorMutationParameters<A, M, T>): UseActorMutationResult<A, M, T> => {
+}: UseActorMutationParameters<
+  Service,
+  Method,
+  Transform
+>): UseActorMutationResult<Service, Method, Transform> => {
   const mutationFn = useCallback(
-    async (args: ReactorArgs<A, M, T>) =>
+    async (args: ReactorArgs<Service, Method, Transform>) =>
       reactor.callMethod({ functionName, callConfig, args }),
     [reactor, functionName, callConfig]
   )
@@ -101,9 +118,9 @@ export const useActorMutation = <
       ...params: Parameters<
         NonNullable<
           UseMutationOptions<
-            ReactorReturnOk<A, M, T>,
-            ReactorReturnErr<A, M, T>,
-            ReactorArgs<A, M, T>
+            ReactorReturnOk<Service, Method, Transform>,
+            ReactorReturnErr<Service, Method, Transform>,
+            ReactorArgs<Service, Method, Transform>
           >["onSuccess"]
         >
       >
@@ -122,8 +139,8 @@ export const useActorMutation = <
 
   const handleError = useCallback(
     (
-      error: ReactorReturnErr<A, M, T>,
-      variables: ReactorArgs<A, M, T>,
+      error: ReactorReturnErr<Service, Method, Transform>,
+      variables: ReactorArgs<Service, Method, Transform>,
       context: unknown,
       mutation: unknown
     ) => {

package/src/hooks/useActorQuery.ts

@@ -11,45 +11,49 @@ import {
   TransformKey,
   ReactorArgs,
   ReactorReturnOk,
+  ReactorQueryData,
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
 
 export interface UseActorQueryParameters<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = ReactorReturnOk<A, M, T>,
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
 > extends Omit<
   QueryObserverOptions<
-    ReactorReturnOk<A, M, T>,
-    ReactorReturnErr<A, M, T>,
-    TSelected,
-    ReactorReturnOk<A, M, T>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    ReactorReturnErr<Service, Method, Transform>,
+    Selected,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     QueryKey
   >,
   "queryKey" | "queryFn"
 > {
-  reactor: Reactor<A, T>
-  functionName: M
-  args?: ReactorArgs<A, M, T>
+  reactor: Reactor<Service, Transform>
+  functionName: Method
+  args?: ReactorArgs<Service, Method, Transform>
   callConfig?: CallConfig
   queryKey?: QueryKey
 }
 
 export type UseActorQueryConfig<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = ReactorReturnOk<A, M, T>,
-> = Omit<UseActorQueryParameters<A, M, T, TSelected>, "reactor">
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+> = Omit<
+  UseActorQueryParameters<Service, Method, Transform, Selected>,
+  "reactor"
+>
 
 export type UseActorQueryResult<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = ReactorReturnOk<A, M, T>,
-> = UseQueryResult<TSelected, ReactorReturnErr<A, M, T>>
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+> = UseQueryResult<Selected, ReactorReturnErr<Service, Method, Transform>>
 
 /**
  * Hook for executing query calls on a canister.
@@ -70,10 +74,10 @@ export type UseActorQueryResult<
  * })
  */
 export const useActorQuery = <
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = ReactorReturnOk<A, M, T>,
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
 >({
   reactor,
   functionName,
@@ -81,16 +85,16 @@ export const useActorQuery = <
   callConfig,
   queryKey: defaultQueryKey,
   ...options
-}: UseActorQueryParameters<A, M, T, TSelected>): UseActorQueryResult<
-  A,
-  M,
-  T,
-  TSelected
-> => {
+}: UseActorQueryParameters<
+  Service,
+  Method,
+  Transform,
+  Selected
+>): UseActorQueryResult<Service, Method, Transform, Selected> => {
   // Memoize query options to prevent unnecessary re-computations
   const { queryKey, queryFn } = useMemo(
     () =>
-      reactor.getQueryOptions<M>({
+      reactor.getQueryOptions<Method>({
         callConfig,
         functionName,
         args,