@ic-reactor/react 3.2.0 → 3.3.1

package/src/createActorHooks.ts

@@ -33,18 +33,17 @@ import {
   UseMutationResult,
   InfiniteData,
 } from "@tanstack/react-query"
-import { createQuery } from "./createQuery"
-import { createSuspenseQuery } from "./createSuspenseQuery"
-import { createInfiniteQuery, InfiniteQueryConfig } from "./createInfiniteQuery"
-import {
-  createSuspenseInfiniteQuery,
-  SuspenseInfiniteQueryConfig,
-} from "./createSuspenseInfiniteQuery"
-import { createMutation } from "./createMutation"
+import { useActorQuery } from "./hooks/useActorQuery"
+import { useActorSuspenseQuery } from "./hooks/useActorSuspenseQuery"
+import { useActorInfiniteQuery } from "./hooks/useActorInfiniteQuery"
+import { useActorSuspenseInfiniteQuery } from "./hooks/useActorSuspenseInfiniteQuery"
+import { useActorMutation } from "./hooks/useActorMutation"
 import {
   useActorMethod,
   UseActorMethodParameters,
 } from "./hooks/useActorMethod"
+import { InfiniteQueryConfig } from "./createInfiniteQuery"
+import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery"
 import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types"
 
 export type ActorHooks<A, T extends TransformKey> = {
@@ -108,33 +107,35 @@ export function createActorHooks<A, T extends TransformKey>(
   reactor: Reactor<A, T>
 ): ActorHooks<A, T> {
   return {
-    useActorQuery: ((config: any) => {
-      const { select, ...options } = config
-      return createQuery(reactor, config).useQuery(options)
-    }) as ActorHooks<A, T>["useActorQuery"],
+    useActorQuery: ((config: any) =>
+      useActorQuery({ ...config, reactor })) as ActorHooks<
+      A,
+      T
+    >["useActorQuery"],
 
-    useActorSuspenseQuery: ((config: any) => {
-      const { select, ...options } = config
-      return createSuspenseQuery(reactor, config).useSuspenseQuery(options)
-    }) as ActorHooks<A, T>["useActorSuspenseQuery"],
+    useActorSuspenseQuery: ((config: any) =>
+      useActorSuspenseQuery({ ...config, reactor })) as ActorHooks<
+      A,
+      T
+    >["useActorSuspenseQuery"],
 
-    useActorInfiniteQuery: ((config) => {
-      const { select, ...options } = config
-      return createInfiniteQuery(reactor, config).useInfiniteQuery(options)
-    }) as ActorHooks<A, T>["useActorInfiniteQuery"],
+    useActorInfiniteQuery: ((config: any) =>
+      useActorInfiniteQuery({ ...config, reactor })) as ActorHooks<
+      A,
+      T
+    >["useActorInfiniteQuery"],
 
-    useActorSuspenseInfiniteQuery: ((config) => {
-      const { select, ...options } = config
-      return createSuspenseInfiniteQuery(
-        reactor,
-        config
-      ).useSuspenseInfiniteQuery(options)
-    }) as ActorHooks<A, T>["useActorSuspenseInfiniteQuery"],
+    useActorSuspenseInfiniteQuery: ((config: any) =>
+      useActorSuspenseInfiniteQuery({ ...config, reactor })) as ActorHooks<
+      A,
+      T
+    >["useActorSuspenseInfiniteQuery"],
 
-    useActorMutation: ((config) => {
-      const { onSuccess, invalidateQueries, ...options } = config
-      return createMutation(reactor, config).useMutation(options)
-    }) as ActorHooks<A, T>["useActorMutation"],
+    useActorMutation: ((config: any) =>
+      useActorMutation({ ...config, reactor })) as ActorHooks<
+      A,
+      T
+    >["useActorMutation"],
 
     useActorMethod: (config) =>
       useActorMethod({ ...config, reactor } as UseActorMethodParameters<

package/src/createInfiniteQuery.ts

@@ -43,8 +43,7 @@ import {
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
 import { NoInfer } from "./types"
-
-const FACTORY_KEY_ARGS_QUERY_KEY = "__ic_reactor_factory_key_args"
+import { mergeFactoryQueryKey } from "./utils"
 
 type InfiniteQueryFactoryFn<
   A,
@@ -63,22 +62,6 @@ type InfiniteQueryFactoryFn<
   >
 }
 
-const mergeFactoryQueryKey = (
-  baseQueryKey?: QueryKey,
-  keyArgs?: unknown
-): QueryKey | undefined => {
-  const merged: unknown[] = []
-
-  if (baseQueryKey) {
-    merged.push(...baseQueryKey)
-  }
-  if (keyArgs !== undefined) {
-    merged.push({ [FACTORY_KEY_ARGS_QUERY_KEY]: keyArgs })
-  }
-
-  return merged.length > 0 ? merged : undefined
-}
-
 // ============================================================================
 // Type Definitions
 // ============================================================================
@@ -510,7 +493,7 @@ export function createInfiniteQueryFactory<
   ) => {
     const initialArgs = getArgs(config.initialPageParam)
     const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
-    const queryKey = mergeFactoryQueryKey(config.queryKey, keyArgs)
+    const queryKey = mergeFactoryQueryKey(config.queryKey, undefined, keyArgs)
 
     return createInfiniteQueryImpl<A, M, T, TPageParam, TSelected>(reactor, {
       ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(

package/src/createMutation.ts

@@ -30,6 +30,22 @@ import type {
   NoInfer,
 } from "./types"
 
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+/** Invalidate a list of query keys in parallel, filtering out undefineds. */
+async function invalidateAll(
+  queryClient: Reactor<any, any>["queryClient"],
+  keys: (import("@tanstack/react-query").QueryKey | undefined)[]
+): Promise<void> {
+  await Promise.all(
+    keys.map((queryKey) =>
+      queryKey ? queryClient.invalidateQueries({ queryKey }) : Promise.resolve()
+    )
+  )
+}
+
 // ============================================================================
 // Internal Implementation
 // ============================================================================
@@ -52,113 +68,80 @@ const createMutationImpl = <
     ...factoryOptions
   } = config
 
-  // Direct execution function
+  /**
+   * Raw call without any invalidation logic.
+   * Used as mutationFn so that onSuccess handles all post-mutation work
+   * and there is no double-invalidation.
+   */
+  const callFn = (
+    args: ReactorArgs<A, M, T>
+  ): Promise<ReactorReturnOk<A, M, T>> =>
+    reactor.callMethod({ functionName, args, callConfig })
+
+  /**
+   * Imperative execution for non-React usage.
+   * Calls the canister method and invalidates factory-level queries.
+   * Use this in route loaders, scripts, or server-side code.
+   */
   const execute = async (
     args: ReactorArgs<A, M, T>
   ): Promise<ReactorReturnOk<A, M, T>> => {
-    const result = await reactor.callMethod({
-      functionName,
-      args,
-      callConfig,
-    })
-
+    const result = await callFn(args)
     if (factoryInvalidateQueries) {
-      await Promise.all(
-        factoryInvalidateQueries.map((queryKey) => {
-          return reactor.queryClient.invalidateQueries({ queryKey })
-        })
-      )
+      await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
     }
-
     return result
   }
 
   // Hook implementation
   const useMutationHook = (options?: MutationHookOptions<A, M, T>) => {
-    const baseOptions = reactor.getQueryOptions({
-      functionName,
-    })
-    // Extract our custom options
+    const baseOptions = reactor.getQueryOptions({ functionName })
     const {
       invalidateQueries: hookInvalidateQueries,
       onCanisterError: hookOnCanisterError,
       ...restOptions
-    } = options || {}
+    } = options ?? {}
 
     return useMutation(
       {
         mutationKey: baseOptions.queryKey,
         ...factoryOptions,
         ...restOptions,
-        mutationFn: execute,
+        // Use callFn (not execute) to avoid double-invalidation:
+        // factoryInvalidateQueries are handled in onSuccess below.
+        mutationFn: callFn,
         onSuccess: async (...args) => {
-          // 1. Handle factory-level invalidateQueries
+          // 1. Factory-level invalidation
           if (factoryInvalidateQueries) {
-            await Promise.all(
-              factoryInvalidateQueries.map((queryKey) => {
-                return reactor.queryClient.invalidateQueries({ queryKey })
-              })
-            )
+            await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
           }
-
-          // 2. Handle hook-level invalidateQueries
+          // 2. Hook-level invalidation
           if (hookInvalidateQueries) {
-            await Promise.all(
-              hookInvalidateQueries.map((queryKey) => {
-                if (queryKey) {
-                  return reactor.queryClient.invalidateQueries({ queryKey })
-                }
-                return Promise.resolve()
-              })
-            )
-          }
-
-          // 3. Call factory onSuccess
-          if (factoryOnSuccess) {
-            await factoryOnSuccess(...args)
-          }
-
-          // 4. Call hook-local onSuccess
-          if (restOptions?.onSuccess) {
-            await restOptions.onSuccess(...args)
+            await invalidateAll(reactor.queryClient, hookInvalidateQueries)
           }
+          // 3. Factory onSuccess
+          await factoryOnSuccess?.(...args)
+          // 4. Hook onSuccess
+          await restOptions.onSuccess?.(...args)
         },
         onError: (error, variables, context, mutation) => {
-          // Check if this is a CanisterError (from Result { Err: E })
           if (isCanisterError(error)) {
-            // 1. Call factory-level onCanisterError
-            if (factoryOnCanisterError) {
-              factoryOnCanisterError(error, variables)
-            }
-            // 2. Call hook-level onCanisterError
-            if (hookOnCanisterError) {
-              hookOnCanisterError(error, variables)
-            }
-          }
-
-          // 3. Call factory-level onError (for all errors)
-          if (factoryOnError) {
-            factoryOnError(error, variables, context, mutation)
-          }
-
-          // 4. Call hook-level onError (for all errors)
-          if (restOptions?.onError) {
-            restOptions.onError(error, variables, context, mutation)
+            factoryOnCanisterError?.(error, variables)
+            hookOnCanisterError?.(error, variables)
           }
+          factoryOnError?.(error, variables, context, mutation)
+          restOptions.onError?.(error, variables, context, mutation)
         },
       },
       reactor.queryClient
     )
   }
 
-  return {
-    useMutation: useMutationHook,
-    execute,
-  }
+  return { useMutation: useMutationHook, execute }
 }
 
 // ============================================================================
-// Factory Function
+// Public Factory Function
 // ============================================================================
 
 export function createMutation<

package/src/createQuery.ts

@@ -30,6 +30,7 @@ import type {
   QueryFactoryConfig,
   NoInfer,
 } from "./types"
+import { buildChainedSelect } from "./utils"
 
 // ============================================================================
 // Internal Implementation
@@ -56,37 +57,34 @@ const createQueryImpl = <
     ...rest
   } = config
 
-  const params = {
-    functionName,
-    args,
-    queryKey: customQueryKey,
-  }
+  const params = { functionName, args, queryKey: customQueryKey }
 
-  // Get query key from actor manager
-  const getQueryKey = (): QueryKey => {
-    return reactor.generateQueryKey(params)
-  }
+  const getQueryKey = (): QueryKey => reactor.generateQueryKey(params)
 
-  // Fetch function for loaders (cache-first)
+  // Apply config.select to raw data (shared by fetch, getCacheData, and the hook)
+  const applySelect = (raw: TData): TSelected =>
+    select ? select(raw) : (raw as unknown as TSelected)
+
+  /** Cache-first fetch for use in loaders / route preloading. */
   const fetch = async (): Promise<TSelected> => {
     const result = await reactor.fetchQuery(params)
-    return select ? select(result) : (result as TSelected)
+    return applySelect(result)
+  }
+
+  /** Fire-and-forget prefetch — warms the cache without blocking. */
+  const prefetch = (): Promise<void> => {
+    const baseOptions = reactor.getQueryOptions(params)
+    return reactor.queryClient.prefetchQuery({
+      queryKey: baseOptions.queryKey,
+      queryFn: baseOptions.queryFn,
+      staleTime,
+    })
   }
 
-  // Implementation
   const useQueryHook: UseQueryWithSelect<TData, TSelected, TError> = (
     options: any
   ): any => {
     const baseOptions = reactor.getQueryOptions(params)
-
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TData) => {
-      const firstPass = config.select ? config.select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
     return useQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -94,50 +92,46 @@ const createQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: chainedSelect,
+        select: buildChainedSelect(select, options?.select),
       },
       reactor.queryClient
     )
   }
 
-  // Invalidate function
   const invalidate = async (): Promise<void> => {
-    const queryKey = getQueryKey()
-    await reactor.queryClient.invalidateQueries({ queryKey })
+    await reactor.queryClient.invalidateQueries({ queryKey: getQueryKey() })
   }
 
-  // Get data from cache without fetching
-  const getCacheData: any = (selectFn?: (data: TData) => any) => {
-    const cachedRawData = reactor.getQueryData(params)
-
-    if (cachedRawData === undefined) {
-      return undefined
-    }
-
-    // Apply config.select to raw cache data
-    const selectedData = (
-      config.select ? config.select(cachedRawData) : cachedRawData
-    ) as TData
-
-    // Apply optional select parameter
-    if (selectFn) {
-      return selectFn(selectedData)
-    }
+  const getCacheData: QueryResult<TData, TSelected, TError>["getCacheData"] = (
+    selectFn?: (data: TSelected) => unknown
+  ): any => {
+    const raw = reactor.getQueryData(params)
+    if (raw === undefined) return undefined
+    const selected = applySelect(raw)
+    return selectFn ? selectFn(selected) : selected
+  }
 
-    return selectedData
+  const setData: QueryResult<TData, TSelected, TError>["setData"] = (
+    updater
+  ) => {
+    return reactor.queryClient.setQueryData(getQueryKey(), updater as any) as
+      | TData
+      | undefined
   }
 
   return {
     fetch,
+    prefetch,
     useQuery: useQueryHook,
     invalidate,
     getQueryKey,
     getCacheData,
+    setData,
   }
 }
 
 // ============================================================================
-// Factory Function
+// Public Factory Function
 // ============================================================================
 
 export function createQuery<
@@ -172,26 +166,21 @@ export function createQueryFactory<
     QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>>
   >()
 
-  return (
-    args: ReactorArgs<A, M, T>
-  ): QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> => {
+  return (args: ReactorArgs<A, M, T>) => {
     const key = reactor.generateQueryKey({
       functionName: config.functionName as M,
       args,
     })
     const cacheKey = JSON.stringify(key)
 
-    if (cache.has(cacheKey)) {
-      return cache.get(cacheKey)!
-    }
+    const existing = cache.get(cacheKey)
+    if (existing) return existing
 
     const result = createQueryImpl<A, M, T, TSelected>(reactor, {
       ...config,
       args,
     })
-
     cache.set(cacheKey, result)
-
     return result
   }
 }

package/src/createSuspenseInfiniteQuery.ts

@@ -45,8 +45,7 @@ import {
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
 import { NoInfer } from "./types"
-
-const FACTORY_KEY_ARGS_QUERY_KEY = "__ic_reactor_factory_key_args"
+import { mergeFactoryQueryKey } from "./utils"
 
 type SuspenseInfiniteFactoryCallOptions = {
   queryKey?: QueryKey
@@ -78,26 +77,6 @@ type SuspenseInfiniteQueryFactoryFn<
   >
 }
 
-const mergeFactoryQueryKey = (
-  baseQueryKey?: QueryKey,
-  callQueryKey?: QueryKey,
-  keyArgs?: unknown
-): QueryKey | undefined => {
-  const merged: unknown[] = []
-
-  if (baseQueryKey) {
-    merged.push(...baseQueryKey)
-  }
-  if (callQueryKey) {
-    merged.push(...callQueryKey)
-  }
-  if (keyArgs !== undefined) {
-    merged.push({ [FACTORY_KEY_ARGS_QUERY_KEY]: keyArgs })
-  }
-
-  return merged.length > 0 ? merged : undefined
-}
-
 // ============================================================================
 // Type Definitions
 // ============================================================================

package/src/createSuspenseQuery.ts

@@ -35,6 +35,7 @@ import type {
   SuspenseQueryFactoryConfig,
   NoInfer,
 } from "./types"
+import { buildChainedSelect } from "./utils"
 
 // ============================================================================
 // Internal Implementation
@@ -65,39 +66,35 @@ const createSuspenseQueryImpl = <
     ...rest
   } = config
 
-  const params = {
-    functionName,
-    args,
-    queryKey: customQueryKey,
-  }
+  const params = { functionName, args, queryKey: customQueryKey }
 
-  // Get query key from actor manager
-  const getQueryKey = () => {
-    return reactor.generateQueryKey(params)
-  }
+  const getQueryKey = () => reactor.generateQueryKey(params)
+
+  const applySelect = (raw: TData): TSelected =>
+    select ? select(raw) : (raw as unknown as TSelected)
 
-  // Fetch function for loaders (cache-first)
+  /** Cache-first fetch for use in loaders / route preloading. */
   const fetch = async (): Promise<TSelected> => {
     const result = await reactor.fetchQuery(params)
-    return select ? select(result) : (result as TSelected)
+    return applySelect(result)
+  }
+
+  /** Fire-and-forget prefetch — warms the cache without blocking. */
+  const prefetch = (): Promise<void> => {
+    const baseOptions = reactor.getQueryOptions(params)
+    return reactor.queryClient.prefetchQuery({
+      queryKey: baseOptions.queryKey,
+      queryFn: baseOptions.queryFn,
+      staleTime,
+    })
   }
 
-  // Implementation
   const useSuspenseQueryHook: UseSuspenseQueryWithSelect<
     TData,
     TSelected,
     TError
   > = (options: any): any => {
     const baseOptions = reactor.getQueryOptions(params)
-
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TData) => {
-      const firstPass = config.select ? config.select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
     return useSuspenseQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -105,50 +102,48 @@ const createSuspenseQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: chainedSelect,
+        select: buildChainedSelect(select, options?.select),
       },
       reactor.queryClient
     )
   }
 
