@ic-reactor/react 3.12.4 → 3.13.0

package/src/hooks/useActorMutation.ts

@@ -3,7 +3,6 @@ import {
   useMutation,
   UseMutationOptions,
   UseMutationResult,
-  QueryKey,
 } from "@tanstack/react-query"
 import {
   Reactor,
@@ -19,16 +18,20 @@ 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,
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
+  TOnMutateResult = unknown,
 > extends Omit<
   UseMutationOptions<
     ReactorReturnOk<Service, Method, Transform>,
     ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>
+    ReactorArgs<Service, Method, Transform>,
+    TOnMutateResult
   >,
   "mutationFn"
 > {
@@ -36,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.
@@ -51,7 +56,8 @@ export interface UseActorMutationParameters<
   onCanisterError?: (
     error: CanisterError<
       TransformReturnRegistry<
-        ErrResult<ActorMethodReturnType<Service[Method]>>
+        ErrResult<ActorMethodReturnType<Service[Method]>>,
+        Service
       >[Transform]
     >,
     variables: ReactorArgs<Service, Method, Transform>
@@ -62,16 +68,22 @@ export type UseActorMutationConfig<
   Service,
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
-> = Omit<UseActorMutationParameters<Service, Method, Transform>, "reactor">
+  TOnMutateResult = unknown,
+> = Omit<
+  UseActorMutationParameters<Service, Method, Transform, TOnMutateResult>,
+  "reactor"
+>
 
 export type UseActorMutationResult<
   Service,
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
+  TOnMutateResult = unknown,
 > = UseMutationResult<
   ReactorReturnOk<Service, Method, Transform>,
   ReactorReturnErr<Service, Method, Transform>,
-  ReactorArgs<Service, Method, Transform>
+  ReactorArgs<Service, Method, Transform>,
+  TOnMutateResult
 >
 
 /**
@@ -80,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!"),
@@ -100,6 +112,7 @@ export const useActorMutation = <
   Service,
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
+  TOnMutateResult = unknown,
 >({
   reactor,
   functionName,
@@ -112,8 +125,11 @@ export const useActorMutation = <
 }: UseActorMutationParameters<
   Service,
   Method,
-  Transform
->): UseActorMutationResult<Service, Method, Transform> => {
+  Transform,
+  TOnMutateResult
+>): UseActorMutationResult<Service, Method, Transform, TOnMutateResult> => {
+  useMountQueryClient(reactor.queryClient)
+
   const mutationFn = useCallback(
     async (args: ReactorArgs<Service, Method, Transform>) =>
       reactor.callMethod({ functionName, callConfig, args }),
@@ -127,29 +143,19 @@ export const useActorMutation = <
           UseMutationOptions<
             ReactorReturnOk<Service, Method, Transform>,
             ReactorReturnErr<Service, Method, Transform>,
-            ReactorArgs<Service, Method, Transform>
+            ReactorArgs<Service, Method, Transform>,
+            TOnMutateResult
           >["onSuccess"]
         >
       >
     ) => {
-      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(
@@ -183,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,

package/src/hooks/useActorQuery.ts

@@ -2,8 +2,10 @@ import { useMemo } from "react"
 import {
   QueryKey,
   useQuery,
+  skipToken,
   QueryObserverOptions,
   UseQueryResult,
+  type SkipToken,
 } from "@tanstack/react-query"
 import {
   FunctionName,
@@ -15,6 +17,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import { retryOption, skippedQueryKey, useMountQueryClient } from "../utils.js"
 
 export interface UseActorQueryParameters<
   Service,
@@ -33,7 +36,13 @@ export interface UseActorQueryParameters<
 > {
   reactor: Reactor<Service, Transform>
   functionName: Method
-  args?: ReactorArgs<Service, Method, Transform>
+  /**
+   * The method's arguments, or TanStack Query's `skipToken` while they are
+   * not known: the query then waits without fetching, in an entry of its own
+   * under its method's key, which no call's key shares, so it shows no data
+   * until the arguments arrive.
+   */
+  args?: ReactorArgs<Service, Method, Transform> | SkipToken
   callConfig?: CallConfig
   queryKey?: QueryKey
 }
@@ -59,19 +68,26 @@ export type UseActorQueryResult<
  * Hook for executing query calls on a canister.
  *
  * @example
- * const { data, isLoading } = useActorQuery({
+ * const { data, isLoading } = useReactorQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
  * })
  *
  * // With select transformation
- * const { data } = useActorQuery({
+ * const { data } = useReactorQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
  *   select: (user) => user.name,
  * })
+ *
+ * // Wait for the args: no fetch until userId is known
+ * const { data } = useReactorQuery({
+ *   reactor,
+ *   functionName: "getUser",
+ *   args: userId ? [userId] : skipToken,
+ * })
  */
 export const useActorQuery = <
   Service,
@@ -91,15 +107,31 @@ export const useActorQuery = <
   Transform,
   Selected
 >): UseActorQueryResult<Service, Method, Transform, Selected> => {
+  useMountQueryClient(reactor.queryClient)
+
   // Memoize query options to prevent unnecessary re-computations
-  const { queryKey, queryFn } = useMemo(
+  // For an update method, the options also carry its default `retry`; see
+  // `Reactor.getQueryRetry`.
+  const { queryKey, queryFn, retry } = useMemo(
     () =>
-      reactor.getQueryOptions<Method>({
-        callConfig,
-        functionName,
-        args,
-        queryKey: defaultQueryKey,
-      }),
+      args === skipToken
+        ? // Waiting for its args: an entry of its own under the method's key,
+          // with nothing to run until then; see skippedQueryKey.
+          {
+            queryKey: skippedQueryKey(
+              reactor.generateQueryKey({ functionName }, callConfig),
+              "query"
+            ),
+            // Kept as the unique symbol, which an object literal widens.
+            queryFn: skipToken as SkipToken,
+            retry: undefined,
+          }
+        : reactor.getQueryOptions<Method>({
+            callConfig,
+            functionName,
+            args,
+            queryKey: defaultQueryKey,
+          }),
     // `canisterId` is mutable reactor state that `setCanisterId` can change,
     // while `reactor` itself stays the same object — so it has to be a
     // dependency in its own right or the key stays pinned to the old canister.
@@ -118,6 +150,7 @@ export const useActorQuery = <
       queryFn,
       ...options,
       queryKey,
+      ...retryOption(options.retry, retry),
     },
     reactor.queryClient
   )

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -16,7 +16,14 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
+import {
+  callConfigForKey,
+  mergeFactoryQueryKey,
+  mountWhileSuspended,
+  normalizeQueryData,
+  retryOption,
+  useMountQueryClient,
+} from "../utils.js"
 
 /**
  * Parameters for useActorSuspenseInfiniteQuery hook.
@@ -47,6 +54,18 @@ export interface UseActorSuspenseInfiniteQueryParameters<
   functionName: Method
   /** 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 — return the stable, serializable
+   * portion (typically everything except the pagination field). It is required
+   * when `initialPageParam` changes between renders, as `Date.now()` does:
+   * without it every render keys a new query.
+   */
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
   /** Agent call configuration (effectiveCanisterId, etc.) */
   callConfig?: CallConfig
   /** Custom query key (auto-generated if not provided) */
@@ -67,12 +86,17 @@ export type UseActorSuspenseInfiniteQueryConfig<
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 > = Omit<
   UseActorSuspenseInfiniteQueryParameters<
     Service,
     Method,
     Transform,
-    TPageParam
+    TPageParam,
+    Selected
   >,
   "reactor"
 >
@@ -82,11 +106,12 @@ export type UseActorSuspenseInfiniteQueryResult<
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
-> = UseSuspenseInfiniteQueryResult<
-  InfiniteData<
+  Selected = InfiniteData<
     ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     TPageParam
   >,
+> = UseSuspenseInfiniteQueryResult<
+  Selected,
   ReactorReturnErr<Service, Method, Transform>
 >
 
@@ -94,10 +119,10 @@ export type UseActorSuspenseInfiniteQueryResult<
  * Hook for executing suspense-enabled infinite/paginated query calls on a canister.
  *
  * @example
- * const { data, fetchNextPage, hasNextPage } = useActorSuspenseInfiniteQuery({
+ * const { data, fetchNextPage, hasNextPage } = useReactorSuspenseInfiniteQuery({
  *   reactor,
  *   functionName: "getItems",
- *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }],
+ *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }] as const,
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextOffset,
  * })
