@ic-reactor/react 3.12.3 → 3.12.5

package/src/createMutation.ts

@@ -25,13 +25,17 @@
  * await transferMutation.execute([{ to: "aaaaa-aa", amount: "1000" }])
  */
 
-import { useMutation } from "@tanstack/react-query"
+import {
+  useMutation,
+  type MutationFunctionContext,
+} from "@tanstack/react-query"
 import type {
   Reactor,
   FunctionName,
   ReactorArgs,
   TransformKey,
   ReactorReturnOk,
+  ReactorReturnErr,
 } from "@ic-reactor/core"
 import { isCanisterError } from "@ic-reactor/core"
 import type {
@@ -65,9 +69,15 @@ const createMutationImpl = <
   Service,
   Method extends FunctionName<Service> = FunctionName<Service>,
   Transform extends TransformKey = "candid",
+  TOnMutateResult = unknown,
 >(
   reactor: Reactor<Service, Transform>,
-  config: MutationConfig<Service, Method, Transform>
+  config: MutationConfig<
+    Service,
+    Method,
+    Transform,
+    TOnMutateResult | undefined
+  >
 ): MutationResult<Service, Method, Transform> => {
   const {
     functionName,
@@ -91,6 +101,34 @@ const createMutationImpl = <
   ): Promise<ReactorReturnOk<Service, Method, Transform>> =>
     reactor.callMethod({ functionName, args, callConfig })
 
+  /**
+   * The factory's own `onMutate` result for each call through the hook.
+   *
+   * TanStack Query stores one `onMutate` result per mutation and hands it to
+   * every callback. That slot holds the hook's result, which the mutation also
+   * exposes as `context`, so this map holds the factory's. Each key is the
+   * context object TanStack Query creates for a call and passes to every
+   * callback of that call.
+   */
+  const factoryOnMutateResults = new WeakMap<
+    MutationFunctionContext,
+    TOnMutateResult | undefined
+  >()
+
+  /**
+   * The `onMutate` result a factory callback receives. A factory without its
+   * own `onMutate` gets the hook's, as it always has. TanStack Query before
+   * 5.89 passes no context, so there a factory callback gets the hook's result
+   * too.
+   */
+  const factoryOnMutateResult = (
+    onMutateResult: unknown,
+    context: MutationFunctionContext | undefined
+  ) =>
+    (factoryOnMutate && context
+      ? factoryOnMutateResults.get(context)
+      : onMutateResult) as TOnMutateResult | undefined
+
   /**
    * Imperative execution for non-React usage.
    *
@@ -99,6 +137,9 @@ const createMutationImpl = <
    * object behaves the same through both call paths. Only hook-level callbacks
    * are absent, because there is no hook here to supply them.
    *
+   * The callbacks get the same `{ client, meta, mutationKey }` context
+   * TanStack Query passes them on the hook path.
+   *
    * The error is rethrown after the callbacks run, so `await execute(...)`
    * still rejects for the caller.
    *
@@ -107,19 +148,45 @@ const createMutationImpl = <
   const execute = async (
     args: ReactorArgs<Service, Method, Transform>
   ): Promise<ReactorReturnOk<Service, Method, Transform>> => {
+    // TanStack Query builds this for the hook path, and the callback types
+    // declare it as always present. None of it is mutation state, so this path
+    // builds the same object. Passing `undefined` made a callback that reads
+    // `context.client` throw here and nowhere else.
+    //
+    // The hook path takes `meta` and `mutationKey` from the client's defaulted
+    // options, so this runs the same spread through `defaultMutationOptions`.
+    // Reading `factoryOptions` alone dropped mutation defaults registered on
+    // the QueryClient (`defaultOptions.mutations`, `setMutationDefaults`).
+    const effectiveOptions = reactor.queryClient.defaultMutationOptions({
+      mutationKey: reactor.getQueryOptions({ functionName }).queryKey,
+      ...factoryOptions,
+    })
+    const context: MutationFunctionContext = {
+      client: reactor.queryClient,
+      meta: effectiveOptions.meta,
+      mutationKey: effectiveOptions.mutationKey,
+    }
+
     let result: ReactorReturnOk<Service, Method, Transform>
     try {
       result = await callFn(args)
     } catch (error) {
       if (isCanisterError(error)) {
-        factoryOnCanisterError?.(error, args)
+        // `catch` drops the type. `callMethod` rejects with this method's
+        // CanisterError, the one the hook path narrows to.
+        factoryOnCanisterError?.(
+          error as Parameters<NonNullable<typeof factoryOnCanisterError>>[0],
+          args
+        )
       }
-      // No mutation context or instance exists on the imperative path.
-      factoryOnError?.(
+      // `onMutate` does not run on this path, so there is no result to pass.
+      // Awaited like `onSuccess` below and like the hook path, so an async
+      // rollback or report finishes before `execute()` rejects.
+      await factoryOnError?.(
         error as Parameters<NonNullable<typeof factoryOnError>>[0],
         args,
-        undefined as never,
-        undefined as never
+        undefined,
+        context
       )
       throw error
     }
@@ -127,18 +194,18 @@ const createMutationImpl = <
     if (factoryInvalidateQueries) {
       await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
     }
-    await factoryOnSuccess?.(
-      result,
-      args,
-      undefined as never,
-      undefined as never
-    )
+    await factoryOnSuccess?.(result, args, undefined, context)
     return result
   }
 
   // Hook implementation
-  const useMutationHook = (
-    options?: MutationHookOptions<Service, Method, Transform>
+  const useMutationHook = <THookOnMutateResult = unknown>(
+    options?: MutationHookOptions<
+      Service,
+      Method,
+      Transform,
+      THookOnMutateResult
+    >
   ) => {
     const baseOptions = reactor.getQueryOptions({ functionName })
     const {
@@ -147,7 +214,12 @@ const createMutationImpl = <
       ...restOptions
     } = options ?? {}
 
-    return useMutation(
+    return useMutation<
+      ReactorReturnOk<Service, Method, Transform>,
+      ReactorReturnErr<Service, Method, Transform>,
+      ReactorArgs<Service, Method, Transform>,
+      THookOnMutateResult
+    >(
       {
         mutationKey: baseOptions.queryKey,
         ...factoryOptions,
@@ -155,7 +227,7 @@ const createMutationImpl = <
         // Use callFn (not execute) to avoid double-invalidation:
         // factoryInvalidateQueries are handled in onSuccess below.
         mutationFn: callFn,
-        onSuccess: async (...args) => {
+        onSuccess: async (data, variables, onMutateResult, context) => {
           // 1. Factory-level invalidation
           if (factoryInvalidateQueries) {
             await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
@@ -165,17 +237,35 @@ const createMutationImpl = <
             await invalidateAll(reactor.queryClient, hookInvalidateQueries)
           }
           // 3. Factory onSuccess
-          await factoryOnSuccess?.(...args)
+          await factoryOnSuccess?.(
+            data,
+            variables,
+            factoryOnMutateResult(onMutateResult, context),
+            context
+          )
           // 4. Hook onSuccess
-          await restOptions.onSuccess?.(...args)
+          await restOptions.onSuccess?.(
+            data,
+            variables,
+            onMutateResult,
+            context
+          )
         },
-        onError: (error, variables, context, mutation) => {
+        onError: async (error, variables, onMutateResult, context) => {
           if (isCanisterError(error)) {
             factoryOnCanisterError?.(error, variables)
             hookOnCanisterError?.(error, variables)
           }
-          factoryOnError?.(error, variables, context, mutation)
-          restOptions.onError?.(error, variables, context, mutation)
+          // Awaited in order, like `onSuccess`. TanStack Query holds
+          // `onSettled` and the settled state until this promise resolves, so
+          // an async `onError` must be part of it.
+          await factoryOnError?.(
+            error,
+            variables,
+            factoryOnMutateResult(onMutateResult, context),
+            context
+          )
+          await restOptions.onError?.(error, variables, onMutateResult, context)
         },
         // `onMutate` and `onSettled` are composed like `onSuccess`/`onError`
         // above. They used to arrive through the `...restOptions` spread, so a
@@ -183,13 +273,33 @@ const createMutationImpl = <
         // telemetry or logging simply vanished the moment any call site passed
         // its own, with no warning and no type error. Chaining is what a
         // reader who has seen `onSuccess` chain already expects.
-        onMutate: async (...params) => {
-          await factoryOnMutate?.(...params)
-          return await restOptions.onMutate?.(...params)
+        onMutate: async (variables, context) => {
+          if (factoryOnMutate) {
+            const result = await factoryOnMutate(variables, context)
+            if (context) factoryOnMutateResults.set(context, result)
+          }
+          // Without a hook-level `onMutate` this is `undefined`, and
+          // THookOnMutateResult is then `unknown`.
+          return (await restOptions.onMutate?.(
+            variables,
+            context
+          )) as THookOnMutateResult
         },
-        onSettled: async (...params) => {
-          await factoryOnSettled?.(...params)
-          await restOptions.onSettled?.(...params)
+        onSettled: async (data, error, variables, onMutateResult, context) => {
+          await factoryOnSettled?.(
+            data,
+            error,
+            variables,
+            factoryOnMutateResult(onMutateResult, context),
+            context
+          )
+          await restOptions.onSettled?.(
+            data,
+            error,
+            variables,
+            onMutateResult,
+            context
+          )
         },
       },
       reactor.queryClient
@@ -207,12 +317,25 @@ export function createMutation<
   Service,
   Transform extends TransformKey,
   Method extends FunctionName<Service> = FunctionName<Service>,
+  TOnMutateResult = unknown,
 >(
   reactor: Reactor<Service, Transform>,
-  config: MutationConfig<NoInfer<Service>, Method, Transform>
+  // `execute()` runs the factory's `onSuccess` and `onError` without running
+  // its `onMutate`, so their `onMutate` result can also be `undefined`.
+  config: MutationConfig<
+    NoInfer<Service>,
+    Method,
+    Transform,
+    TOnMutateResult | undefined
+  >
 ): MutationResult<Service, Method, Transform> {
   return createMutationImpl(
     reactor,
-    config as MutationConfig<Service, Method, Transform>
+    config as MutationConfig<
+      Service,
+      Method,
+      Transform,
+      TOnMutateResult | undefined
+    >
   )
 }

package/src/defineReactor.ts

@@ -175,7 +175,6 @@ export function defineReactor<Service = BaseActor>(
 
 export function defineReactor<Service = BaseActor>(
   params: DefineReactorParameters | DefineDisplayReactorParameters<Service>
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): DefineReactorResult<Service, any, any> {
   const {
     clientManager: providedClientManager,
@@ -267,7 +266,7 @@ export function defineReactor<Service = BaseActor>(
   // The Reactor / DisplayReactor union cannot be expressed through the shared
   // implementation signature, so the body is intentionally untyped here; the
   // public overloads above carry the precise types for callers.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
   const reactor: any = display
     ? new DisplayReactor<Service>({
         ...reactorConfig,

package/src/hooks/createAuthHooks.ts

@@ -11,6 +11,11 @@ export interface UseAuthReturn {
   logout: (options?: { returnTo?: string }) => Promise<void>
   isAuthenticated: boolean
   isAuthenticating: boolean
+  /**
+   * The signed-in user's principal, or `null` while signed out. A signed-out
+   * session still holds an anonymous `identity`, and its principal is not
+   * returned here.
+   */
   principal: Principal | null
   identity: Identity | null
   error: Error | undefined
@@ -22,6 +27,26 @@ export interface CreateAuthHooksReturn {
   useAuth: () => UseAuthReturn
 }
 
+/**
+ * The principal both hooks return.
+ *
+ * `authenticate()` and `logout()` leave the client's anonymous identity in
+ * `authState.identity` with `isAuthenticated: false`, so deriving the principal
+ * from the identity alone reported `2vxsx-fae` for a signed-out user, and
+ * `principal ? <SignedIn /> : <SignedOut />` rendered the signed-in branch.
+ * Memoized on the identity, because `getPrincipal()` may build a new object on
+ * each call and the result is often a hook dependency.
+ */
+function usePrincipal(
+  isAuthenticated: boolean,
+  identity: Identity | null
+): Principal | null {
+  return useMemo(
+    () => (isAuthenticated && identity ? identity.getPrincipal() : null),
+    [isAuthenticated, identity]
+  )
+}
+
 /**
  * Create authentication hooks for managing user sessions with Internet Identity.
  *
@@ -32,8 +57,8 @@ export interface CreateAuthHooksReturn {
  *   const { login, logout, principal, isAuthenticated } = useAuth()
  *
  *   return isAuthenticated
- *     ? <button onClick={logout}>Logout {principal?.toText()}</button>
- *     : <button onClick={login}>Login with II</button>
+ *     ? <button onClick={() => logout()}>Logout {principal?.toText()}</button>
+ *     : <button onClick={() => login()}>Login with II</button>
  * }
  */
 export const createAuthHooks = (
@@ -91,10 +116,10 @@ export const createAuthHooks = (
    *   const { login, logout, isAuthenticated, isAuthenticating } = useAuth()
    *
    *   if (isAuthenticated) {
-   *     return <button onClick={logout}>Logout</button>
+   *     return <button onClick={() => logout()}>Logout</button>
    *   }
    *   return (
-   *     <button onClick={login} disabled={isAuthenticating}>
+   *     <button onClick={() => login()} disabled={isAuthenticating}>
    *       {isAuthenticating ? "Connecting..." : "Login"}
    *     </button>
    *   )
@@ -125,10 +150,7 @@ export const createAuthHooks = (
       }
     }, [])
 
-    const principal = useMemo(
-      () => (identity ? identity.getPrincipal() : null),
-      [identity]
-    )
+    const principal = usePrincipal(isAuthenticated, identity)
 
     return {
       authenticate,
@@ -144,7 +166,8 @@ export const createAuthHooks = (
 
   /**
    * Get the current user's Principal.
-   * Returns null if not authenticated.
+   * Returns null if not authenticated, including while the signed-out session
+   * holds the anonymous identity.
    *
    * @example
    * function UserInfo() {
@@ -154,8 +177,8 @@ export const createAuthHooks = (
    * }
    */
   const useUserPrincipal = (): Principal | null => {
-    const { identity } = useAuthState()
-    return identity ? identity.getPrincipal() : null
+    const { isAuthenticated, identity } = useAuthState()
+    return usePrincipal(isAuthenticated, identity)
   }
 
   return {

package/src/hooks/useActorInfiniteQuery.ts

@@ -67,8 +67,18 @@ export type UseActorInfiniteQueryConfig<
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 > = Omit<
-  UseActorInfiniteQueryParameters<Service, Method, Transform, TPageParam>,
+  UseActorInfiniteQueryParameters<
+    Service,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  >,
   "reactor"
 >
 
@@ -77,11 +87,12 @@ export type UseActorInfiniteQueryResult<
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
-> = UseInfiniteQueryResult<
-  InfiniteData<
+  Selected = InfiniteData<
     ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
     TPageParam
   >,
+> = UseInfiniteQueryResult<
+  Selected,
   ReactorReturnErr<Service, Method, Transform>
 >
 
@@ -102,6 +113,10 @@ export const useActorInfiniteQuery = <
   Method extends FunctionName<Service>,
   Transform extends TransformKey = "candid",
   TPageParam = unknown,
+  Selected = InfiniteData<
+    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+    TPageParam
+  >,
 >({
   reactor,
   functionName,
@@ -113,8 +128,15 @@ export const useActorInfiniteQuery = <
   Service,
   Method,
   Transform,
-  TPageParam
->): UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam> => {
+  TPageParam,
+  Selected
+>): UseActorInfiniteQueryResult<
+  Service,
+  Method,
+  Transform,
+  TPageParam,
+  Selected
+> => {
   // 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.
@@ -173,5 +195,11 @@ export const useActorInfiniteQuery = <
       ...options,
     } as any,
     reactor.queryClient
-  ) as UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam>
+  ) as UseActorInfiniteQueryResult<
+    Service,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  >
 }