@ic-reactor/react 3.8.0 → 3.10.0

package/src/createMutation.ts

@@ -76,6 +76,8 @@ const createMutationImpl = <
     onSuccess: factoryOnSuccess,
     onCanisterError: factoryOnCanisterError,
     onError: factoryOnError,
+    onMutate: factoryOnMutate,
+    onSettled: factoryOnSettled,
     ...factoryOptions
   } = config
 
@@ -91,16 +93,46 @@ const createMutationImpl = <
 
   /**
    * Imperative execution for non-React usage.
-   * Calls the canister method and invalidates factory-level queries.
+   *
+   * Runs the same factory-level chain the hook does — invalidation, then
+   * `onSuccess`, or `onCanisterError`/`onError` on failure — so a mutation
+   * object behaves the same through both call paths. Only hook-level callbacks
+   * are absent, because there is no hook here to supply them.
+   *
+   * The error is rethrown after the callbacks run, so `await execute(...)`
+   * still rejects for the caller.
+   *
    * Use this in route loaders, scripts, or server-side code.
    */
   const execute = async (
     args: ReactorArgs<Service, Method, Transform>
   ): Promise<ReactorReturnOk<Service, Method, Transform>> => {
-    const result = await callFn(args)
+    let result: ReactorReturnOk<Service, Method, Transform>
+    try {
+      result = await callFn(args)
+    } catch (error) {
+      if (isCanisterError(error)) {
+        factoryOnCanisterError?.(error, args)
+      }
+      // No mutation context or instance exists on the imperative path.
+      factoryOnError?.(
+        error as Parameters<NonNullable<typeof factoryOnError>>[0],
+        args,
+        undefined as never,
+        undefined as never
+      )
+      throw error
+    }
+
     if (factoryInvalidateQueries) {
       await invalidateAll(reactor.queryClient, factoryInvalidateQueries)
     }
+    await factoryOnSuccess?.(
+      result,
+      args,
+      undefined as never,
+      undefined as never
+    )
     return result
   }
 
@@ -145,6 +177,20 @@ const createMutationImpl = <
           factoryOnError?.(error, variables, context, mutation)
           restOptions.onError?.(error, variables, context, mutation)
         },
+        // `onMutate` and `onSettled` are composed like `onSuccess`/`onError`
+        // above. They used to arrive through the `...restOptions` spread, so a
+        // hook-level one silently replaced the factory's — factory teardown,
+        // 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)
+        },
+        onSettled: async (...params) => {
+          await factoryOnSettled?.(...params)
+          await restOptions.onSettled?.(...params)
+        },
       },
       reactor.queryClient
     )

package/src/createQuery.ts

@@ -30,6 +30,7 @@ import type {
   ReactorArgs,
   TransformKey,
 } from "@ic-reactor/core"
