@ic-reactor/react 3.12.3 → 3.12.5

package/src/hooks/useActorMethod.ts

@@ -14,10 +14,12 @@ import {
   TransformKey,
   ReactorArgs,
   ReactorReturnOk,
+  ReactorQueryData,
   ReactorReturnErr,
   FunctionType,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import { normalizeQueryData } from "../utils.js"
 
 /**
  * Configuration for useActorMethod hook.
@@ -33,10 +35,10 @@ export interface UseActorMethodParameters<
   Transform extends TransformKey = "candid",
 > extends Omit<
   QueryObserverOptions<
-    ReactorReturnOk<Service, Method, Transform>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     ReactorReturnErr<Service, Method, Transform>,
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnOk<Service, Method, Transform>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     QueryKey
   >,
   "queryKey" | "queryFn"
@@ -59,8 +61,13 @@ export interface UseActorMethodParameters<
   /**
    * Callback when the method call succeeds.
    * Works for both query and mutation methods.
+   *
+   * A method's `undefined` result arrives as `null`, as in `useActorQuery`,
+   * for query and update methods alike.
    */
-  onSuccess?: (data: ReactorReturnOk<Service, Method, Transform>) => void
+  onSuccess?: (
+    data: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
+  ) => void
 
   /**
    * Callback when the method call fails.
@@ -94,8 +101,13 @@ export interface UseActorMethodResult<
   Method extends FunctionName<Service> = FunctionName<Service>,
   Transform extends TransformKey = "candid",
 > {
-  /** The returned data from the method call */
-  data: ReactorReturnOk<Service, Method, Transform> | undefined
+  /**
+   * 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.
+   */
+  data:
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
 
   /** Whether the method is currently executing */
   isLoading: boolean
@@ -125,11 +137,16 @@ export interface UseActorMethodResult<
    */
   call: (
     args?: ReactorArgs<Service, Method, Transform>
-  ) => Promise<ReactorReturnOk<Service, Method, Transform> | undefined>
+  ) => Promise<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
+  >
 
   /**
-   * Reset the state (clear data and error).
-   * For queries: removes the query from cache
+   * Reset the state (data and error).
+   * For queries: resets this hook's own cache entry to its initial state, so
+   * `data` goes back to `initialData` when one was given and is cleared
+   * otherwise. An enabled hook then refetches. Other args of the same method
+   * are left alone.
    * For mutations: resets the mutation state
    */
   reset: () => void
@@ -138,19 +155,19 @@ export interface UseActorMethodResult<
    * For queries only: Refetch the query
    */
   refetch: () => Promise<
-    ReactorReturnOk<Service, Method, Transform> | undefined
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
   >
 
   // Expose underlying results for advanced use cases
   /** The raw query result (only available for query methods) */
   queryResult?: UseQueryResult<
-    ReactorReturnOk<Service, Method, Transform>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     ReactorReturnErr<Service, Method, Transform>
   >
 
   /** The raw mutation result (only available for mutation methods) */
   mutationResult?: UseMutationResult<
-    ReactorReturnOk<Service, Method, Transform>,
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     ReactorReturnErr<Service, Method, Transform>,
     ReactorArgs<Service, Method, Transform>
   >