@@ -107,10 +132,15 @@ export const useActorSuspenseInfiniteQuery = <
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 >({
   reactor,
   functionName,
   getArgs,
+  getKeyArgs,
   callConfig,
   queryKey,
   ...options
@@ -118,56 +148,68 @@ export const useActorSuspenseInfiniteQuery = <
   Service,
   Method,
   Transform,
-  TPageParam
+  TPageParam,
+  Selected
 >): UseActorSuspenseInfiniteQueryResult<
   Service,
   Method,
   Transform,
-  TPageParam
+  TPageParam,
+  Selected
 > => {
+  useMountQueryClient(reactor.queryClient)
+
   // 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(
-    () =>
-      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,
-      // `canisterId` is mutable reactor state that `setCanisterId` can change,
-      // while `reactor` itself stays the same object — so it has to be a
-      // dependency in its own right or the key stays pinned to the old canister
-      // while the queryFn already calls the new one.
-      reactor.canisterId?.toString(),
-      functionName,
-      callConfig,
-      getArgs,
-      options.initialPageParam,
-    ]
-  )
+  const baseQueryKey = useMemo(() => {
+    // 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. `getKeyArgs` narrows them exactly as it does for the
+    // factories, which the bound hook's config type always accepted: it used
+    // to be ignored here, so the cursor stayed in the key, and an
+    // `initialPageParam` that changes every render (`Date.now()`) keyed a new
+    // query on every render — an endless loop of first-page fetches.
+    const initialArgs = getArgs(options.initialPageParam)
+    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
+
+    return reactor.generateQueryKey(
+      {
+        functionName,
+        queryKey: mergeFactoryQueryKey(queryKey, undefined, keyArgs),
+      },
+      callConfig
+    )
+  }, [
+    queryKey,
+    reactor,
+    // `canisterId` is mutable reactor state that `setCanisterId` can change,
+    // while `reactor` itself stays the same object — so it has to be a
+    // dependency in its own right or the key stays pinned to the old canister
+    // while the queryFn already calls the new one.
+    reactor.canisterId?.toString(),
+    functionName,
+    callConfig,
+    getArgs,
+    getKeyArgs,
+    options.initialPageParam,
+  ])
 
   // Memoize queryFn to prevent recreation on every render
   const queryFn = useCallback(
-    async ({ pageParam }: { pageParam: TPageParam }) => {
+    async ({
+      pageParam,
+      queryKey: fetchedKey,
+    }: {
+      pageParam: TPageParam
+      queryKey: QueryKey
+    }) => {
       const args = getArgs(pageParam)
       const result = await reactor.callMethod({
         functionName,
         args,
-        callConfig,
+        callConfig: callConfigForKey(fetchedKey, callConfig),
       })
       return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
         result as ReactorReturnOk<Service, Method, Transform>
@@ -176,17 +218,31 @@ export const useActorSuspenseInfiniteQuery = <
     [reactor, functionName, getArgs, callConfig]
   )
 
-  return useSuspenseInfiniteQuery(
-    {
-      queryKey: baseQueryKey,
-      queryFn,
-      ...options,
-    } as any,
-    reactor.queryClient
-  ) as UseActorSuspenseInfiniteQueryResult<
-    Service,
-    Method,
-    Transform,
-    TPageParam
-  >
+  // The method's default `retry`: for an update method, only failures that
+  // prove the canister never ran the call; see `Reactor.getQueryRetry`.
+  const defaultRetry = useMemo(
+    () => reactor.getQueryRetry(functionName, baseQueryKey),
+    [reactor, functionName, baseQueryKey]
+  )
+
+  try {
+    return useSuspenseInfiniteQuery(
+      {
+        queryKey: baseQueryKey,
+        queryFn,
+        ...options,
+        ...retryOption(options.retry, defaultRetry),
+      } as any,
+      reactor.queryClient
+    ) as UseActorSuspenseInfiniteQueryResult<
+      Service,
+      Method,
+      Transform,
+      TPageParam,
+      Selected
+    >
+  } catch (thrown) {
+    mountWhileSuspended(reactor.queryClient, thrown)
+    throw thrown
+  }
 }

package/src/hooks/useActorSuspenseQuery.ts

@@ -16,6 +16,11 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import {
+  mountWhileSuspended,
+  retryOption,
+  useMountQueryClient,
+} from "../utils.js"
 
 export interface UseActorSuspenseQueryParameters<
   Service,
@@ -63,14 +68,14 @@ export type UseActorSuspenseQueryResult<
  * Hook for executing suspense-enabled query calls on a canister.
  *
  * @example
- * const { data } = useActorSuspenseQuery({
+ * const { data } = useReactorSuspenseQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
  * })
  *
  * // With select transformation
- * const { data } = useActorSuspenseQuery({
+ * const { data } = useReactorSuspenseQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
@@ -95,8 +100,12 @@ export const useActorSuspenseQuery = <
   Transform,
   Selected
 >): UseActorSuspenseQueryResult<Service, Method, Transform, Selected> => {
+  useMountQueryClient(reactor.queryClient)
+
   // Memoize query options to prevent unnecessary re-computations
-  const { queryKey, queryFn } = useMemo(
+  // For an update method, the options also carry its default `retry`; see
+  // `Reactor.getQueryRetry`.
+  const { queryKey, queryFn, retry } = useMemo(
     () =>
       reactor.getQueryOptions<Method>({
         callConfig,
@@ -117,16 +126,22 @@ export const useActorSuspenseQuery = <
     ]
   )
 
-  return useSuspenseQuery(
-    {
-      // Suspense queries don't support skipToken, so cast the queryFn
-      queryFn: queryFn as QueryFunction<
-        ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-        QueryKey
-      >,
-      ...options,
-      queryKey,
-    },
-    reactor.queryClient
-  )
+  try {
+    return useSuspenseQuery(
+      {
+        // Suspense queries don't support skipToken, so cast the queryFn
+        queryFn: queryFn as QueryFunction<
+          ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+          QueryKey
+        >,
+        ...options,
+        queryKey,
+        ...retryOption(options.retry, retry),
+      },
+      reactor.queryClient
+    )
+  } catch (thrown) {
+    mountWhileSuspended(reactor.queryClient, thrown)
+    throw thrown
+  }
 }

package/src/index.ts

@@ -11,6 +11,8 @@ export * from "./validation.js"
 // React-specific exports
 export * from "./createActorHooks.js"
 export * from "./defineReactor.js"
+export * from "./defineDisplayReactor.js"
+export * from "./createReactorProvider.js"
 
 export * from "./createQuery.js"
 export * from "./createSuspenseQuery.js"
@@ -21,3 +23,9 @@ export * from "./createMutation.js"
 export * from "./auth/index.js"
 
 export * from "./types.js"
+
+// TanStack Query's marker for a query whose args are not known yet, which the
+// non-suspense query hooks and createQueryFactory take in place of args. It is
+// the same symbol as @tanstack/react-query's, so either import works.
+export { skipToken } from "@tanstack/react-query"
+export type { SkipToken } from "@tanstack/react-query"