@ic-reactor/react 3.12.2 → 3.12.4

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.
  *
@@ -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/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

@@ -153,7 +153,7 @@ export const useActorMutation = <
   )
 
   const handleError = useCallback(
-    (
+    async (
       error: ReactorReturnErr<Service, Method, Transform>,
       variables: ReactorArgs<Service, Method, Transform>,
       context: unknown,
@@ -162,7 +162,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]
   )