-  // Invalidate function
   const invalidate = async (): Promise<void> => {
-    const queryKey = getQueryKey()
-    await reactor.queryClient.invalidateQueries({ queryKey })
+    await reactor.queryClient.invalidateQueries({ queryKey: getQueryKey() })
   }
 
-  // Get data from cache without fetching
-  const getCacheData: any = (selectFn?: (data: TData) => any) => {
-    const cachedRawData = reactor.getQueryData(params)
-
-    if (cachedRawData === undefined) {
-      return undefined
-    }
-
-    // Apply config.select to raw cache data
-    const selectedData = (
-      config.select ? config.select(cachedRawData) : cachedRawData
-    ) as TData
-
-    // Apply optional select parameter
-    if (selectFn) {
-      return selectFn(selectedData)
-    }
+  const getCacheData: SuspenseQueryResult<
+    TData,
+    TSelected,
+    TError
+  >["getCacheData"] = (selectFn?: (data: TSelected) => unknown): any => {
+    const raw = reactor.getQueryData(params)
+    if (raw === undefined) return undefined
+    const selected = applySelect(raw)
+    return selectFn ? selectFn(selected) : selected
+  }
 
-    return selectedData
+  const setData: SuspenseQueryResult<TData, TSelected, TError>["setData"] = (
+    updater
+  ) => {
+    return reactor.queryClient.setQueryData(getQueryKey(), updater as any) as
+      | TData
+      | undefined
   }
 
   return {
     fetch,
+    prefetch,
     useSuspenseQuery: useSuspenseQueryHook,
     invalidate,
     getQueryKey,
     getCacheData,
+    setData,
   }
 }
 
 // ============================================================================
-// Factory Function
+// Public Factory Function
 // ============================================================================
 
 export function createSuspenseQuery<
@@ -186,30 +181,21 @@ export function createSuspenseQueryFactory<
     SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>>
   >()
 
-  return (
-    args: ReactorArgs<A, M, T>
-  ): SuspenseQueryResult<
-    QueryFnData<A, M, T>,
-    TSelected,
-    QueryError<A, M, T>
-  > => {
+  return (args: ReactorArgs<A, M, T>) => {
     const key = reactor.generateQueryKey({
       functionName: config.functionName as M,
       args,
     })
     const cacheKey = JSON.stringify(key)
 
-    if (cache.has(cacheKey)) {
-      return cache.get(cacheKey)!
-    }
+    const existing = cache.get(cacheKey)
+    if (existing) return existing
 
     const result = createSuspenseQueryImpl<A, M, T, TSelected>(reactor, {
       ...(config as SuspenseQueryFactoryConfig<A, M, T, TSelected>),
       args,
     })
-
     cache.set(cacheKey, result)
-
     return result
   }
 }