@ic-reactor/react 3.7.0 → 3.9.0

package/src/createSuspenseQuery.ts

@@ -25,6 +25,7 @@ import type {
   ReactorArgs,
   TransformKey,
 } from "@ic-reactor/core"
+import { useMemo } from "react"
 import { useSuspenseQuery } from "@tanstack/react-query"
 import type {
   QueryFnData,
@@ -34,8 +35,8 @@ import type {
   SuspenseQueryResult,
   SuspenseQueryFactoryConfig,
   NoInfer,
-} from "./types"
-import { buildChainedSelect } from "./utils"
+} from "./types.js"
+import { buildChainedSelect } from "./utils.js"
 
 // ============================================================================
 // Internal Implementation
@@ -95,6 +96,12 @@ const createSuspenseQueryImpl = <
     TError
   > = (options: any): any => {
     const baseOptions = reactor.getQueryOptions(params)
+    // Memoized so the observer's select-result cache can hit; see
+    // buildChainedSelect. `select` comes from the factory config and is stable.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select, options?.select),
+      [options?.select]
+    )
     return useSuspenseQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -102,7 +109,7 @@ const createSuspenseQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: buildChainedSelect(select, options?.select),
+        select: chainedSelect,
       },
       reactor.queryClient
     )

package/src/defineReactor.ts

@@ -33,8 +33,26 @@
  *   name: "index",
  *   idlFactory: indexIdl,
  *   clientManager: ledger.clientManager,
