@ic-reactor/react 3.6.0 → 3.7.0

package/src/createInfiniteQuery.ts

@@ -29,6 +29,7 @@ import type {
   BaseActor,
   TransformKey,
   ReactorReturnOk,
+  ReactorQueryData,
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import {
@@ -43,22 +44,22 @@ import {
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
 import { NoInfer } from "./types"
-import { mergeFactoryQueryKey } from "./utils"
+import { mergeFactoryQueryKey, normalizeQueryData } from "./utils"
 
 type InfiniteQueryFactoryFn<
-  A,
-  M extends FunctionName<A>,
-  T extends TransformKey,
+  Service,
+  Method extends FunctionName<Service>,
+  Transform extends TransformKey,
   TPageParam,
-  TSelected,
+  Selected,
 > = {
   (
-    getArgs: (pageParam: TPageParam) => ReactorArgs<A, M, T>
+    getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ): InfiniteQueryResult<
-    InfiniteQueryPageData<A, M, T>,
+    InfiniteQueryPageData<Service, Method, Transform>,
     TPageParam,
-    TSelected,
-    InfiniteQueryError<A, M, T>
+    Selected,
+    InfiniteQueryError<Service, Method, Transform>
   >
 }
 
@@ -68,17 +69,17 @@ type InfiniteQueryFactoryFn<
 
 /** The raw page data type returned by the query function */
 export type InfiniteQueryPageData<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
-> = ReactorReturnOk<A, M, T>
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+> = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
 
 /** The error type for infinite queries */
 export type InfiniteQueryError<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
-> = ReactorReturnErr<A, M, T>
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+> = ReactorReturnErr<Service, Method, Transform>
 
 // ============================================================================
 // Configuration Types
@@ -90,30 +91,33 @@ export type InfiniteQueryError<
  * infinite-query options at the create level (e.g. refetchInterval,
  * refetchOnMount, refetchOnWindowFocus, retry, gcTime, networkMode).
  *
- * @template A - The actor interface type
- * @template M - The method name on the actor
- * @template T - The transformation key (identity, display, etc.)
+ * @template Service - The actor interface type
+ * @template Method - The method name on the actor
+ * @template Transform - The transformation key (identity, display, etc.)
  * @template TPageParam - The type of the page parameter
- * @template TSelected - The type returned after select transformation
+ * @template Selected - The type returned after select transformation
  */
 export interface InfiniteQueryConfig<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
-  TSelected = InfiniteData<InfiniteQueryPageData<A, M, T>, TPageParam>,
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
 > extends Omit<
   InfiniteQueryObserverOptions<
-    InfiniteQueryPageData<A, M, T>,
-    InfiniteQueryError<A, M, T>,
-    TSelected,
+    InfiniteQueryPageData<Service, Method, Transform>,
+    InfiniteQueryError<Service, Method, Transform>,
+    Selected,
     QueryKey,
     TPageParam
   >,
   "queryKey" | "queryFn"
 > {
   /** The method to call on the canister */
-  functionName: M
+  functionName: Method
   /** Call configuration for the actor method */
   callConfig?: CallConfig
   /** Custom query key (optional, auto-generated if not provided) */
@@ -121,18 +125,18 @@ export interface InfiniteQueryConfig<
   /** Initial page parameter */
   initialPageParam: TPageParam
   /** Function to get args from page parameter */
-  getArgs: (pageParam: TPageParam) => ReactorArgs<A, M, T>
+  getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   /** Function to determine next page parameter */
   getNextPageParam: (
-    lastPage: InfiniteQueryPageData<A, M, T>,
-    allPages: InfiniteQueryPageData<A, M, T>[],
+    lastPage: InfiniteQueryPageData<Service, Method, Transform>,
+    allPages: InfiniteQueryPageData<Service, Method, Transform>[],
     lastPageParam: TPageParam,
     allPageParams: TPageParam[]
   ) => TPageParam | undefined | null
   /** Function to determine previous page parameter (for bi-directional) */
   getPreviousPageParam?: (
-    firstPage: InfiniteQueryPageData<A, M, T>,
-    allPages: InfiniteQueryPageData<A, M, T>[],
+    firstPage: InfiniteQueryPageData<Service, Method, Transform>,
+    allPages: InfiniteQueryPageData<Service, Method, Transform>[],
     firstPageParam: TPageParam,
     allPageParams: TPageParam[]
   ) => TPageParam | undefined | null
@@ -142,19 +146,25 @@ export interface InfiniteQueryConfig<
  * Configuration for createActorInfiniteQueryFactory (without initialPageParam, getArgs determined at call time).
  */
 export type InfiniteQueryFactoryConfig<
-  A = BaseActor,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
-  TSelected = InfiniteData<InfiniteQueryPageData<A, M, T>, TPageParam>,
-> = Omit<InfiniteQueryConfig<A, M, T, TPageParam, TSelected>, "getArgs"> & {
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
+> = Omit<
+  InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
+  "getArgs"
+> & {
   /**
    * Optional key-args derivation for factory calls.
    * Receives the resolved args from `getArgs(initialPageParam)` and should return
    * a stable serializable representation of the logical query identity
    * (typically excluding pagination/cursor fields).
    */
-  getKeyArgs?: (args: ReactorArgs<A, M, T>) => unknown
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
 }
 
 // ============================================================================
@@ -167,16 +177,16 @@ export type InfiniteQueryFactoryConfig<
 export interface UseInfiniteQueryWithSelect<
   TPageData,
   TPageParam,
-  TSelected = InfiniteData<TPageData, TPageParam>,
+  Selected = InfiniteData<TPageData, TPageParam>,
   TError = Error,
 > {
-  // Overload 1: Without select - returns TSelected
+  // Overload 1: Without select - returns Selected
   (
     options?: Omit<
       UseInfiniteQueryOptions<
         TPageData,
         TError,
-        TSelected,
+        Selected,
         QueryKey,
         TPageParam
       >,
@@ -187,10 +197,10 @@ export interface UseInfiniteQueryWithSelect<
       | "getNextPageParam"
       | "getPreviousPageParam"
     >
-  ): UseInfiniteQueryResult<TSelected, TError>
+  ): UseInfiniteQueryResult<Selected, TError>
 
   // Overload 2: With select - chains on top and returns TFinal
-  <TFinal = TSelected>(
+  <TFinal = Selected>(
     options: Omit<
       UseInfiniteQueryOptions<TPageData, TError, TFinal, QueryKey, TPageParam>,
       | "queryKey"
@@ -200,7 +210,7 @@ export interface UseInfiniteQueryWithSelect<
       | "getNextPageParam"
       | "getPreviousPageParam"
     > & {
-      select: (data: TSelected) => TFinal
+      select: (data: Selected) => TFinal
     }
   ): UseInfiniteQueryResult<TFinal, TError>
 }
@@ -214,23 +224,23 @@ export interface UseInfiniteQueryWithSelect<
  *
  * @template TPageData - The raw page data type
  * @template TPageParam - The page parameter type
- * @template TSelected - The type after select transformation
+ * @template Selected - The type after select transformation
  * @template TError - The error type
  */
 export interface InfiniteQueryResult<
   TPageData,
   TPageParam,
-  TSelected = InfiniteData<TPageData, TPageParam>,
+  Selected = InfiniteData<TPageData, TPageParam>,
   TError = Error,
 > {
   /** Fetch first page in loader (uses ensureQueryData for cache-first) */
-  fetch: () => Promise<TSelected>
+  fetch: () => Promise<Selected>
 
   /** React hook for components - supports pagination */
   useInfiniteQuery: UseInfiniteQueryWithSelect<
     TPageData,
     TPageParam,
-    TSelected,
+    Selected,
     TError
   >
 
@@ -245,8 +255,8 @@ export interface InfiniteQueryResult<
    * Returns undefined if data is not in cache.
    */
   getCacheData: {
-    (): TSelected | undefined
-    <TFinal>(select: (data: TSelected) => TFinal): TFinal | undefined
+    (): Selected | undefined
+    <TFinal>(select: (data: Selected) => TFinal): TFinal | undefined
   }
 }
 
@@ -255,22 +265,25 @@ export interface InfiniteQueryResult<
 // ============================================================================
 
 const createInfiniteQueryImpl = <
-  A,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
   TPageParam = unknown,
-  TSelected = InfiniteData<InfiniteQueryPageData<A, M, T>, TPageParam>,
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
 >(
-  reactor: Reactor<A, T>,
-  config: InfiniteQueryConfig<A, M, T, TPageParam, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>
 ): InfiniteQueryResult<
-  InfiniteQueryPageData<A, M, T>,
+  InfiniteQueryPageData<Service, Method, Transform>,
   TPageParam,
-  TSelected,
-  InfiniteQueryError<A, M, T>
+  Selected,
+  InfiniteQueryError<Service, Method, Transform>
 > => {
-  type TPageData = InfiniteQueryPageData<A, M, T>
-  type TError = InfiniteQueryError<A, M, T>
+  type TPageData = InfiniteQueryPageData<Service, Method, Transform>
+  type TError = InfiniteQueryError<Service, Method, Transform>
   type TInfiniteData = InfiniteData<TPageData, TPageParam>
 
   const {
@@ -310,7 +323,9 @@ const createInfiniteQueryImpl = <
       args,
       callConfig,
     })
-    return result
+    return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
+      result as ReactorReturnOk<Service, Method, Transform>
+    )
   }
 
   // Get infinite query options for fetchInfiniteQuery
@@ -328,14 +343,13 @@ const createInfiniteQueryImpl = <
   })
 
   // Fetch function for loaders (cache-first, fetches first page)
-  const fetch = async (): Promise<TSelected> => {
+  const fetch = async (): Promise<Selected> => {
     // Check cache first
     const cachedData = reactor.queryClient.getQueryData(getQueryKey()) as
-      | TInfiniteData
-      | undefined
+      TInfiniteData | undefined
 
     if (cachedData !== undefined) {
-      return select ? select(cachedData) : (cachedData as TSelected)
+      return select ? select(cachedData) : (cachedData as Selected)
     }
 
     // Fetch if not in cache
@@ -344,14 +358,14 @@ const createInfiniteQueryImpl = <
     )
 
     // Result is already InfiniteData format
-    return select ? select(result) : (result as unknown as TSelected)
+    return select ? select(result) : (result as unknown as Selected)
   }
 
   // Implementation
   const useInfiniteQueryHook: UseInfiniteQueryWithSelect<
     TPageData,
     TPageParam,
-    TSelected,
+    Selected,
     TError
   > = (options: any): any => {
     // Chain the selects: raw -> config.select -> options.select
@@ -387,7 +401,7 @@ const createInfiniteQueryImpl = <
   }
 
   // Get data from cache without fetching
-  const getCacheData: any = (selectFn?: (data: TSelected) => any) => {
+  const getCacheData: any = (selectFn?: (data: Selected) => any) => {
     const queryKey = getQueryKey()
     const cachedRawData = reactor.queryClient.getQueryData(
       queryKey
@@ -400,7 +414,7 @@ const createInfiniteQueryImpl = <
     // Apply config.select to raw cache data
     const selectedData = (
       select ? select(cachedRawData) : cachedRawData
-    ) as TSelected
+    ) as Selected
 
     // Apply optional select parameter
     if (selectFn) {
@@ -424,23 +438,38 @@ const createInfiniteQueryImpl = <
 // ============================================================================
 
 export function createInfiniteQuery<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
   TPageParam = unknown,
-  TSelected = InfiniteData<InfiniteQueryPageData<A, M, T>, TPageParam>,
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
 >(
-  reactor: Reactor<A, T>,
-  config: InfiniteQueryConfig<NoInfer<A>, M, T, TPageParam, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: InfiniteQueryConfig<
+    NoInfer<Service>,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  >
 ): InfiniteQueryResult<
-  InfiniteQueryPageData<A, M, T>,
+  InfiniteQueryPageData<Service, Method, Transform>,
   TPageParam,
-  TSelected,
-  InfiniteQueryError<A, M, T>
+  Selected,
+  InfiniteQueryError<Service, Method, Transform>
 > {
   return createInfiniteQueryImpl(
     reactor,
-    config as InfiniteQueryConfig<A, M, T, TPageParam, TSelected>
+    config as InfiniteQueryConfig<
+      Service,
+      Method,
+      Transform,
+      TPageParam,
+      Selected
+    >
   )
 }
 
@@ -452,11 +481,11 @@ export function createInfiniteQuery<
  * Create an infinite query factory that accepts getArgs at call time.
  * Useful when pagination logic varies by context.
  *
- * @template A - The actor interface type
- * @template M - The method name on the actor
- * @template T - The transformation key (identity, display, etc.)
+ * @template Service - The actor interface type
+ * @template Method - The method name on the actor
+ * @template Transform - The transformation key (identity, display, etc.)
  * @template TPageParam - The page parameter type
- * @template TSelected - The type returned after select transformation
+ * @template Selected - The type returned after select transformation
  *
  * @param reactor - The Reactor instance
  * @param config - Infinite query configuration (without getArgs)
@@ -479,25 +508,52 @@ export function createInfiniteQuery<
  */
 
 export function createInfiniteQueryFactory<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
   TPageParam = unknown,
-  TSelected = InfiniteData<InfiniteQueryPageData<A, M, T>, TPageParam>,
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
 >(
-  reactor: Reactor<A, T>,
-  config: InfiniteQueryFactoryConfig<NoInfer<A>, M, T, TPageParam, TSelected>
-): InfiniteQueryFactoryFn<A, M, T, TPageParam, TSelected> {
-  const factory: InfiniteQueryFactoryFn<A, M, T, TPageParam, TSelected> = (
-    getArgs: (pageParam: TPageParam) => ReactorArgs<A, M, T>
+  reactor: Reactor<Service, Transform>,
+  config: InfiniteQueryFactoryConfig<
+    NoInfer<Service>,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  >
+): InfiniteQueryFactoryFn<Service, Method, Transform, TPageParam, Selected> {
+  const factory: InfiniteQueryFactoryFn<
+    Service,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  > = (
+    getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ) => {
     const initialArgs = getArgs(config.initialPageParam)
     const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
     const queryKey = mergeFactoryQueryKey(config.queryKey, undefined, keyArgs)
 
-    return createInfiniteQueryImpl<A, M, T, TPageParam, TSelected>(reactor, {
+    return createInfiniteQueryImpl<
+      Service,
+      Method,
+      Transform,
+      TPageParam,
+      Selected
+    >(reactor, {
       ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(
-        config as InfiniteQueryFactoryConfig<A, M, T, TPageParam, TSelected>
+        config as InfiniteQueryFactoryConfig<
+          Service,
+          Method,
+          Transform,
+          TPageParam,
+          Selected
+        >
       ),
       queryKey,
       getArgs,

package/src/createMutation.ts

@@ -3,6 +3,8 @@
  *
  * Creates unified mutation hooks for any canister method.
  * Works with any Reactor instance.
+ * Use this when one mutation should support both React hooks and imperative
+ * execution outside React.
  *
  * @example
  * const transferMutation = createMutation(reactor, {
@@ -12,6 +14,15 @@
  *
  * // In component
  * const { mutate, isPending } = transferMutation.useMutation()
+ *
+ * @example
+ * const transferMutation = createMutation(reactor, {
+ *   functionName: "transfer",
+ *   onCanisterError: (err) => console.error(err.code),
+ * })
+ *
+ * // Outside React (loader/service/script)
+ * await transferMutation.execute([{ to: "aaaaa-aa", amount: "1000" }])
  */
 
 import { useMutation } from "@tanstack/react-query"
@@ -51,13 +62,13 @@ async function invalidateAll(
 // ============================================================================
 
 const createMutationImpl = <
-  A,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
+  Service,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
 >(
-  reactor: Reactor<A, T>,
-  config: MutationConfig<A, M, T>
-): MutationResult<A, M, T> => {
+  reactor: Reactor<Service, Transform>,
+  config: MutationConfig<Service, Method, Transform>
+): MutationResult<Service, Method, Transform> => {
   const {
     functionName,
     callConfig,
@@ -74,8 +85,8 @@ const createMutationImpl = <
    * and there is no double-invalidation.
    */
   const callFn = (
-    args: ReactorArgs<A, M, T>
-  ): Promise<ReactorReturnOk<A, M, T>> =>
+    args: ReactorArgs<Service, Method, Transform>
+  ): Promise<ReactorReturnOk<Service, Method, Transform>> =>
     reactor.callMethod({ functionName, args, callConfig })
 
   /**
@@ -84,8 +95,8 @@ const createMutationImpl = <
    * Use this in route loaders, scripts, or server-side code.
    */
   const execute = async (
-    args: ReactorArgs<A, M, T>
-  ): Promise<ReactorReturnOk<A, M, T>> => {
+    args: ReactorArgs<Service, Method, Transform>
+  ): Promise<ReactorReturnOk<Service, Method, Transform>> => {
     const result = await callFn(args)
     if (factoryInvalidateQueries) {
       await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
@@ -94,7 +105,9 @@ const createMutationImpl = <
   }
 
   // Hook implementation
-  const useMutationHook = (options?: MutationHookOptions<A, M, T>) => {
+  const useMutationHook = (
+    options?: MutationHookOptions<Service, Method, Transform>
+  ) => {
     const baseOptions = reactor.getQueryOptions({ functionName })
     const {
       invalidateQueries: hookInvalidateQueries,
@@ -145,12 +158,15 @@ const createMutationImpl = <
 // ============================================================================
 
 export function createMutation<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
 >(
-  reactor: Reactor<A, T>,
-  config: MutationConfig<NoInfer<A>, M, T>
-): MutationResult<A, M, T> {
-  return createMutationImpl(reactor, config as MutationConfig<A, M, T>)
+  reactor: Reactor<Service, Transform>,
+  config: MutationConfig<NoInfer<Service>, Method, Transform>
+): MutationResult<Service, Method, Transform> {
+  return createMutationImpl(
+    reactor,
+    config as MutationConfig<Service, Method, Transform>
+  )
 }