@ic-reactor/react 3.8.0 → 3.9.0

package/src/createSuspenseInfiniteQuery.ts

@@ -24,6 +24,7 @@
  * const allPosts = data.pages.flatMap(page => page.posts)
  */
 
+import { useMemo } from "react"
 import type {
   Reactor,
   FunctionName,
@@ -46,7 +47,11 @@ import {
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
 import { NoInfer } from "./types.js"
-import { mergeFactoryQueryKey, normalizeQueryData } from "./utils.js"
+import {
+  buildChainedSelect,
+  mergeFactoryQueryKey,
+  normalizeQueryData,
+} from "./utils.js"
 
 type SuspenseInfiniteFactoryCallOptions = {
   queryKey?: QueryKey
@@ -137,6 +142,15 @@ export interface SuspenseInfiniteQueryConfig<
   queryKey?: QueryKey
   /** Function to get args from page parameter */
   getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
+  /**
+   * Narrows what the cache key derives from the call arguments.
+   *
+   * By default the key is scoped by `getArgs(initialPageParam)`, so two
+   * infinite queries on the same method with different arguments stay in
+   * separate cache entries. Supply this when those args embed the cursor and
+   * only part of them identifies the query.
+   */
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
 }
 
 /**
@@ -152,17 +166,11 @@ export type SuspenseInfiniteQueryFactoryConfig<
     TPageParam
   >,
 > = Omit<
+  // `getArgs` is supplied per factory call. `getKeyArgs` is inherited from
+  // SuspenseInfiniteQueryConfig, which now applies it for every infinite query.
   SuspenseInfiniteQueryConfig<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<Service, Method, Transform>) => unknown
-}
+>
 
 // ============================================================================
 // Hook Interface
@@ -301,6 +309,7 @@ const createSuspenseInfiniteQueryImpl = <
     queryKey: customQueryKey,
     initialPageParam,
     getArgs,
+    getKeyArgs,
     getNextPageParam,
     getPreviousPageParam,
     maxPages,
@@ -309,12 +318,18 @@ const createSuspenseInfiniteQueryImpl = <
     ...rest
   } = config
 
-  // Get query key from actor manager
+  // Fold the call arguments into the key — see the matching comment in
+  // createInfiniteQuery. Without them every infinite query on a method shares
+  // one cache entry, because the arguments live in a `getArgs` closure rather
+  // than in the config.
   const getQueryKey = (): QueryKey => {
+    const initialArgs = getArgs(initialPageParam)
+    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
+
     return reactor.generateQueryKey(
       {
         functionName,
-        queryKey: customQueryKey,
+        queryKey: mergeFactoryQueryKey(customQueryKey, undefined, keyArgs),
       },
       callConfig
     )
@@ -370,14 +385,12 @@ const createSuspenseInfiniteQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TInfiniteData) => {
-      const firstPass = select ? select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
+    // Memoized and identity-preserving; see buildChainedSelect for why the
+    // function identity matters to the observer's select-result cache.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select as never, options?.select),
+      [options?.select]
+    )
 
     return useSuspenseInfiniteQuery(
       {
@@ -550,12 +563,13 @@ export function createSuspenseInfiniteQueryFactory<
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>,
     options?: SuspenseInfiniteFactoryCallOptions
   ) => {
-    const initialArgs = getArgs(config.initialPageParam)
-    const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
+    // Only the caller-supplied segments are merged here; the args-derived
+    // segment is added by the impl, which does it for every infinite query.
+    // Applying it in both places would append the args twice.
     const queryKey = mergeFactoryQueryKey(
       config.queryKey,
       options?.queryKey,
-      keyArgs
+      undefined
     )
 
     return createSuspenseInfiniteQueryImpl<
@@ -565,15 +579,13 @@ export function createSuspenseInfiniteQueryFactory<
       TPageParam,
       Selected
     >(reactor, {
-      ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(
-        config as SuspenseInfiniteQueryFactoryConfig<
-          Service,
-          Method,
-          Transform,
-          TPageParam,
-          Selected
-        >
-      ),
+      ...(config as SuspenseInfiniteQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        TPageParam,
+        Selected
+      >),
       queryKey,
       getArgs,
     } as SuspenseInfiniteQueryConfig<

package/src/createSuspenseQuery.ts

@@ -25,6 +25,7 @@ import type {
   ReactorArgs,
   TransformKey,
 } from "@ic-reactor/core"
+import { useMemo } from "react"
 import { useSuspenseQuery } from "@tanstack/react-query"
 import type {
   QueryFnData,
@@ -95,6 +96,12 @@ const createSuspenseQueryImpl = <
     TError
   > = (options: any): any => {
     const baseOptions = reactor.getQueryOptions(params)
+    // Memoized so the observer's select-result cache can hit; see
+    // buildChainedSelect. `select` comes from the factory config and is stable.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select, options?.select),
+      [options?.select]
+    )
     return useSuspenseQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -102,7 +109,7 @@ const createSuspenseQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: buildChainedSelect(select, options?.select),
+        select: chainedSelect,
       },
       reactor.queryClient
     )

package/src/hooks/useActorInfiniteQuery.ts

@@ -16,7 +16,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils.js"
+import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorInfiniteQuery hook.
@@ -119,8 +119,30 @@ export const useActorInfiniteQuery = <
   // 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(
-    () => reactor.generateQueryKey({ functionName, queryKey }, callConfig),
-    [queryKey, reactor, functionName, callConfig]
+    () =>
+      reactor.generateQueryKey(
+        {
+          functionName,
+          // Fold the call arguments into the key. They live in the `getArgs`
+          // closure rather than in the config, so without this two hooks on the
+          // same method with different arguments share one cache entry and
+          // serve each other's pages.
+          queryKey: mergeFactoryQueryKey(
+            queryKey,
+            undefined,
+            getArgs(options.initialPageParam)
+          ),
+        },
+        callConfig
+      ),
+    [
+      queryKey,
+      reactor,
+      functionName,
+      callConfig,
+      getArgs,
+      options.initialPageParam,
+    ]
   )
 
   // Memoize queryFn to prevent recreation on every render

package/src/hooks/useActorMethod.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react"
+import { useCallback, useEffect, useMemo, useRef } from "react"
 import {
   useQuery,
   useMutation,
@@ -188,17 +188,30 @@ export function useActorMethod<
 
   const functionType: FunctionType = isQuery ? "query" : "update"
 
-  // Generate query key
-  const queryKey = useMemo(() => {
-    if (customQueryKey) return customQueryKey
-    return reactor.generateQueryKey(
-      {
-        functionName,
-        args,
-      },
-      callConfig
-    )
-  }, [reactor, functionName, args, callConfig, customQueryKey])
+  // Latest callbacks, read at dispatch time: this keeps a rerendered closure
+  // from being ignored, and keeps callback identity out of the effect deps.
+  const onSuccessRef = useRef(onSuccess)
+  const onErrorRef = useRef(onError)
+  onSuccessRef.current = onSuccess
+  onErrorRef.current = onError
+
+  // Build the key for a given set of call arguments.
+  //
+  // A custom `queryKey` is appended to the canister/function prefix rather than
+  // replacing it, matching `useActorQuery`. Used verbatim it would carry no
+  // canister id, so the entry would be invisible to the canister-scoped
+  // invalidation `ClientManager.updateAgent` runs on identity change and would
+  // keep serving the previous principal's data after sign-in or sign-out.
+  const buildQueryKey = useCallback(
+    (keyArgs: ReactorArgs<Service, Method, Transform> | undefined): QueryKey =>
+      reactor.generateQueryKey(
+        { functionName, args: keyArgs, queryKey: customQueryKey },
+        callConfig
+      ),
+    [reactor, functionName, callConfig, customQueryKey]
+  )
+
+  const queryKey = useMemo(() => buildQueryKey(args), [buildQueryKey, args])
 
   // ============================================================================
   // Query Implementation
@@ -210,26 +223,51 @@ export function useActorMethod<
   >(
     {
       queryKey,
-      queryFn: async () => {
-        try {
-          const result = await reactor.callMethod({
-            functionName,
-            args,
-            callConfig,
-          })
-          onSuccess?.(result)
-          return result
-        } catch (error) {
-          onError?.(error as ReactorReturnErr<Service, Method, Transform>)
-          throw error
-        }
-      },
+      // Callbacks deliberately do NOT live here: a queryFn runs once per fetch
+      // attempt, so `onError` fired on every retry (four times with the default
+      // QueryClient) and `onSuccess` never fired when data came from the cache
+      // or a deduped sibling. They are dispatched from the settled observer
+      // result below instead.
+      queryFn: () =>
+        reactor.callMethod({
+          functionName,
+          args,
+          callConfig,
+        }),
       enabled: isQuery && enabled,
       ...queryOptions,
     },
     reactor.queryClient
   )
 
+  // Dispatch the query callbacks from the settled observer result, once per
+  // distinct outcome. TanStack v5 removed `onSuccess`/`onError` from useQuery
+  // for exactly this reason, so the settle timestamps are what identify a new
+  // result: they also advance for a cache hit on a fresh mount, which is the
+  // case that previously never notified at all.
+  const notifiedSuccessAt = useRef<number | undefined>(undefined)
+  const notifiedErrorAt = useRef<number | undefined>(undefined)
+
+  const { status, data, error, dataUpdatedAt, errorUpdatedAt } = queryResult
+
+  useEffect(() => {
+    if (!isQuery) return
+    if (status === "success" && dataUpdatedAt !== notifiedSuccessAt.current) {
+      notifiedSuccessAt.current = dataUpdatedAt
+      onSuccessRef.current?.(data)
+    }
+  }, [isQuery, status, data, dataUpdatedAt])
+
+  useEffect(() => {
+    if (!isQuery) return
+    if (status === "error" && errorUpdatedAt !== notifiedErrorAt.current) {
+      notifiedErrorAt.current = errorUpdatedAt
+      onErrorRef.current?.(
+        error as ReactorReturnErr<Service, Method, Transform>
+      )
+    }
+  }, [isQuery, status, error, errorUpdatedAt])
+
   // ============================================================================
   // Mutation Implementation
   // ============================================================================
@@ -250,7 +288,7 @@ export function useActorMethod<
         return result
       },
       onSuccess: (data) => {
-        onSuccess?.(data)
+        onSuccessRef.current?.(data)
         // Invalidate specified queries after successful mutation
         if (invalidateQueries && invalidateQueries.length > 0) {
           invalidateQueries.forEach((key) => {
@@ -259,7 +297,7 @@ export function useActorMethod<
         }
       },
       onError: (error) => {
-        onError?.(error)
+        onErrorRef.current?.(error)
       },
     },
     reactor.queryClient
@@ -276,9 +314,14 @@ export function useActorMethod<
       if (isQuery) {
         // For queries, refetch with new args if provided
         if (callArgs !== undefined) {
+          // Key on the args actually being called. Reusing the hook's
+          // mount-time key would store this result under the previous args'
+          // entry — poisoning it for every other reader — and let fetchQuery
+          // dedupe onto an in-flight request for the old args, returning that
+          // response as though it answered this one.
           try {
             const result = await reactor.queryClient.fetchQuery({
-              queryKey,
+              queryKey: buildQueryKey(callArgs),
               queryFn: () =>
                 reactor.callMethod({
                   functionName,
@@ -287,10 +330,17 @@ export function useActorMethod<
                 }),
               staleTime: 0,
             })
-            onSuccess?.(result)
+            // Dispatched here rather than by the observer effect: this result
+            // lands under the called args' key, which the mounted observer (bound
+            // to the hook's own args) does not watch. That separation is also why
+            // this can no longer double-fire the way it did when both wrote to
+            // the same key.
+            onSuccessRef.current?.(result)
             return result
           } catch (error) {
-            onError?.(error as ReactorReturnErr<Service, Method, Transform>)
+            onErrorRef.current?.(
+              error as ReactorReturnErr<Service, Method, Transform>
+            )
             return undefined
           }
         }
@@ -309,11 +359,9 @@ export function useActorMethod<
       reactor,
       functionName,
       callConfig,
-      queryKey,
+      buildQueryKey,
       queryResult,
       mutationResult,
-      onSuccess,
-      onError,
     ]
   )
 

package/src/hooks/useActorMutation.ts

@@ -35,7 +35,14 @@ export interface UseActorMutationParameters<
   reactor: Reactor<Service, Transform>
   functionName: Method
   callConfig?: CallConfig
-  invalidateQueries?: QueryKey[]
+  /**
+   * Queries to invalidate upon successful mutation.
+   *
+   * `undefined` entries are skipped, so the common
+   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
+   * is absent.
+   */
+  invalidateQueries?: (QueryKey | undefined)[]
   /**
    * Callback for canister-level business logic errors.
    * Called when the canister returns a Result { Err: E } variant.
@@ -126,10 +133,18 @@ export const useActorMutation = <
       >
     ) => {
       if (invalidateQueries) {
+        // Skip undefined entries. React Query reads `{ queryKey: undefined }`
+        // as "match everything", so a single undefined — which the natural
+        // `invalidateQueries: [maybeQuery?.getQueryKey()]` idiom produces
+        // whenever the optional query object is absent — would invalidate every
+        // query in the client, including an app's unrelated non-canister ones.
+        // `createMutation.invalidateAll` already filters the same way.
         await Promise.all(
-          invalidateQueries.map((queryKey) =>
-            reactor.queryClient.invalidateQueries({ queryKey })
-          )
+          invalidateQueries
+            .filter((queryKey) => queryKey !== undefined)
+            .map((queryKey) =>
+              reactor.queryClient.invalidateQueries({ queryKey })
+            )
         )
       }
       await onSuccess?.(...params)

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -16,7 +16,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils.js"
+import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorSuspenseInfiniteQuery hook.
@@ -129,8 +129,30 @@ export const useActorSuspenseInfiniteQuery = <
   // 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(
-    () => reactor.generateQueryKey({ functionName, queryKey }, callConfig),
-    [queryKey, reactor, functionName, callConfig]
+    () =>
+      reactor.generateQueryKey(
+        {
+          functionName,
+          // Fold the call arguments into the key. They live in the `getArgs`
+          // closure rather than in the config, so without this two hooks on the
+          // same method with different arguments share one cache entry and
+          // serve each other's pages.
+          queryKey: mergeFactoryQueryKey(
+            queryKey,
+            undefined,
+            getArgs(options.initialPageParam)
+          ),
+        },
+        callConfig
+      ),
+    [
+      queryKey,
+      reactor,
+      functionName,
+      callConfig,
+      getArgs,
+      options.initialPageParam,
+    ]
   )
 
   // Memoize queryFn to prevent recreation on every render

package/src/types.ts

@@ -356,8 +356,14 @@ export interface MutationConfig<
   functionName: Method
   /** Call configuration for the actor method */
   callConfig?: CallConfig
-  /** Queries to invalidate upon successful mutation */
-  invalidateQueries?: QueryKey[]
+  /**
+   * Queries to invalidate upon successful mutation.
+   *
+   * `undefined` entries are skipped, so the common
+   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
+   * is absent.
+   */
+  invalidateQueries?: (QueryKey | undefined)[]
   /**
    * Callback for canister-level business logic errors.
    * Called when the canister returns a Result { Err: E } variant.

package/src/utils.ts

@@ -46,20 +46,31 @@ export function mergeFactoryQueryKey(
 }
 
 /**
- * Build a chained select function that first applies the config-level select
- * (if any) and then the hook-level select (if any).
+ * Build a chained select that 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.
+ * Returns the caller's own function untouched when only one of the two is
+ * present, and `undefined` when neither is — allocating a wrapper only for the
+ * genuinely chained case. Identity matters here: `QueryObserver` memoizes a
+ * select result on `options.select === previousSelectFn`, so a wrapper rebuilt
+ * on every render defeats that check. The select then re-runs each render, and
+ * for a select returning a non-plain value (a `Map`, a `Date`, a `Principal`)
+ * `replaceEqualDeep` cannot structurally share the result either, so `data`
+ * gets a fresh reference every render and a `useEffect([data])` that sets state
+ * becomes an unbounded loop.
+ *
+ * Callers should still memoize the result, since the chained case allocates.
  */
 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
+): ((rawData: TData) => TSelected | TFinal) | undefined {
+  if (!configSelect) {
+    // `hookSelect` receives the raw data when there is no config-level select,
+    // matching the previous behaviour.
+    return hookSelect as unknown as
+      ((rawData: TData) => TSelected | TFinal) | undefined
   }
+  if (!hookSelect) return configSelect
+  return (rawData: TData) => hookSelect(configSelect(rawData))
 }