@ic-reactor/react 3.2.0 → 3.3.1

package/src/hooks/useActorInfiniteQuery.ts

@@ -104,16 +104,11 @@ export const useActorInfiniteQuery = <
   T,
   TPageParam
 >): UseActorInfiniteQueryResult<A, M, T, TPageParam> => {
-  // Memoize queryKey to prevent unnecessary re-calculations
+  // 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.
   const baseQueryKey = useMemo(
-    () =>
-      queryKey ??
-      reactor.generateQueryKey(
-        {
-          functionName,
-        },
-        callConfig
-      ),
+    () => reactor.generateQueryKey({ functionName, queryKey }, callConfig),
     [queryKey, reactor, functionName, callConfig]
   )
 

package/src/hooks/useActorMutation.ts

@@ -12,6 +12,11 @@ import {
   FunctionName,
   TransformKey,
   ReactorReturnErr,
+  isCanisterError,
+  CanisterError,
+  ErrResult,
+  ActorMethodReturnType,
+  TransformReturnRegistry,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
 
@@ -31,6 +36,17 @@ export interface UseActorMutationParameters<
   functionName: M
   callConfig?: CallConfig
   invalidateQueries?: QueryKey[]
+  /**
+   * Callback for canister-level business logic errors.
+   * Called when the canister returns a Result { Err: E } variant.
+   * Separate from `onError`, which fires for all errors including network failures.
+   */
+  onCanisterError?: (
+    error: CanisterError<
+      TransformReturnRegistry<ErrResult<ActorMethodReturnType<A[M]>>>[T]
+    >,
+    variables: ReactorArgs<A, M, T>
+  ) => void
 }
 
 export type UseActorMutationConfig<
@@ -57,6 +73,7 @@ export type UseActorMutationResult<
  *   reactor,
  *   functionName: "transfer",
  *   onSuccess: () => console.log("Success!"),
+ *   onCanisterError: (err) => console.error("Canister Err:", err.code),
  * })
  */
 export const useActorMutation = <
@@ -68,22 +85,17 @@ export const useActorMutation = <
   functionName,
   invalidateQueries,
   onSuccess,
+  onError,
+  onCanisterError,
   callConfig,
   ...options
 }: UseActorMutationParameters<A, M, T>): UseActorMutationResult<A, M, T> => {
-  // Memoize mutationFn to avoid creating new function on every render
   const mutationFn = useCallback(
-    async (args: ReactorArgs<A, M, T>) => {
-      return reactor.callMethod({
-        functionName,
-        callConfig,
-        args,
-      })
-    },
+    async (args: ReactorArgs<A, M, T>) =>
+      reactor.callMethod({ functionName, callConfig, args }),
     [reactor, functionName, callConfig]
   )
 
-  // Memoize onSuccess handler
   const handleSuccess = useCallback(
     async (
       ...params: Parameters<
@@ -103,21 +115,35 @@ export const useActorMutation = <
           )
         )
       }
-      if (onSuccess) {
-        await onSuccess(...params)
-      }
+      await onSuccess?.(...params)
     },
     [reactor, invalidateQueries, onSuccess]
   )
 
-  // Memoize mutation options
+  const handleError = useCallback(
+    (
+      error: ReactorReturnErr<A, M, T>,
+      variables: ReactorArgs<A, M, T>,
+      context: unknown,
+      mutation: unknown
+    ) => {
+      if (isCanisterError(error)) {
+        onCanisterError?.(error as any, variables)
+      }
+      onError?.(error, variables, context as any, mutation as any)
+    },
+    [onCanisterError, onError]
+  )
+
   const mutationOptions = useMemo(
     () => ({
       ...options,
       mutationFn,
       onSuccess: handleSuccess,
+      onError: handleError,
     }),
-    [options, mutationFn, handleSuccess]
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [mutationFn, handleSuccess, handleError]
   )
 
   return useMutation(mutationOptions, reactor.queryClient)

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -107,16 +107,11 @@ export const useActorSuspenseInfiniteQuery = <
   T,
   TPageParam
 >): UseActorSuspenseInfiniteQueryResult<A, M, T, TPageParam> => {
-  // Memoize queryKey to prevent unnecessary re-calculations
+  // 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.
   const baseQueryKey = useMemo(
-    () =>
-      queryKey ??
-      reactor.generateQueryKey(
-        {
-          functionName,
-        },
-        callConfig
-      ),
+    () => reactor.generateQueryKey({ functionName, queryKey }, callConfig),
     [queryKey, reactor, functionName, callConfig]
   )
 

package/src/types.ts

@@ -231,6 +231,18 @@ export interface BaseQueryResult<
   /** Fetch data in loader (uses ensureQueryData for cache-first) */
   fetch: () => Promise<TSelected>
 
+  /**
+   * Eagerly prefetch data into the cache without blocking.
+   * Useful for preloading data before navigating to a route.
+   *
+   * Unlike `fetch()`, this returns a void promise so it can be fire-and-forget.
+   *
+   * @example
+   * // In a route hover handler
+   * button.addEventListener("mouseenter", () => userQuery.prefetch())
+   */
+  prefetch: () => Promise<void>
+
   /** Invalidate the cache (refetches if query is active) */
   invalidate: () => Promise<void>
 
@@ -256,6 +268,26 @@ export interface BaseQueryResult<
     (): TSelected | undefined
     <TFinal>(select: (data: TSelected) => TFinal): TFinal | undefined
   }
+
+  /**
+   * Write raw data directly into the cache (useful for optimistic updates).
+   * Accepts a new value or an updater function that receives the current cached raw data.
+   *
+   * Note: The value is stored as raw (pre-select) data.  Any active `select`
+   * transformations are automatically re-applied by React Query on the next render.
+   *
+   * @example
+   * // Optimistic update before a mutation
+   * userQuery.setData({ id: "1", name: "Alice" })
+   *
+   * // Functional update
+   * counterQuery.setData((prev) => (prev ?? 0) + 1)
+   */
+  setData: (
+    updater:
+      | TQueryFnData
+      | ((old: TQueryFnData | undefined) => TQueryFnData | undefined)
+  ) => TQueryFnData | undefined
 }
 
 /**

package/src/utils.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared internal utilities for query and mutation factories.
+ */
+
+import type { QueryKey } from "@tanstack/react-query"
+
+/**
+ * Internal query-key segment used to distinguish per-call factory args
+ * from the base query key. Not part of the public API.
+ */
+export const FACTORY_KEY_ARGS_QUERY_KEY = "__ic_reactor_factory_key_args"
+
+/**
+ * Merge a base query key, optional per-call query key, and optional key-args
+ * into a single query key array.
+ *
+ * Used by createInfiniteQueryFactory and createSuspenseInfiniteQueryFactory to
+ * ensure each unique set of factory args produces a distinct cache entry.
+ */
+export function 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
+}
+
+/**
+ * Build a chained select function that first applies the config-level select
+ * (if any) and then the hook-level select (if any).
+ *
+ * This enables `createQuery` / `createSuspenseQuery` to support two-level
+ * select chaining without duplicating the logic.
+ */
+export function buildChainedSelect<TData, TSelected, TFinal = TSelected>(
+  configSelect: ((data: TData) => TSelected) | undefined,
+  hookSelect: ((data: TSelected) => TFinal) | undefined
+): (rawData: TData) => TSelected | TFinal {
+  return (rawData: TData) => {
+    const firstPass = configSelect
+      ? configSelect(rawData)
+      : (rawData as unknown as TSelected)
+    return hookSelect ? hookSelect(firstPass) : firstPass
+  }
+}