+import { useMemo } from "react"
 import {
   QueryKey,
   useQuery,
@@ -45,7 +46,7 @@ import type {
   QueryFactoryConfig,
   NoInfer,
 } from "./types.js"
-import { buildChainedSelect } from "./utils.js"
+import { buildChainedSelect, createBoundedCache } from "./utils.js"
 
 // ============================================================================
 // Internal Implementation
@@ -110,6 +111,12 @@ const createQueryImpl = <
 
   const useQueryHook = ((options?: UseQueryHookOptions) => {
     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 useQuery(
       {
         queryKey: baseOptions.queryKey,
@@ -117,7 +124,7 @@ const createQueryImpl = <
         ...rest,
         ...options,
         queryFn: baseOptions.queryFn,
-        select: buildChainedSelect(select, options?.select),
+        select: chainedSelect,
       },
       reactor.queryClient
     )
@@ -198,14 +205,14 @@ export function createQueryFactory<
   Selected,
   QueryError<Service, Method, Transform>
 > {
-  const cache = new Map<
-    string,
-    QueryResult<
-      QueryFnData<Service, Method, Transform>,
-      Selected,
-      QueryError<Service, Method, Transform>
-    >
-  >()
+  const cache =
+    createBoundedCache<
+      QueryResult<
+        QueryFnData<Service, Method, Transform>,
+        Selected,
+        QueryError<Service, Method, Transform>
+      >
+    >()
 
   return (args: ReactorArgs<Service, Method, Transform>) => {
     const key = reactor.generateQueryKey({

package/src/createSuspenseInfiniteQuery.ts

@@ -24,6 +24,7 @@
  * const allPosts = data.pages.flatMap(page => page.posts)
  */
 
+import { useMemo } from "react"
 import type {
   Reactor,
   FunctionName,
@@ -46,7 +47,11 @@ import {
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
 import { NoInfer } from "./types.js"
-import { mergeFactoryQueryKey, normalizeQueryData } from "./utils.js"
+import {
+  buildChainedSelect,
+  mergeFactoryQueryKey,
+  normalizeQueryData,
+} from "./utils.js"
 
 type SuspenseInfiniteFactoryCallOptions = {
   queryKey?: QueryKey
@@ -137,6 +142,15 @@ export interface SuspenseInfiniteQueryConfig<
   queryKey?: QueryKey
   /** Function to get args from page parameter */
   getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
+  /**
+   * 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.
+   */
+  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
 }
 
 /**
@@ -152,17 +166,11 @@ export type SuspenseInfiniteQueryFactoryConfig<
     TPageParam
   >,
 > = Omit<
+  // `getArgs` is supplied per factory call. `getKeyArgs` is inherited from
+  // SuspenseInfiniteQueryConfig, which now applies it for every infinite query.
   SuspenseInfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
   "getArgs"
-> & {
-  /**
-   * Optional key-args derivation for factory calls.
-   * Receives the resolved args from `getArgs(initialPageParam)` and should return
-   * a stable serializable representation of the logical query identity
-   * (typically excluding pagination/cursor fields).
-   */
-  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
-}
+>
 
 // ============================================================================
 // Hook Interface
@@ -301,6 +309,7 @@ const createSuspenseInfiniteQueryImpl = <
     queryKey: customQueryKey,
     initialPageParam,
     getArgs,
+    getKeyArgs,
     getNextPageParam,
     getPreviousPageParam,
     maxPages,
@@ -309,12 +318,18 @@ const createSuspenseInfiniteQueryImpl = <
     ...rest
   } = config
 
-  // Get query key from actor manager
+  // Fold the call arguments into the key — see the matching comment in
+  // createInfiniteQuery. Without them every infinite query on a method shares
+  // one cache entry, because the arguments live in a `getArgs` closure rather
+  // than in the config.
   const getQueryKey = (): QueryKey => {
+    const initialArgs = getArgs(initialPageParam)
+    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
+
     return reactor.generateQueryKey(
       {
         functionName,
-        queryKey: customQueryKey,
+        queryKey: mergeFactoryQueryKey(customQueryKey, undefined, keyArgs),
       },
       callConfig
     )
@@ -370,14 +385,12 @@ const createSuspenseInfiniteQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
-    // Chain the selects: raw -> config.select -> options.select
-    const chainedSelect = (rawData: TInfiniteData) => {
-      const firstPass = select ? select(rawData) : rawData
-      if (options?.select) {
-        return options.select(firstPass)
-      }
-      return firstPass
-    }
+    // Memoized and identity-preserving; see buildChainedSelect for why the
+    // function identity matters to the observer's select-result cache.
+    const chainedSelect = useMemo(
+      () => buildChainedSelect(select as never, options?.select),
+      [options?.select]
+    )
 
     return useSuspenseInfiniteQuery(
       {
@@ -550,12 +563,13 @@ export function createSuspenseInfiniteQueryFactory<
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>,
     options?: SuspenseInfiniteFactoryCallOptions
   ) => {
-    const initialArgs = getArgs(config.initialPageParam)
-    const keyArgs = config.getKeyArgs?.(initialArgs) ?? initialArgs
+    // Only the caller-supplied segments are merged here; the args-derived
+    // segment is added by the impl, which does it for every infinite query.
+    // Applying it in both places would append the args twice.
     const queryKey = mergeFactoryQueryKey(
       config.queryKey,
       options?.queryKey,
-      keyArgs
+      undefined
     )
 
     return createSuspenseInfiniteQueryImpl<
@@ -565,15 +579,13 @@ export function createSuspenseInfiniteQueryFactory<
       TPageParam,
       Selected
     >(reactor, {
-      ...(({ getKeyArgs: _getKeyArgs, ...rest }) => rest)(
-        config as SuspenseInfiniteQueryFactoryConfig<
-          Service,
-          Method,
-          Transform,
-          TPageParam,
-          Selected
-        >
-      ),
+      ...(config as SuspenseInfiniteQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        TPageParam,
+        Selected
+      >),
       queryKey,
       getArgs,
     } as SuspenseInfiniteQueryConfig<

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,
@@ -35,7 +36,7 @@ import type {
   SuspenseQueryFactoryConfig,
   NoInfer,
 } from "./types.js"
-import { buildChainedSelect } from "./utils.js"
+import { buildChainedSelect, createBoundedCache } 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
     )
@@ -188,14 +195,14 @@ export function createSuspenseQueryFactory<
   Selected,
   QueryError<Service, Method, Transform>
 > {
-  const cache = new Map<
-    string,
-    SuspenseQueryResult<
-      QueryFnData<Service, Method, Transform>,
-      Selected,
-      QueryError<Service, Method, Transform>
-    >
-  >()
+  const cache =
+    createBoundedCache<
+      SuspenseQueryResult<
+        QueryFnData<Service, Method, Transform>,
+        Selected,
+        QueryError<Service, Method, Transform>
+      >
+    >()
 
   return (args: ReactorArgs<Service, Method, Transform>) => {
     const key = reactor.generateQueryKey({

package/src/defineReactor.ts

@@ -54,7 +54,12 @@
  * }
  * ```
  */
-import { ClientManager, Reactor, DisplayReactor } from "@ic-reactor/core"
+import {
+  ClientManager,
+  Reactor,
+  DisplayReactor,
+  reactorRetry,
+} from "@ic-reactor/core"
 import type {
   BaseActor,
   TransformKey,
@@ -142,6 +147,23 @@ export type DefineReactorResult<
     useIdentityAttributes: () => UseIdentityAttributesReturn
   }
 
+/**
+ * The QueryClient this module creates when the caller does not supply one.
+ *
+ * React Query retries every failure three times by default, which for canister
+ * calls means four attempts and several seconds of backoff on outcomes that
+ * cannot change — a canister `Err`, a validation failure, a Candid encode
+ * error that never reached the network. `reactorRetry` keeps the same three
+ * attempts for transport failures and stops immediately on the rest.
+ *
+ * A caller-supplied `queryClient` is left exactly as given; opt in there with
+ * `defaultOptions: { queries: { retry: reactorRetry } }`.
+ */
+const createDefaultQueryClient = () =>
+  new QueryClient({
+    defaultOptions: { queries: { retry: reactorRetry } },
+  })
+
 export function defineReactor<Service = BaseActor>(
   params: DefineDisplayReactorParameters<Service>
 ): DefineReactorResult<Service, "display", DisplayReactor<Service>>
@@ -197,7 +219,7 @@ export function defineReactor<Service = BaseActor>(
     providedClientManager ??
     providedAuthentication?.clientManager ??
     new ClientManager({
-      queryClient: providedQueryClient ?? new QueryClient(),
+      queryClient: providedQueryClient ?? createDefaultQueryClient(),
       agentOptions,
     })
 

package/src/hooks/createAuthHooks.ts

@@ -39,6 +39,24 @@ export interface CreateAuthHooksReturn {
 export const createAuthHooks = (
   authentication: AuthenticationManager
 ): CreateAuthHooksReturn => {
+  // Passing a ClientManager here is the natural mistake — it is what
+  // `AuthenticationManager` is built from, and the two are adjacent in every
+  // setup snippet. TypeScript rejects it, but a JS caller got no error until
+  // render, where it surfaced as "Cannot destructure property 'isAuthenticated'
+  // of 'useAuthState(...)' as it is undefined" — which names neither the cause
+  // nor this function.
+  if (
+    !authentication ||
+    typeof authentication.subscribeAuthState !== "function"
+  ) {
+    throw new TypeError(
+      "[ic-reactor] createAuthHooks() expects an AuthenticationManager, not a " +
+        "ClientManager. Build one first: " +
+        "`new AuthenticationManager({ clientManager })`, or take it from " +
+        "`defineReactor(...).authentication`."
+    )
+  }
+
   const { clientManager } = authentication
   /**
    * Subscribe to agent state changes.

package/src/hooks/index.ts

@@ -1,5 +1,11 @@
 // ============================================================================
 // Hooks
+//
+// These are the RAW hooks: they take the reactor as a property. They are
+// therefore exported as `useReactor*` only — the `useActor*` names belong to
+// the bound hooks `createActorHooks` returns, which take no reactor. Aliasing
+// the raw implementations under the bound names would hand a caller following
+// the documented `useActorQuery({ functionName })` shape an undefined reactor.
 // ============================================================================
 
 // useActorQuery / useReactorQuery

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.js"
+import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
 
 /**
  * Parameters for useActorInfiniteQuery hook.
@@ -119,8 +119,35 @@ 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,
+      // `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,
+    ]
   )
 
   // 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,39 @@ 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
+      ),
+    // `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.
+    [
+      reactor,
+      reactor.canisterId?.toString(),
+      functionName,
+      callConfig,
+      customQueryKey,
+    ]
+  )
+
+  const queryKey = useMemo(() => buildQueryKey(args), [buildQueryKey, args])
 
   // ============================================================================
   // Query Implementation
@@ -210,26 +232,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 +297,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 +306,7 @@ export function useActorMethod<
         }
       },
       onError: (error) => {
-        onError?.(error)
+        onErrorRef.current?.(error)
       },
     },
     reactor.queryClient
@@ -276,9 +323,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 +339,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 +368,9 @@ export function useActorMethod<
       reactor,
       functionName,
       callConfig,
-      queryKey,
+      buildQueryKey,
       queryResult,
       mutationResult,
-      onSuccess,
-      onError,
     ]
   )