@ic-reactor/react 3.12.5 → 3.13.0

package/src/hooks/useActorMethod.ts

@@ -1,7 +1,14 @@
-import { useCallback, useEffect, useMemo, useRef } from "react"
+import {
+  useCallback,
+  useEffect,
+  useInsertionEffect,
+  useMemo,
+  useRef,
+} from "react"
 import {
   useQuery,
   useMutation,
+  hashKey,
   type UseQueryResult,
   type UseMutationResult,
   type QueryKey,
@@ -19,7 +26,13 @@ import {
   FunctionType,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils.js"
+import {
+  invalidateTargets,
+  normalizeQueryData,
+  pickFetchOptions,
+  useMountQueryClient,
+} from "../utils.js"
+import type { InvalidationTarget } from "../types.js"
 
 /**
  * Configuration for useActorMethod hook.
@@ -28,6 +41,13 @@ import { normalizeQueryData } from "../utils.js"
  * This is a unified hook that handles both query and mutation methods.
  * Query-specific options (like refetchInterval) only apply to query methods.
  * Mutation-specific options (like invalidateQueries) only apply to mutation methods.
+ *
+ * `retry`, `retryDelay`, `networkMode` and `meta` decide how a call runs, so
+ * they apply to both. An update method's call is a mutation: without a `retry`
+ * here it follows the QueryClient's mutation defaults, which retry nothing
+ * unless the app set `mutations.retry`, because each attempt runs the update
+ * on the canister again. Its query defaults, such as `reactorRetry`, do not
+ * apply to it.
  */
 export interface UseActorMethodParameters<
   Service = BaseActor,
@@ -76,10 +96,19 @@ export interface UseActorMethodParameters<
   onError?: (error: ReactorReturnErr<Service, Method, Transform>) => void
 
   /**
-   * Query keys to invalidate after a successful mutation.
+   * Queries to invalidate after a successful mutation.
    * Only applies to mutation methods (updates).
+   *
+   * Each entry is a query key, a query object or query factory, or a
+   * `{ functionName, args? }` method of `reactor`; see
+   * {@link InvalidationTarget}. `undefined` entries are skipped.
+   *
+   * The invalidation is awaited before `onSuccess` runs, as in
+   * `useActorMutation` and `createMutation`, so `onSuccess` sees the
+   * refetched data, and `call()` resolves once the invalidated queries in use
+   * have refetched.
    */
-  invalidateQueries?: QueryKey[]
+  invalidateQueries?: InvalidationTarget<Service, Transform>[]
 }
 
 /**
@@ -103,8 +132,9 @@ export interface UseActorMethodResult<
 > {
   /**
    * The returned data from the method call. A method's `undefined` result is
-   * `null` here, as in `useActorQuery`, so `undefined` only means no call has
-   * settled yet.
+   * `null` here, as in `useActorQuery`, so `undefined` means that no call has
+   * settled yet, that the last call failed, or that an update call is
+   * running. A query keeps its earlier data when a refetch fails.
    */
   data:
     ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
@@ -134,6 +164,15 @@ export interface UseActorMethodResult<
    * Call the method with optional arguments.
    * For queries: triggers a refetch
    * For mutations: executes the mutation with the provided args
+   *
+   * For a query method, `call(args)` fetches those args from the canister
+   * even when they are cached, and reports the result to `onSuccess` or
+   * `onError` itself. `call()` refetches the hook's own args, as `refetch()`
+   * does. Either resolves `undefined` when its fetch fails. A sign-in or
+   * sign-out while either is in flight cancels the fetch, which then runs
+   * again for the principal signed in, so the call resolves with that
+   * principal's answer rather than the previous one's; see
+   * `ClientManager.fetchAcrossIdentitySwitch`.
    */
   call: (
     args?: ReactorArgs<Service, Method, Transform>
@@ -153,6 +192,12 @@ export interface UseActorMethodResult<
 
   /**
    * For queries only: Refetch the query
+   *
+   * Resolves with the answer, or `undefined` when the refetch fails, whose
+   * error the hook reports to `onError`; `data` keeps the last answer. A
+   * sign-in or sign-out while it is in flight makes it refetch for the
+   * principal signed in, and it resolves with that principal's answer, as
+   * `call()` does.
    */
   refetch: () => Promise<
     ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
@@ -173,6 +218,29 @@ export interface UseActorMethodResult<
   >
 }
 
+/**
+ * A ref to `value` as of the last committed render, for code that runs outside
+ * render: event handlers, timers, effects and TanStack callbacks.
+ *
+ * Assigning the ref during render would also publish renders that React throws
+ * away, such as a transition that suspends or one that a more urgent update
+ * interrupts. The tree still on screen would then act on props it never showed,
+ * like calling a method it does not render. An insertion effect runs only when
+ * its render commits, and before every layout and passive effect of that
+ * commit, so no effect anywhere in the tree reads the previous commit's value.
+ * React's own `useEffectEvent` also swaps in its new function during the
+ * commit, ahead of layout effects. Unlike `useLayoutEffect`, an insertion
+ * effect does not warn in a React 18 server render. The initial value serves
+ * anything that runs before the first commit.
+ */
+function useCommittedRef<T>(value: T): { readonly current: T } {
+  const ref = useRef(value)
+  useInsertionEffect(() => {
+    ref.current = value
+  })
+  return ref
+}
+
 /**
  * A unified hook for calling canister methods that automatically handles
  * both query and mutation methods based on the Candid interface.
@@ -208,12 +276,13 @@ export function useActorMethod<
 
   const functionType: FunctionType = isQuery ? "query" : "update"
 
-  // 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
+  useMountQueryClient(reactor.queryClient)
+
+  // The committed render's callbacks, read at dispatch time: this keeps a
+  // rerendered closure from being ignored, and keeps callback identity out of
+  // the effect deps.
+  const onSuccessRef = useCommittedRef(onSuccess)
+  const onErrorRef = useCommittedRef(onError)
 
   // Build the key for a given set of call arguments.
   //
@@ -284,15 +353,31 @@ export function useActorMethod<
   const notifiedSuccessAt = useRef<number | undefined>(undefined)
   const notifiedErrorAt = useRef<number | undefined>(undefined)
 
-  const { status, data, error, dataUpdatedAt, errorUpdatedAt } = queryResult
+  const {
+    status,
+    data,
+    error,
+    dataUpdatedAt,
+    errorUpdatedAt,
+    isPlaceholderData,
+    isFetched,
+  } = queryResult
 
   useEffect(() => {
     if (!isQuery) return
+    // Placeholder data also has `status: "success"`, but no call has returned
+    // it: it is the `placeholderData` option, or with `keepPreviousData` the
+    // previous args' result standing in while this call is in flight.
+    if (isPlaceholderData) return
+    // So does `initialData`: an entry starts with it, and `reset()` puts it
+    // back, before any fetch of the entry has settled. The first fetch that
+    // settles makes the entry fetched, and its result is reported below.
+    if (!isFetched) return
     if (status === "success" && dataUpdatedAt !== notifiedSuccessAt.current) {
       notifiedSuccessAt.current = dataUpdatedAt
       onSuccessRef.current?.(data)
     }
-  }, [isQuery, status, data, dataUpdatedAt])
+  }, [isQuery, status, data, dataUpdatedAt, isPlaceholderData, isFetched])
 
   useEffect(() => {
     if (!isQuery) return
@@ -304,6 +389,50 @@ export function useActorMethod<
     }
   }, [isQuery, status, error, errorUpdatedAt])
 
+  // `call(args)` reports its own outcome, once per call, because the args it
+  // fetched usually key an entry this observer does not watch. When they key
+  // the entry it does watch, the effects above see the same settle, and each
+  // callback used to fire twice for one call. So the settle that ends a call's
+  // fetch is marked as notified when it lands in the observed entry, and the
+  // effects skip it.
+  //
+  // A query cache listener sets that mark while TanStack dispatches the
+  // settle, before any render can show it. Matching a settle up by its
+  // timestamp afterwards could not tell settles apart: two in one millisecond
+  // share a timestamp. And a call that an identity switch cancels settles
+  // nothing: TanStack reverts the entry to its previous result, timestamp
+  // included, so the call's outcome looked reported already, and neither the
+  // call nor the effects reported it.
+  const observedKeyRef = useCommittedRef(queryKey)
+  const markCallSettle = (calledKey: QueryKey): (() => void) => {
+    const { queryClient } = reactor
+    // The hash TanStack files the called entry under, worked out the way
+    // `fetchQuery` does. The listener compares it with hashes TanStack has
+    // already computed rather than hashing keys itself: the QueryClient may be
+    // shared with the app, whose keys a custom `queryKeyHashFn` can let hold
+    // values that `hashKey` throws on, inside TanStack's dispatch.
+    const calledHash = queryClient.defaultQueryOptions({
+      queryKey: calledKey,
+    }).queryHash
+    let settled = false
+    return queryClient.getQueryCache().subscribe((event) => {
+      if (settled || event.type !== "updated") return
+      const { action, query } = event
+      // A fetch settles with one of these. `setQueryData` dispatches a
+      // success too, flagged manual, and it does not end this call's fetch.
+      const isSettle =
+        action.type === "error" || (action.type === "success" && !action.manual)
+      if (!isSettle || query.queryHash !== calledHash) return
+      settled = true
+      if (hashKey(calledKey) !== hashKey(observedKeyRef.current)) return
+      if (action.type === "success") {
+        notifiedSuccessAt.current = query.state.dataUpdatedAt
+      } else {
+        notifiedErrorAt.current = query.state.errorUpdatedAt
+      }
+    })
+  }
+
   // ============================================================================
   // Mutation Implementation
   // ============================================================================
@@ -315,6 +444,16 @@ export function useActorMethod<
   >(
     {
       mutationKey: queryKey,
+      // The hook's `retry`, `retryDelay`, `networkMode` and `meta`, the options
+      // that decide how a call runs, as the query branch's `call()` applies
+      // them. They reached only the query branch, so an update's call ignored
+      // them: it stayed paused offline under `networkMode: "always"` and
+      // reached the MutationCache callbacks without the hook's `meta`. Unset
+      // ones are left to the QueryClient's mutation defaults, which retry
+      // nothing unless the app set `mutations.retry`: each attempt of an
+      // update is a new call the canister runs, so only a `retry` given here
+      // or in those defaults sends one again.
+      ...pickFetchOptions(queryOptions),
       // Normalized like the query branch, so `data`, `call()` and `onSuccess`
       // mean the same thing for both kinds of method. The hook cannot type the
       // two branches apart: a Candid service type does not say which methods
@@ -327,14 +466,16 @@ export function useActorMethod<
             callConfig,
           })) as TData
         ),
-      onSuccess: (data) => {
+      // Invalidation first, then `onSuccess`, as `useActorMutation` and
+      // `createMutation` do. TanStack Query waits for the promise returned
+      // here before it settles the mutation, so `call()` resolves, and
+      // `isPending` turns false, once the invalidated queries that are in use
+      // have refetched, and `onSuccess` reads the refetched data. A refetch
+      // that fails does not reject `invalidateQueries`, so it cannot turn the
+      // update, which has already run on the canister, into a failure.
+      onSuccess: async (data) => {
+        await invalidateTargets(reactor, invalidateQueries, callConfig)
         onSuccessRef.current?.(data)
-        // Invalidate specified queries after successful mutation
-        if (invalidateQueries && invalidateQueries.length > 0) {
-          invalidateQueries.forEach((key) => {
-            void reactor.queryClient.invalidateQueries({ queryKey: key })
-          })
-        }
       },
       onError: (error) => {
         onErrorRef.current?.(error)
@@ -344,75 +485,126 @@ export function useActorMethod<
   )
 
   // ============================================================================
-  // Unified Call Function
+  // Refetch and Call Functions
   // ============================================================================
 
-  const call = useCallback(
-    async (
-      callArgs?: ReactorArgs<Service, Method, Transform>
-    ): Promise<TQueryData | undefined> => {
-      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<TQueryData>({
-              queryKey: buildQueryKey(callArgs),
-              // Normalize for the same reason as the observer's queryFn.
-              queryFn: async () =>
-                normalizeQueryData<TData>(
-                  (await reactor.callMethod({
-                    functionName,
-                    args: callArgs,
-                    callConfig,
-                  })) as TData
-                ),
-              staleTime: 0,
-            })
-            // 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) {
-            onErrorRef.current?.(
-              error as ReactorReturnErr<Service, Method, Transform>
-            )
-            return undefined
-          }
+  // A query's `call()` and `refetch()` resolve with the answer for the
+  // principal signed in when they settle. `ClientManager.updateAgent` cancels
+  // a fetch in flight when a sign-in or sign-out switches the principal, so
+  // that the previous principal's answer is never cached. TanStack then
+  // resolves the fetch with the data it puts the entry back to, which is the
+  // previous principal's, or rejects it with a `CancelledError` when the entry
+  // had none, and a call used to resolve with, and report, whichever it got.
+  // Through `fetchAcrossIdentitySwitch` it runs again for the principal signed
+  // in, as `reactor.fetchQuery()` and the factories' `fetch()` do. When the
+  // principal switches during that run too, and during each of two more, that
+  // rejects with a `CallError`, which is reported to `onError` like any other
+  // failure.
+
+  const refetchLatest = async (): Promise<TQueryData | undefined> => {
+    if (!isQuery) return undefined
+    let runs = 0
+    try {
+      const result = await reactor.clientManager.fetchAcrossIdentitySwitch(() =>
+        // A run after a switch joins the refetch the switch started for
+        // this entry, rather than cancel it and start another.
+        queryResult.refetch(runs++ === 0 ? undefined : { cancelRefetch: false })
+      )
+      // TanStack's `refetch()` resolves even when the fetch fails, with the
+      // entry's last answer still in the result. After a sign-in or sign-out
+      // that is the previous principal's: the entry is put back to it when
+      // the switch cancels a fetch, and keeps it when the new principal's
+      // refetch fails. So a failed refetch resolves `undefined`, as a failed
+      // `call(args)` does, and the effects report the failure to `onError`.
+      // The hook's `data` keeps the last answer, as TanStack's does.
+      return result.isError ? undefined : result.data
+    } catch (error) {
+      // Only that CallError: `refetch()` itself never rejects. The effects
+      // report what the entry settles with, and it settles nothing for this.
+      onErrorRef.current?.(
+        error as ReactorReturnErr<Service, Method, Transform>
+      )
+      return undefined
+    }
+  }
+
+  const callLatest = async (
+    callArgs?: ReactorArgs<Service, Method, Transform>
+  ): Promise<TQueryData | undefined> => {
+    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.
+        const calledKey = buildQueryKey(callArgs)
+        // Reported here rather than by the observer effects: this result
+        // usually lands under a key the mounted observer (bound to the hook's
+        // own args) does not watch. When it is that key, `markCallSettle` has
+        // already kept the effects from reporting it as well. Either way the
+        // callbacks get what the call settles with.
+        try {
+          const result = await reactor.clientManager.fetchAcrossIdentitySwitch(
+            async () => {
+              // Each run marks the settle of its own fetch. A run a switch
+              // overtook may have settled with the previous principal's answer,
+              // which the effects must not report either.
+              const stopMarking = markCallSettle(calledKey)
+              try {
+                return await reactor.queryClient.fetchQuery<
+                  TQueryData,
+                  ReactorReturnErr<Service, Method, Transform>
+                >({
+                  // The options the hook's own fetches run with: `retry`,
+                  // `retryDelay`, `networkMode` and `meta`. With only a key and
+                  // a function, a call ran on the QueryClient's defaults. It
+                  // failed on the first error the hook retried through, stayed
+                  // paused offline under `networkMode: "always"`, and reached
+                  // the QueryCache callbacks without the hook's `meta`.
+                  ...pickFetchOptions(queryOptions),
+                  queryKey: calledKey,
+                  // Normalize for the same reason as the observer's queryFn.
+                  queryFn: async () =>
+                    normalizeQueryData<TData>(
+                      (await reactor.callMethod({
+                        functionName,
+                        args: callArgs,
+                        callConfig,
+                      })) as TData
+                    ),
+                  staleTime: 0,
+                })
+              } finally {
+                stopMarking()
+              }
+            }
+          )
+          onSuccessRef.current?.(result)
+          return result
+        } catch (error) {
+          onErrorRef.current?.(
+            error as ReactorReturnErr<Service, Method, Transform>
+          )
+          return undefined
         }
-        // Otherwise just refetch
-        const { data } = await queryResult.refetch()
-        return data
-      } else {
-        // For mutations, execute with provided args
-        return mutationResult
-          .mutateAsync(callArgs as ReactorArgs<Service, Method, Transform>)
-          .catch(() => undefined)
       }
-    },
-    [
-      isQuery,
-      reactor,
-      functionName,
-      callConfig,
-      buildQueryKey,
-      queryResult,
-      mutationResult,
-    ]
-  )
+      // Otherwise just refetch
+      return refetchLatest()
+    } else {
+      // For mutations, execute with provided args
+      return mutationResult
+        .mutateAsync(callArgs as ReactorArgs<Service, Method, Transform>)
+        .catch(() => undefined)
+    }
+  }
 
   // ============================================================================
   // Reset Function
   // ============================================================================
 
-  const reset = useCallback(() => {
+  const resetLatest = () => {
     if (isQuery) {
       // Reset, not remove. `removeQueries` drops the entry without notifying
       // its observers, so this hook kept rendering the old data while bound to
@@ -425,19 +617,30 @@ export function useActorMethod<
     } else {
       mutationResult.reset()
     }
-  }, [isQuery, reactor, queryKey, mutationResult])
+  }
 
-  // ============================================================================
-  // Refetch Function
-  // ============================================================================
+  // `call`, `reset` and `refetch` keep one identity for the life of the
+  // component, as TanStack's own `refetch`, `mutate` and `reset` do, and run
+  // the latest committed render's implementation above when invoked. They used
+  // to be `useCallback`s listing the query and mutation results, which TanStack
+  // Query returns fresh every render, so they changed every render too. An
+  // effect that lists one — `react-hooks/exhaustive-deps` requires it as soon
+  // as the effect calls it — then re-ran after every render its own call
+  // caused: an unbounded loop of canister calls, state-changing ones for an
+  // update method.
+  const latest = useCommittedRef({
+    call: callLatest,
+    reset: resetLatest,
+    refetch: refetchLatest,
+  })
 
-  const refetch = useCallback(async () => {
-    if (isQuery) {
-      const result = await queryResult.refetch()
-      return result.data
-    }
-    return undefined
-  }, [isQuery, queryResult])
+  const call = useCallback(
+    (callArgs?: ReactorArgs<Service, Method, Transform>) =>
+      latest.current.call(callArgs),
+    []
+  )
+  const reset = useCallback(() => latest.current.reset(), [])
+  const refetch = useCallback(() => latest.current.refetch(), [])
 
   // ============================================================================
   // Return Unified Result

package/src/hooks/useActorMutation.ts

@@ -3,7 +3,6 @@ import {
   useMutation,
   UseMutationOptions,
   UseMutationResult,
-  QueryKey,
 } from "@tanstack/react-query"
 import {
   Reactor,
@@ -19,6 +18,8 @@ import {
   TransformReturnRegistry,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import { invalidateTargets, useMountQueryClient } from "../utils.js"
+import type { InvalidationTarget } from "../types.js"
 
 export interface UseActorMutationParameters<
   Service,
@@ -38,13 +39,15 @@ export interface UseActorMutationParameters<
   functionName: Method
   callConfig?: CallConfig
   /**
-   * Queries to invalidate upon successful mutation.
+   * Queries to invalidate upon successful mutation, awaited before
+   * `onSuccess` runs.
    *
-   * `undefined` entries are skipped, so the common
-   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
-   * is absent.
+   * Each entry is a query key, a query object or query factory, or a
+   * `{ functionName, args? }` method of `reactor`; see
+   * {@link InvalidationTarget}. `undefined` entries are skipped, so
+   * `[maybeQuery]` is safe when the optional query object is absent.
    */
-  invalidateQueries?: (QueryKey | undefined)[]
+  invalidateQueries?: InvalidationTarget<Service, Transform>[]
   /**
    * Callback for canister-level business logic errors.
    * Called when the canister returns a Result { Err: E } variant.
@@ -89,7 +92,7 @@ export type UseActorMutationResult<
  * For non-React usage, prefer `createMutation(...).execute(args)`.
  *
  * @example
- * const { mutate, isPending } = useActorMutation({
+ * const { mutate, isPending } = useReactorMutation({
  *   reactor,
  *   functionName: "transfer",
  *   onSuccess: () => console.log("Success!"),
@@ -125,6 +128,8 @@ export const useActorMutation = <
   Transform,
   TOnMutateResult
 >): UseActorMutationResult<Service, Method, Transform, TOnMutateResult> => {
+  useMountQueryClient(reactor.queryClient)
+
   const mutationFn = useCallback(
     async (args: ReactorArgs<Service, Method, Transform>) =>
       reactor.callMethod({ functionName, callConfig, args }),
@@ -144,24 +149,13 @@ 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
-            .filter((queryKey) => queryKey !== undefined)
-            .map((queryKey) =>
-              reactor.queryClient.invalidateQueries({ queryKey })
-            )
-        )
-      }
+      // Undefined entries are skipped: React Query reads
+      // `{ queryKey: undefined }` as "match everything", and the natural
+      // `[maybeQuery]` idiom produces one whenever the query is absent.
+      await invalidateTargets(reactor, invalidateQueries, callConfig)
       await onSuccess?.(...params)
     },
-    [reactor, invalidateQueries, onSuccess]
+    [reactor, invalidateQueries, onSuccess, callConfig]
   )
 
   const handleError = useCallback(
@@ -195,6 +189,12 @@ export const useActorMutation = <
   // rather than the reference.
   return useMutation(
     {
+      // Keyed like `createMutation`'s hook and `useActorMethod`'s mutations,
+      // so `useIsMutating({ mutationKey })`, `useMutationState` and defaults
+      // registered with `setMutationDefaults` can find this one too. An
+      // explicit `mutationKey` in the options still wins.
+      mutationKey: reactor.getQueryOptions({ functionName, callConfig })
+        .queryKey,
       ...options,
       mutationFn,
       onSuccess: handleSuccess,