+ *   authentication: ledger.authentication, // one Internet Identity session
  * })
  * ```
+ *
+ * @example Internet Identity is wired up out of the box
+ * ```typescript
+ * const { useAuth, useIdentityAttributes } = defineReactor<_SERVICE>({
+ *   name: "backend",
+ *   idlFactory,
+ *   // Needed when the app is served from more than one origin.
+ *   auth: { derivationOrigin: "https://app.example.com" },
+ * })
+ *
+ * function LoginButton() {
+ *   const { login, logout, isAuthenticated, principal } = useAuth()
+ *   return isAuthenticated
+ *     ? <button onClick={() => logout()}>{principal?.toText()}</button>
+ *     : <button onClick={() => login()}>Sign in</button>
+ * }
+ * ```
  */
 import { ClientManager, Reactor, DisplayReactor } from "@ic-reactor/core"
 import type {
@@ -45,7 +63,14 @@ import type {
   DisplayReactorParameters,
 } from "@ic-reactor/core"
 import { QueryClient } from "@tanstack/react-query"
-import { createActorHooks, ActorHooks } from "./createActorHooks"
+import { createActorHooks, ActorHooks } from "./createActorHooks.js"
+import { AuthenticationManager } from "./auth/authentication-manager.js"
+import { IdentityAttributesManager } from "./auth/identity-attributes-manager.js"
+import { createIdentityAttributeHooks } from "./auth/createIdentityAttributeHooks.js"
+import type { UseIdentityAttributesReturn } from "./auth/createIdentityAttributeHooks.js"
+import { createAuthHooks } from "./hooks/createAuthHooks.js"
+import type { CreateAuthHooksReturn } from "./hooks/createAuthHooks.js"
+import type { AuthenticationManagerParameters } from "./auth/authentication-manager.js"
 
 /** Options shared by both the standard and display variants of defineReactor. */
 export interface DefineReactorSharedParameters
@@ -55,13 +80,35 @@ export interface DefineReactorSharedParameters
   /**
    * Reuse an existing ClientManager (e.g. to share one agent across canisters).
    * When omitted, a ClientManager is created from the agent options below.
+   *
+   * A supplied or adopted manager brings its own agent and QueryClient, so
+   * `agentOptions` and `queryClient` apply only when this call creates one.
    */
   clientManager?: ClientManager
   /**
-   * Reuse an existing QueryClient. When omitted, the provided ClientManager's
-   * QueryClient is reused, or a new one is created.
+   * QueryClient for a ClientManager created by this call.
+   *
+   * Ignored when `clientManager` or `authentication` is supplied — queries run
+   * against that manager's own QueryClient, which is what is returned.
    */
   queryClient?: QueryClient
+  /**
+   * Reuse an existing AuthenticationManager, so several reactors share one
+   * Internet Identity session. When omitted, one is created for this reactor.
+   *
+   * Its `clientManager` is adopted for this reactor, so sign-in updates the
+   * same agent the reactor calls through. Supplying a different `clientManager`
+   * alongside it is rejected.
+   */
+  authentication?: AuthenticationManager
+  /**
+   * Internet Identity options forwarded to the AuthenticationManager
+   * (`identityProvider`, `derivationOrigin`, `idleOptions`, `storage`, …).
+   *
+   * Mutually exclusive with `authentication`: a manager built elsewhere is
+   * already configured, so these could not be applied to it.
+   */
+  auth?: Omit<AuthenticationManagerParameters, "clientManager">
 }
 
 /** Parameters for a standard (raw Candid types) reactor. */
@@ -83,11 +130,17 @@ export type DefineReactorResult<
   Service,
   Transform extends TransformKey,
   R extends Reactor<Service, Transform>,
-> = ActorHooks<Service, Transform> & {
-  reactor: R
-  clientManager: ClientManager
-  queryClient: QueryClient
-}
+> = ActorHooks<Service, Transform> &
+  CreateAuthHooksReturn & {
+    reactor: R
+    clientManager: ClientManager
+    queryClient: QueryClient
+    /** Internet Identity session manager backing `useAuth`. */
+    authentication: AuthenticationManager
+    /** Signed identity attribute requests backing `useIdentityAttributes`. */
+    identityAttributes: IdentityAttributesManager
+    useIdentityAttributes: () => UseIdentityAttributesReturn
+  }
 
 export function defineReactor<Service = BaseActor>(
   params: DefineDisplayReactorParameters<Service>
@@ -104,6 +157,8 @@ export function defineReactor<Service = BaseActor>(
   const {
     clientManager: providedClientManager,
     queryClient: providedQueryClient,
+    authentication: providedAuthentication,
+    auth,
     display,
     agentOptions,
     name,
@@ -112,18 +167,44 @@ export function defineReactor<Service = BaseActor>(
     pollingOptions,
   } = params as DefineDisplayReactorParameters<Service>
 
-  const queryClient =
-    providedQueryClient ??
-    providedClientManager?.queryClient ??
-    new QueryClient()
+  // A shared AuthenticationManager updates the identity on its own
+  // ClientManager. Giving this reactor a different one would leave its calls
+  // anonymous after sign-in, so adopt the manager's rather than building a new
+  // one, and refuse an explicit mismatch instead of splitting them silently.
+  if (
+    providedClientManager &&
+    providedAuthentication &&
+    providedAuthentication.clientManager !== providedClientManager
+  ) {
+    throw new Error(
+      `[ic-reactor] defineReactor("${name}") received an \`authentication\` manager bound to a different \`clientManager\`. ` +
+        `Sign-in would update the authentication manager's agent while this reactor calls through another one, ` +
+        `leaving its calls anonymous. Pass \`clientManager: authentication.clientManager\`, or omit \`clientManager\` to adopt it.`
+    )
+  }
+
+  // `auth` configures a manager this call would build; an existing one is
+  // already constructed, so these options could only be dropped on the floor.
+  if (providedAuthentication && auth) {
+    throw new Error(
+      `[ic-reactor] defineReactor("${name}") received both \`authentication\` and \`auth\`. ` +
+        `The supplied manager is already configured, so \`auth\` (${Object.keys(auth).join(", ")}) would be ignored. ` +
+        `Pass those options where that AuthenticationManager is created, or drop \`authentication\` to build one here.`
+    )
+  }
 
   const clientManager =
     providedClientManager ??
+    providedAuthentication?.clientManager ??
     new ClientManager({
-      queryClient,
+      queryClient: providedQueryClient ?? new QueryClient(),
       agentOptions,
     })
 
