@ic-reactor/react 3.12.4 → 3.13.0

package/src/hooks/createAuthHooks.ts

@@ -10,6 +10,13 @@ export interface UseAuthReturn {
   login: (options?: AuthenticationSignInOptions) => Promise<void>
   logout: (options?: { returnTo?: string }) => Promise<void>
   isAuthenticated: boolean
+  /**
+   * `true` while a sign-in or sign-out is in progress, and until the session
+   * restore the first `useAuth()` starts has settled: on the first render, in
+   * a server render and while the stored session is read. A restore that fails
+   * settles it too. Show a loading state while it is `true` rather than
+   * treating `isAuthenticated: false` as signed out.
+   */
   isAuthenticating: boolean
   /**
    * The signed-in user's principal, or `null` while signed out. A signed-out
@@ -27,6 +34,31 @@ export interface CreateAuthHooksReturn {
   useAuth: () => UseAuthReturn
 }
 
+/**
+ * The managers whose session a `useAuth()` has already started restoring.
+ *
+ * Restoring ends in `authenticate()`, which publishes `isAuthenticating: true`
+ * and then the restored state. It used to run once per mounted `useAuth()`
+ * rather than once per manager, so every consumer that mounted while signed out
+ * flipped `isAuthenticating` for the whole app, and one that mounted while a
+ * sign-in popup was open cleared `isAuthenticating` before the sign-in ended. A
+ * component that hides a `useAuth()` consumer while `isAuthenticating` never
+ * settled: each restore unmounted the consumer, and each remount restored
+ * again. Both clients answer from memory once loaded, so that loop ran on the
+ * microtask queue and the page never painted again.
+ *
+ * Keyed by manager rather than by `createAuthHooks` call, because reactors that
+ * share one `AuthenticationManager` each build their own hooks.
+ */
+const restoredSessions = new WeakSet<AuthenticationManager>()
+
+/**
+ * How many `useAuth()` consumers of each manager are mounted, so that a
+ * restore can tell a manager that was discarded from one StrictMode released
+ * and mounted again; see `useAuth()`.
+ */
+const mountedConsumers = new WeakMap<AuthenticationManager, number>()
+
 /**
  * The principal both hooks return.
  *
@@ -47,6 +79,31 @@ function usePrincipal(
   )
 }
 
+/**
+ * The auth state a server render shows, and so the one hydration shows.
+ *
+ * `useSyncExternalStore` renders `getServerSnapshot` on the server and again
+ * while hydrating, and both renders have to produce the HTML the server sent.
+ * The hooks passed the live state for both. A server holds no session, so its
+ * HTML is signed out. A component that hydrates after the session is restored,
+ * such as one inside a Suspense boundary whose code arrives later, read the
+ * restored state and no longer matched that HTML. React then reported a
+ * hydration error and threw the boundary's server HTML away to render it again
+ * on the client. A constant also keeps a server render from showing whatever a
+ * manager shared across requests happens to hold.
+ *
+ * It is the state the hooks report before the session has been checked: a
+ * server cannot know the session, so it renders the "checking" state that a
+ * browser shows until its restore settles. Once hydrated, React compares it
+ * with the live state and renders again with that.
+ */
+const SERVER_AUTH_STATE: AuthState = Object.freeze({
+  identity: null,
+  isAuthenticating: true,
+  isAuthenticated: false,
+  error: undefined,
+})
+
 /**
  * Create authentication hooks for managing user sessions with Internet Identity.
  *
@@ -57,8 +114,8 @@ function usePrincipal(
  *   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 = (
@@ -83,16 +140,71 @@ export const createAuthHooks = (
   }
 
   const { clientManager } = authentication
+
+  // The agent state a manager starts in, for the reason given at
+  // SERVER_AUTH_STATE: `useAuth()` initializes the agent once hydrated, so a
+  // component hydrating later read `isInitialized: true` against server HTML
+  // rendered before any initialization. The network is kept: it comes from the
+  // agent's host, which initialization does not change.
+  const serverAgentState: AgentState = Object.freeze({
+    isInitialized: false,
+    isInitializing: false,
+    error: undefined,
+    network: clientManager.network,
+    isLocalhost: clientManager.isLocal,
+  })
+
+  // What every consumer hands `useSyncExternalStore`, built once rather than
+  // on each render. React unsubscribes and subscribes again whenever the
+  // subscribe function changes, and each unsubscribe filters the manager's
+  // whole subscriber list. An auth state change re-renders every consumer, so
+  // a function per render cost k re-subscriptions and about k²/2 subscriber
+  // visits for k consumers: two million for 2,000 `useUserPrincipal()` rows.
+  const subscribeAgentState = (callback: () => void) =>
+    clientManager.subscribeAgentState(callback)
+  const getAgentState = () => clientManager.agentState
+  const getServerAgentState = () => serverAgentState
+
+  // Until the session has been checked, `authState` is the signed-out state
+  // the manager starts in, and reporting it as the answer sent signed-in users
+  // to the login page (#621). `useAuth()` starts the check from an effect, so
+  // on the first render nothing had been checked, yet `isAuthenticating` was
+  // false: a guard that redirects when `!isAuthenticating && !isAuthenticated`
+  // redirected before the session was ever read. The hooks report
+  // `isAuthenticating: true` until the check settles instead. The snapshot is
+  // kept per source state, because `useSyncExternalStore` needs the same object
+  // back until something changes.
+  let unchecked: { source: AuthState; state: AuthState } | undefined
+  const subscribeAuthState = (callback: () => void) => {
+    const unsubscribeState = authentication.subscribeAuthState(callback)
+    const unsubscribeChecked = authentication.subscribeSessionChecked(callback)
+    return () => {
+      unsubscribeState()
+      unsubscribeChecked()
+    }
+  }
+  const getAuthState = () => {
+    const state = authentication.authState
+    if (authentication.sessionChecked || state.isAuthenticating) return state
+    if (unchecked?.source !== state) {
+      unchecked = {
+        source: state,
+        state: Object.freeze({ ...state, isAuthenticating: true }),
+      }
+    }
+    return unchecked.state
+  }
+  const getServerAuthState = () => SERVER_AUTH_STATE
+
   /**
    * Subscribe to agent state changes.
    * Returns the current agent state (agent, isInitialized, etc.)
    */
   const useAgentState = (): AgentState =>
     useSyncExternalStore(
-      (callback) => clientManager.subscribeAgentState(callback),
-      () => clientManager.agentState,
-      // Server snapshot - provide initial state for SSR
-      () => clientManager.agentState
+      subscribeAgentState,
+      getAgentState,
+      getServerAgentState
     )
 
   /**
@@ -100,26 +212,26 @@ export const createAuthHooks = (
    * Returns auth state (isAuthenticated, isAuthenticating, identity, error)
    */
   const useAuthState = (): AuthState =>
-    useSyncExternalStore(
-      (callback) => authentication.subscribeAuthState(callback),
-      () => authentication.authState,
-      // Server snapshot - provide initial state for SSR
-      () => authentication.authState
-    )
+    useSyncExternalStore(subscribeAuthState, getAuthState, getServerAuthState)
 
   /**
    * Main authentication hook that provides login/logout methods and auth state.
    * Automatically initializes the session on first use, restoring any previous session.
    *
+   * `isAuthenticating` is `true` until that restore has settled, including on
+   * the first render and in a server render, so a guard that shows a spinner
+   * while `isAuthenticating` never takes the state before the restore for a
+   * signed-out user. A restore that fails settles it too.
+   *
    * @example
    * function AuthButton() {
    *   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>
    *   )
@@ -130,24 +242,94 @@ export const createAuthHooks = (
     const { isAuthenticated, isAuthenticating, identity, error } =
       useAuthState()
 
-    // Track if we've already initialized to avoid duplicate calls
+    // Keeps a StrictMode re-run of the effect below from repeating it.
     const initializedRef = useRef(false)
 
-    // Auto-initialize on first mount to restore previous session.
-    // `prepareClient` also warms up the AuthClient so a later `login()` can
-    // open the identity provider window inside the click handler.
+    // Restore the previous session when the first consumer of this manager
+    // mounts. `prepareClient` also warms up the AuthClient so a later
+    // `login()` can open the identity provider window inside the click handler.
     useEffect(() => {
-      if (!initializedRef.current) {
-        initializedRef.current = true
-        authentication
-          .prepareClient()
-          .catch(() => undefined)
-          .then(() => clientManager.initialize())
-          .then(() => authentication.authenticate())
-          // Failures are already reflected in authState/agentState; without
-          // this the rejection escapes as an unhandled promise rejection.
-          .catch(() => undefined)
+      mountedConsumers.set(
+        authentication,
+        (mountedConsumers.get(authentication) ?? 0) + 1
+      )
+      const unmount = () => {
+        mountedConsumers.set(
+          authentication,
+          (mountedConsumers.get(authentication) ?? 1) - 1
+        )
       }
+
+      if (initializedRef.current && restoredSessions.has(authentication)) {
+        return unmount
+      }
+      const firstRun = !initializedRef.current
+      initializedRef.current = true
+
+      if (restoredSessions.has(authentication)) {
+        // Restored already. A live session is still checked again, which
+        // notices a delegation that has lapsed since and publishes nothing
+        // while it is valid.
+        if (firstRun && authentication.authState.isAuthenticated) {
+          authentication.authenticate().catch(() => undefined)
+        }
+        return unmount
+      }
+      restoredSessions.add(authentication)
+
+      // A provider that builds its managers per mount disposes the manager
+      // from its cleanup. One that unmounted before this restore had built
+      // the client still got one, built after `dispose()` and never released,
+      // so each quick remount left a live client listening to the page. The
+      // restore stops instead once the manager has been disposed since it
+      // began and no `useAuth()` of it is mounted, releasing what it built.
+      // StrictMode's cleanup disposes the manager too, but mounts this
+      // consumer again before the restore looks, and that restore goes on.
+      // One that stopped counts as not having run, so a manager mounted again,
+      // as `<Activity>` mounts a tree it showed again, restores.
+      const releases = authentication.releaseCount
+      const abandoned = () => {
+        if (
+          authentication.releaseCount === releases ||
+          (mountedConsumers.get(authentication) ?? 0) > 0
+        ) {
+          return false
+        }
+        authentication.dispose()
+        restoredSessions.delete(authentication)
+        return true
+      }
+
+      void authentication
+        .prepareClient()
+        .catch(() => undefined)
+        .then(async () => {
+          if (abandoned()) return false
+          await clientManager.initialize()
+          if (abandoned()) return false
+          // A check that has settled already and found no session, such as
+          // the one a manager runs over a client handed to its constructor,
+          // or a route loader's `authenticate()`, answered what this restore
+          // would. Running it again only flashed `isAuthenticating`, and a
+          // guard redirected a second time. A live session is still checked,
+          // which publishes nothing while it is valid.
+          const { isAuthenticated, error } = authentication.authState
+          if (authentication.sessionChecked && !isAuthenticated && !error) {
+            return true
+          }
+          await authentication.authenticate().catch(() => undefined)
+          return !abandoned()
+        })
+        // Failures are already reflected in authState/agentState; without
+        // this the rejection escapes as an unhandled promise rejection. A
+        // restore that failed before it reached `authenticate()`, such as a
+        // root key that could not be fetched, has settled all the same.
+        .catch(() => true)
+        .then((settled) => {
+          if (settled) authentication.markSessionChecked()
+        })
+
+      return unmount
     }, [])
 
     const principal = usePrincipal(isAuthenticated, identity)

package/src/hooks/useActorInfiniteQuery.ts

@@ -1,10 +1,12 @@
-import { useMemo, useCallback } from "react"
+import { useMemo } from "react"
 import {
   QueryKey,
   useInfiniteQuery,
+  skipToken,
   UseInfiniteQueryResult,
   UseInfiniteQueryOptions,
   InfiniteData,
+  type SkipToken,
 } from "@tanstack/react-query"
 import {
   FunctionName,
@@ -16,7 +18,14 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
+import {
+  callConfigForKey,
+  mergeFactoryQueryKey,
+  normalizeQueryData,
+  retryOption,
+  skippedQueryKey,
+  useMountQueryClient,
+} from "../utils.js"
 
 /**
  * Parameters for useActorInfiniteQuery hook.
@@ -45,8 +54,27 @@ export interface UseActorInfiniteQueryParameters<
   reactor: Reactor<Service, Transform>
   /** The method name to call on the canister */
   functionName: Method
-  /** Function to get args from page parameter */
-  getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
+  /**
+   * Function to get args from page parameter, or TanStack Query's `skipToken`
+   * while the args are not known: the query then waits without fetching, in
+   * an entry of its own under its method and `queryKey`, which no call's key
+   * shares, so it shows no data until the args arrive.
+   */
+  getArgs:
+    | ((pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>)
+    | SkipToken
+  /**
+   * 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,8 +95,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 +115,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>
 >
 
@@ -89,10 +128,21 @@ export type UseActorInfiniteQueryResult<
  * Hook for executing infinite/paginated query calls on a canister.
  *
  * @example
- * const { data, fetchNextPage, hasNextPage } = useActorInfiniteQuery({
+ * const { data, fetchNextPage, hasNextPage } = useReactorInfiniteQuery({
  *   reactor,
  *   functionName: "getItems",
- *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }],
+ *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }] as const,
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextOffset,
+ * })
+ *
+ * // Wait for the args: no fetch until userId is known
+ * const { data } = useReactorInfiniteQuery({
+ *   reactor,
+ *   functionName: "getUserItems",
+ *   getArgs: userId
+ *     ? (pageParam) => [{ userId, offset: pageParam, limit: 10 }] as const
+ *     : skipToken,
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextOffset,
  * })
@@ -102,10 +152,15 @@ export const useActorInfiniteQuery = <
   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
@@ -113,65 +168,111 @@ export const useActorInfiniteQuery = <
   Service,
   Method,
   Transform,
-  TPageParam
->): UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam> => {
+  TPageParam,
+  Selected
+>): UseActorInfiniteQueryResult<
+  Service,
+  Method,
+  Transform,
+  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(() => {
+    // Waiting for its args: an entry of its own under the method and the
+    // custom key, which every key the args will give extends; see
+    // skippedQueryKey.
+    if (getArgs === skipToken) {
+      return skippedQueryKey(
+        reactor.generateQueryKey(
+          { functionName, queryKey: mergeFactoryQueryKey(queryKey) },
+          callConfig
+        ),
+        "infinite"
+      )
+    }
+    // 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
 
-  // Memoize queryFn to prevent recreation on every render
-  const queryFn = useCallback(
-    async ({ pageParam }: { pageParam: TPageParam }) => {
-      const args = getArgs(pageParam)
-      const result = await reactor.callMethod({
+    return reactor.generateQueryKey(
+      {
         functionName,
-        args,
-        callConfig,
-      })
-      return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
-        result as ReactorReturnOk<Service, Method, Transform>
-      )
-    },
+        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 = useMemo(
+    () =>
+      getArgs === skipToken
+        ? skipToken
+        : async ({
+            pageParam,
+            queryKey: fetchedKey,
+          }: {
+            pageParam: TPageParam
+            queryKey: QueryKey
+          }) => {
+            const args = getArgs(pageParam)
+            const result = await reactor.callMethod({
+              functionName,
+              args,
+              callConfig: callConfigForKey(fetchedKey, callConfig),
+            })
+            return normalizeQueryData<
+              ReactorReturnOk<Service, Method, Transform>
+            >(result as ReactorReturnOk<Service, Method, Transform>)
+          },
     [reactor, functionName, getArgs, callConfig]
   )
 
+  // 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]
+  )
+
   return useInfiniteQuery(
     {
       queryKey: baseQueryKey,
       queryFn,
       ...options,
+      ...retryOption(options.retry, defaultRetry),
     } as any,
     reactor.queryClient
-  ) as UseActorInfiniteQueryResult<Service, Method, Transform, TPageParam>
+  ) as UseActorInfiniteQueryResult<
+    Service,
+    Method,
+    Transform,
+    TPageParam,
+    Selected
+  >
 }