@ic-reactor/react 3.3.0 → 3.4.0

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
   }
 }

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
+  }
+}