+  // Always report the QueryClient actually in use: when a ClientManager is
+  // supplied or adopted, its own QueryClient is the one queries run against.
+  const queryClient = clientManager.queryClient
+
   const reactorConfig = {
     clientManager,
     name,
@@ -146,5 +227,46 @@ export function defineReactor<Service = BaseActor>(
 
   const hooks = createActorHooks(reactor)
 
-  return { ...hooks, reactor, clientManager, queryClient }
+  // Auth is built on first use. `AuthenticationManager` dynamically imports the
+  // optional `@icp-sdk/auth` peer as soon as it is constructed, and reactors
+  // that never touch authentication should not pay for that.
+  let authenticationInstance: AuthenticationManager | undefined
+  const getAuthentication = () =>
+    (authenticationInstance ??=
+      providedAuthentication ??
+      new AuthenticationManager({ ...auth, clientManager }))
+
+  let identityAttributesInstance: IdentityAttributesManager | undefined
+  const getIdentityAttributes = () =>
+    (identityAttributesInstance ??= new IdentityAttributesManager(
+      getAuthentication()
+    ))
+
+  let authHooks: CreateAuthHooksReturn | undefined
+  const getAuthHooks = () =>
+    (authHooks ??= createAuthHooks(getAuthentication()))
+
+  let attributeHooks:
+    ReturnType<typeof createIdentityAttributeHooks> | undefined
+  const getAttributeHooks = () =>
+    (attributeHooks ??= createIdentityAttributeHooks(getIdentityAttributes()))
+
+  return {
+    ...hooks,
+    reactor,
+    clientManager,
+    queryClient,
+    // Stable wrappers: the hook call order inside them never changes, so the
+    // rules of hooks still hold.
+    useAuth: () => getAuthHooks().useAuth(),
+    useAgentState: () => getAuthHooks().useAgentState(),
+    useUserPrincipal: () => getAuthHooks().useUserPrincipal(),
+    useIdentityAttributes: () => getAttributeHooks().useIdentityAttributes(),
+    get authentication() {
+      return getAuthentication()
+    },
+    get identityAttributes() {
+      return getIdentityAttributes()
+    },
+  }
 }

package/src/hooks/createAuthHooks.ts

@@ -1,6 +1,6 @@
 import { useSyncExternalStore, useEffect, useRef, useMemo } from "react"
-import type { AuthenticationManager } from "../auth/authentication-manager"
-import type { AuthState, AuthenticationSignInOptions } from "../auth/types"
+import type { AuthenticationManager } from "../auth/authentication-manager.js"
+import type { AuthState, AuthenticationSignInOptions } from "../auth/types.js"
 import type { AgentState } from "@ic-reactor/core"
 import type { Principal } from "@icp-sdk/core/principal"
 import type { Identity } from "@icp-sdk/core/agent"
@@ -90,7 +90,9 @@ export const createAuthHooks = (
     // Track if we've already initialized to avoid duplicate calls
     const initializedRef = useRef(false)
 
-    // Auto-initialize on first mount to restore previous session
+    // 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.
     useEffect(() => {
       if (!initializedRef.current) {
         initializedRef.current = true
@@ -99,6 +101,9 @@ export const createAuthHooks = (
           .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)
       }
     }, [])
 

package/src/hooks/useActorInfiniteQuery.ts

@@ -16,7 +16,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils"
+import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorInfiniteQuery hook.
@@ -119,8 +119,30 @@ export const useActorInfiniteQuery = <
   // 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, queryKey }, callConfig),
-    [queryKey, reactor, functionName, callConfig]
+    () =>
+      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,
+      functionName,
+      callConfig,
+      getArgs,
+      options.initialPageParam,
+    ]
   )
 
   // Memoize queryFn to prevent recreation on every render