@@ -180,6 +197,9 @@ export function useActorMethod<
   Method,
   Transform
 > {
+  type TData = ReactorReturnOk<Service, Method, Transform>
+  type TQueryData = ReactorQueryData<TData>
+
   // Determine if this is a query method by checking the IDL
   const isQuery = useMemo(() => {
     if (!reactor) throw new Error("Reactor instance is required")
@@ -227,7 +247,7 @@ export function useActorMethod<
   // ============================================================================
 
   const queryResult = useQuery<
-    ReactorReturnOk<Service, Method, Transform>,
+    TQueryData,
     ReactorReturnErr<Service, Method, Transform>
   >(
     {
@@ -237,12 +257,19 @@ export function useActorMethod<
       // 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,
-        }),
+      //
+      // TanStack Query fails a query whose queryFn resolves `undefined`, with
+      // "data is undefined", and a successful call can resolve it. A
+      // DisplayReactor decodes an `opt` None to `undefined`, and a `()` query
+      // returns nothing. Every other query path normalizes the value to `null`.
+      queryFn: async () =>
+        normalizeQueryData<TData>(
+          (await reactor.callMethod({
+            functionName,
+            args,
+            callConfig,
+          })) as TData
+        ),
       enabled: isQuery && enabled,
       ...queryOptions,
     },
@@ -282,26 +309,30 @@ export function useActorMethod<
   // ============================================================================
 
   const mutationResult = useMutation<
-    ReactorReturnOk<Service, Method, Transform>,
+    TQueryData,
     ReactorReturnErr<Service, Method, Transform>,
     ReactorArgs<Service, Method, Transform>
   >(
     {
       mutationKey: queryKey,
-      mutationFn: async (mutationArgs) => {
-        const result = await reactor.callMethod({
-          functionName,
-          args: mutationArgs ?? args,
-          callConfig,
-        })
-        return result
-      },
+      // 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
+      // are queries.
+      mutationFn: async (mutationArgs) =>
+        normalizeQueryData<TData>(
+          (await reactor.callMethod({
+            functionName,
+            args: mutationArgs ?? args,
+            callConfig,
+          })) as TData
+        ),
       onSuccess: (data) => {
         onSuccessRef.current?.(data)
         // Invalidate specified queries after successful mutation
         if (invalidateQueries && invalidateQueries.length > 0) {
           invalidateQueries.forEach((key) => {
-            reactor.queryClient.invalidateQueries({ queryKey: key })
+            void reactor.queryClient.invalidateQueries({ queryKey: key })
           })
         }
       },
@@ -319,7 +350,7 @@ export function useActorMethod<
   const call = useCallback(
     async (
       callArgs?: ReactorArgs<Service, Method, Transform>
-    ): Promise<ReactorReturnOk<Service, Method, Transform> | undefined> => {
+    ): Promise<TQueryData | undefined> => {
       if (isQuery) {
         // For queries, refetch with new args if provided
         if (callArgs !== undefined) {
@@ -329,14 +360,17 @@ export function useActorMethod<
           // 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({
+            const result = await reactor.queryClient.fetchQuery<TQueryData>({
               queryKey: buildQueryKey(callArgs),
-              queryFn: () =>
-                reactor.callMethod({
-                  functionName,
-                  args: callArgs,
-                  callConfig,
-                }),
+              // 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
@@ -380,7 +414,14 @@ export function useActorMethod<
 
   const reset = useCallback(() => {
     if (isQuery) {
-      reactor.queryClient.removeQueries({ queryKey })
+      // Reset, not remove. `removeQueries` drops the entry without notifying
+      // its observers, so this hook kept rendering the old data while bound to
+      // a query that was no longer in the cache. No later invalidation reached
+      // it, including the one an identity switch runs. `resetQueries` notifies
+      // the observer and refetches the entry when the hook is enabled. It is
+      // `exact` because only this hook's entry should reset. A prefix match on
+      // a no-args key would also reset every args variant other hooks render.
+      void reactor.queryClient.resetQueries({ queryKey, exact: true })
     } else {
       mutationResult.reset()
     }

package/src/hooks/useActorMutation.ts

@@ -24,11 +24,13 @@ 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"
 > {
@@ -51,7 +53,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 +65,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
 >
 
 /**
@@ -100,6 +109,7 @@ export const useActorMutation = <
   Service,
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
+  TOnMutateResult = unknown,
 >({
   reactor,
   functionName,
@@ -112,8 +122,9 @@ export const useActorMutation = <
 }: UseActorMutationParameters<
   Service,
   Method,
-  Transform
->): UseActorMutationResult<Service, Method, Transform> => {
+  Transform,
+  TOnMutateResult
+>): UseActorMutationResult<Service, Method, Transform, TOnMutateResult> => {
   const mutationFn = useCallback(
     async (args: ReactorArgs<Service, Method, Transform>) =>
       reactor.callMethod({ functionName, callConfig, args }),
@@ -127,7 +138,8 @@ export const useActorMutation = <
           UseMutationOptions<
             ReactorReturnOk<Service, Method, Transform>,
             ReactorReturnErr<Service, Method, Transform>,
-            ReactorArgs<Service, Method, Transform>
+            ReactorArgs<Service, Method, Transform>,
+            TOnMutateResult
           >["onSuccess"]
         >
       >
@@ -153,7 +165,7 @@ export const useActorMutation = <
   )
 
   const handleError = useCallback(
-    (
+    async (
       error: ReactorReturnErr<Service, Method, Transform>,
       variables: ReactorArgs<Service, Method, Transform>,
       context: unknown,
@@ -162,7 +174,10 @@ export const useActorMutation = <
       if (isCanisterError(error)) {
         onCanisterError?.(error as any, variables)
       }
-      onError?.(error, variables, context as any, mutation as any)
+      // Awaited like `onSuccess` above. TanStack Query waits for the promise
+      // `onError` returns before it runs `onSettled` and settles the mutation,
+      // and it can only wait for a promise this wrapper passes back.
+      await onError?.(error, variables, context as any, mutation as any)
     },
     [onCanisterError, onError]
   )

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -67,12 +67,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 +87,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>
 >
 
@@ -107,6 +113,10 @@ export const useActorSuspenseInfiniteQuery = <
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 >({
   reactor,
   functionName,
@@ -118,12 +128,14 @@ export const useActorSuspenseInfiniteQuery = <
   Service,
   Method,
   Transform,
-  TPageParam
+  TPageParam,
+  Selected
 >): UseActorSuspenseInfiniteQueryResult<
   Service,
   Method,
   Transform,
-  TPageParam
+  TPageParam,
+  Selected
 > => {
   // Always pass queryKey through generateQueryKey so it is merged with the
   // reactor/function identity. Using the custom key verbatim would cause cache
@@ -187,6 +199,7 @@ export const useActorSuspenseInfiniteQuery = <
     Service,
     Method,
     Transform,
-    TPageParam
+    TPageParam,
+    Selected
   >
 }

package/src/types.ts

@@ -339,16 +339,21 @@ export interface SuspenseQueryResult<
 
 /**
  * Configuration for createMutation and useActorMutation.
+ *
+ * @template TOnMutateResult - The value `onMutate` returns, which `onSuccess`,
+ * `onError` and `onSettled` receive. TypeScript infers it from `onMutate`.
  */
 export interface MutationConfig<
   Service = BaseActor,
   Method extends FunctionName<Service> = 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"
 > {
@@ -387,7 +392,12 @@ export interface MutationConfig<
    * ```
    */
   onCanisterError?: (
-    error: CanisterError<unknown>,
+    error: CanisterError<
+      TransformReturnRegistry<
+        ErrResult<ActorMethodReturnType<Service[Method]>>,
+        Service
+      >[Transform]
+    >,
     variables: ReactorArgs<Service, Method, Transform>
   ) => void
 }
@@ -399,21 +409,30 @@ export type MutationFactoryConfig<
   Service = BaseActor,
   Method extends FunctionName<Service> = FunctionName<Service>,
   Transform extends TransformKey = "candid",
-> = Omit<MutationConfig<Service, Method, Transform>, "onSuccess">
+  TOnMutateResult = unknown,
+> = Omit<
+  MutationConfig<Service, Method, Transform, TOnMutateResult>,
+  "onSuccess"
+>
 
 /**
  * Options for useMutation hook.
  * Extends React Query's UseMutationOptions with invalidateQueries support.
+ *
+ * @template TOnMutateResult - The value `onMutate` returns, which `onSuccess`,
+ * `onError` and `onSettled` receive. TypeScript infers it from `onMutate`.
  */
 export interface MutationHookOptions<
   Service = BaseActor,
   Method extends FunctionName<Service> = 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"
 > {
@@ -438,7 +457,8 @@ export interface MutationHookOptions<
   onCanisterError?: (
     error: CanisterError<
       TransformReturnRegistry<
-        ErrResult<ActorMethodReturnType<Service[Method]>>
+        ErrResult<ActorMethodReturnType<Service[Method]>>,
+        Service
       >[Transform]
     >,
     variables: ReactorArgs<Service, Method, Transform>
@@ -463,12 +483,13 @@ export interface MutationResult<
    *   invalidateQueries: [userBalanceQuery], // Auto-invalidate after success!
    * })
    */
-  useMutation: (
-    options?: MutationHookOptions<Service, Method, Transform>
+  useMutation: <TOnMutateResult = unknown>(
+    options?: MutationHookOptions<Service, Method, Transform, TOnMutateResult>
   ) => UseMutationResult<
     ReactorReturnOk<Service, Method, Transform>,
     ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>
+    ReactorArgs<Service, Method, Transform>,
+    TOnMutateResult
   >
 
   /** Execute the update call directly (outside of React) */