package/src/hooks/useActorMethod.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react"
+import { useCallback, useEffect, useMemo, useRef } from "react"
 import {
   useQuery,
   useMutation,
@@ -188,17 +188,30 @@ export function useActorMethod<
 
   const functionType: FunctionType = isQuery ? "query" : "update"
 
-  // Generate query key
-  const queryKey = useMemo(() => {
-    if (customQueryKey) return customQueryKey
-    return reactor.generateQueryKey(
-      {
-        functionName,
-        args,
-      },
-      callConfig
-    )
-  }, [reactor, functionName, args, callConfig, customQueryKey])
+  // Latest callbacks, read at dispatch time: this keeps a rerendered closure
+  // from being ignored, and keeps callback identity out of the effect deps.
+  const onSuccessRef = useRef(onSuccess)
+  const onErrorRef = useRef(onError)
+  onSuccessRef.current = onSuccess
+  onErrorRef.current = onError
+
+  // Build the key for a given set of call arguments.
+  //
+  // A custom `queryKey` is appended to the canister/function prefix rather than
+  // replacing it, matching `useActorQuery`. Used verbatim it would carry no
+  // canister id, so the entry would be invisible to the canister-scoped
+  // invalidation `ClientManager.updateAgent` runs on identity change and would
+  // keep serving the previous principal's data after sign-in or sign-out.
+  const buildQueryKey = useCallback(
+    (keyArgs: ReactorArgs<Service, Method, Transform> | undefined): QueryKey =>
+      reactor.generateQueryKey(
+        { functionName, args: keyArgs, queryKey: customQueryKey },
+        callConfig
+      ),
+    [reactor, functionName, callConfig, customQueryKey]
+  )
+
+  const queryKey = useMemo(() => buildQueryKey(args), [buildQueryKey, args])
 
   // ============================================================================
   // Query Implementation
@@ -210,26 +223,51 @@ export function useActorMethod<
   >(
     {
       queryKey,
-      queryFn: async () => {
-        try {
-          const result = await reactor.callMethod({
-            functionName,
-            args,
-            callConfig,
-          })
-          onSuccess?.(result)
-          return result
-        } catch (error) {
-          onError?.(error as ReactorReturnErr<Service, Method, Transform>)
-          throw error
-        }
-      },
+      // Callbacks deliberately do NOT live here: a queryFn runs once per fetch
+      // attempt, so `onError` fired on every retry (four times with the default
+      // 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,
+        }),
       enabled: isQuery && enabled,
       ...queryOptions,
     },
     reactor.queryClient
   )
 
+  // Dispatch the query callbacks from the settled observer result, once per
+  // distinct outcome. TanStack v5 removed `onSuccess`/`onError` from useQuery
+  // for exactly this reason, so the settle timestamps are what identify a new
+  // result: they also advance for a cache hit on a fresh mount, which is the
+  // case that previously never notified at all.
+  const notifiedSuccessAt = useRef<number | undefined>(undefined)
+  const notifiedErrorAt = useRef<number | undefined>(undefined)
+
+  const { status, data, error, dataUpdatedAt, errorUpdatedAt } = queryResult
+
+  useEffect(() => {
+    if (!isQuery) return
+    if (status === "success" && dataUpdatedAt !== notifiedSuccessAt.current) {
+      notifiedSuccessAt.current = dataUpdatedAt
+      onSuccessRef.current?.(data)
+    }
+  }, [isQuery, status, data, dataUpdatedAt])
+
+  useEffect(() => {
+    if (!isQuery) return
+    if (status === "error" && errorUpdatedAt !== notifiedErrorAt.current) {
+      notifiedErrorAt.current = errorUpdatedAt
+      onErrorRef.current?.(
+        error as ReactorReturnErr<Service, Method, Transform>
+      )
+    }
+  }, [isQuery, status, error, errorUpdatedAt])
+
   // ============================================================================
   // Mutation Implementation
   // ============================================================================
@@ -250,7 +288,7 @@ export function useActorMethod<
         return result
       },
       onSuccess: (data) => {
-        onSuccess?.(data)
+        onSuccessRef.current?.(data)
         // Invalidate specified queries after successful mutation
         if (invalidateQueries && invalidateQueries.length > 0) {
           invalidateQueries.forEach((key) => {
@@ -259,7 +297,7 @@ export function useActorMethod<
         }
       },
       onError: (error) => {
-        onError?.(error)
+        onErrorRef.current?.(error)
       },
     },
     reactor.queryClient
@@ -276,9 +314,14 @@ export function useActorMethod<
       if (isQuery) {
         // For queries, refetch with new args if provided
         if (callArgs !== undefined) {
+          // Key on the args actually being called. Reusing the hook's
+          // mount-time key would store this result under the previous args'
+          // entry — poisoning it for every other reader — and let fetchQuery
+          // 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({
-              queryKey,
+              queryKey: buildQueryKey(callArgs),
               queryFn: () =>
                 reactor.callMethod({
                   functionName,
@@ -287,10 +330,17 @@ export function useActorMethod<
                 }),
               staleTime: 0,
             })
-            onSuccess?.(result)
+            // Dispatched here rather than by the observer effect: this result
+            // lands under the called args' key, which the mounted observer (bound
+            // to the hook's own args) does not watch. That separation is also why
+            // this can no longer double-fire the way it did when both wrote to
+            // the same key.
+            onSuccessRef.current?.(result)
             return result
           } catch (error) {
-            onError?.(error as ReactorReturnErr<Service, Method, Transform>)
+            onErrorRef.current?.(
+              error as ReactorReturnErr<Service, Method, Transform>
+            )
             return undefined
           }
         }
@@ -309,11 +359,9 @@ export function useActorMethod<
       reactor,
       functionName,
       callConfig,
-      queryKey,
+      buildQueryKey,
       queryResult,
       mutationResult,
-      onSuccess,
-      onError,
     ]
   )
 

package/src/hooks/useActorMutation.ts

@@ -35,7 +35,14 @@ export interface UseActorMutationParameters<
   reactor: Reactor<Service, Transform>
   functionName: Method
   callConfig?: CallConfig
-  invalidateQueries?: QueryKey[]
+  /**
+   * Queries to invalidate upon successful mutation.
+   *
+   * `undefined` entries are skipped, so the common
+   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
+   * is absent.
+   */
+  invalidateQueries?: (QueryKey | undefined)[]
   /**
    * Callback for canister-level business logic errors.
    * Called when the canister returns a Result { Err: E } variant.
@@ -126,10 +133,18 @@ export const useActorMutation = <
       >
     ) => {
       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.map((queryKey) =>
-            reactor.queryClient.invalidateQueries({ queryKey })
-          )
+          invalidateQueries
+            .filter((queryKey) => queryKey !== undefined)
+            .map((queryKey) =>
+              reactor.queryClient.invalidateQueries({ queryKey })
+            )
         )
       }
       await onSuccess?.(...params)

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -16,7 +16,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils"
+import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorSuspenseInfiniteQuery hook.
@@ -129,8 +129,30 @@ export const useActorSuspenseInfiniteQuery = <
   // 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, queryKey }, callConfig),
-    [queryKey, reactor, functionName, callConfig]
+    () =>
+      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,
+      functionName,
+      callConfig,
+      getArgs,
+      options.initialPageParam,
+    ]
   )
 
   // Memoize queryFn to prevent recreation on every render

package/src/index.ts

@@ -3,21 +3,21 @@
 export * from "@ic-reactor/core"
 
 // Re-export hooks
-export * from "./hooks"
+export * from "./hooks/index.js"
 
 // Validation utilities for React
-export * from "./validation"
+export * from "./validation.js"
 
 // React-specific exports
-export * from "./createActorHooks"
-export * from "./defineReactor"
+export * from "./createActorHooks.js"
+export * from "./defineReactor.js"
 
-export * from "./createQuery"
-export * from "./createSuspenseQuery"
-export * from "./createInfiniteQuery"
-export * from "./createSuspenseInfiniteQuery"
-export * from "./createMutation"
+export * from "./createQuery.js"
+export * from "./createSuspenseQuery.js"
+export * from "./createInfiniteQuery.js"
+export * from "./createSuspenseInfiniteQuery.js"
+export * from "./createMutation.js"
 
-export * from "./auth"
+export * from "./auth/index.js"
 
-export * from "./types"
+export * from "./types.js"

package/src/types.ts

@@ -356,8 +356,14 @@ export interface MutationConfig<
   functionName: Method
   /** Call configuration for the actor method */
   callConfig?: CallConfig
-  /** Queries to invalidate upon successful mutation */
-  invalidateQueries?: QueryKey[]
+  /**
+   * Queries to invalidate upon successful mutation.
+   *
+   * `undefined` entries are skipped, so the common
+   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
+   * is absent.
+   */
+  invalidateQueries?: (QueryKey | undefined)[]
   /**
    * Callback for canister-level business logic errors.
    * Called when the canister returns a Result { Err: E } variant.