@ic-reactor/react 3.12.4 → 3.13.0

package/src/createSuspenseInfiniteQuery.ts

@@ -13,7 +13,7 @@
  * const postsQuery = createSuspenseInfiniteQuery(reactor, {
  *   functionName: "get_posts",
  *   initialPageParam: 0,
- *   getArgs: (cursor) => [{ cursor, limit: 10 }],
+ *   getArgs: (cursor) => [{ cursor, limit: 10 }] as const,
  *   getNextPageParam: (lastPage) => lastPage.nextCursor,
  * })
  *
@@ -46,11 +46,22 @@ import {
   InfiniteQueryObserverOptions,
 } from "@tanstack/react-query"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { NoInfer } from "./types.js"
+import type {
+  NoInfer,
+  QueryCacheControls,
+  QueryFactoryMethods,
+} from "./types.js"
 import {
   buildChainedSelect,
+  callConfigForKey,
   mergeFactoryQueryKey,
+  mountWhileSuspended,
   normalizeQueryData,
+  pickFetchOptions,
+  queryCacheControls,
+  retryOption,
+  useMountQueryClient,
+  withQueryFactoryMethods,
 } from "./utils.js"
 
 type SuspenseInfiniteFactoryCallOptions = {
@@ -63,7 +74,7 @@ type SuspenseInfiniteQueryFactoryFn<
   Transform extends TransformKey,
   TPageParam,
   Selected,
-> = {
+> = QueryFactoryMethods & {
   (
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ): SuspenseInfiniteQueryResult<
@@ -106,7 +117,7 @@ export type SuspenseInfiniteQueryError<
 // ============================================================================
 
 /**
- * Configuration for createActorSuspenseInfiniteQuery.
+ * Configuration for createSuspenseInfiniteQuery.
  * Extends InfiniteQueryObserverOptions to accept all React Query options at the create level.
  *
  * @template Service - The actor interface type
@@ -154,7 +165,7 @@ export interface SuspenseInfiniteQueryConfig<
 }
 
 /**
- * Configuration for createActorSuspenseInfiniteQueryFactory (without getArgs; provided at call time).
+ * Configuration for createSuspenseInfiniteQueryFactory (without getArgs; provided at call time).
  */
 export type SuspenseInfiniteQueryFactoryConfig<
   Service = BaseActor,
@@ -231,7 +242,11 @@ export interface UseSuspenseInfiniteQueryWithSelect<
 // ============================================================================
 
 /**
- * Result from createActorSuspenseInfiniteQuery
+ * Result from createSuspenseInfiniteQuery
+ *
+ * `cancel()`, `reset()` and `optimisticUpdate()` act on the whole page set:
+ * `optimisticUpdate` gets and returns the raw `InfiniteData`, `{ pages,
+ * pageParams }`.
  *
  * @template TPageData - The raw page data type
  * @template TPageParam - The page parameter type
@@ -243,7 +258,7 @@ export interface SuspenseInfiniteQueryResult<
   TPageParam,
   Selected = InfiniteData<TPageData, TPageParam>,
   TError = Error,
-> {
+> extends QueryCacheControls<InfiniteData<TPageData, TPageParam>> {
   /** Fetch first page in loader (uses ensureInfiniteQueryData for cache-first) */
   fetch: () => Promise<Selected>
 
@@ -345,7 +360,7 @@ const createSuspenseInfiniteQueryImpl = <
     const result = await reactor.callMethod({
       functionName,
       args,
-      callConfig,
+      callConfig: callConfigForKey(context.queryKey, callConfig),
     })
     return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
       result as ReactorReturnOk<Service, Method, Transform>
@@ -359,19 +374,30 @@ const createSuspenseInfiniteQueryImpl = <
     TPageData,
     QueryKey,
     TPageParam
-  > => ({
-    queryKey: getQueryKey(),
-    queryFn,
-    initialPageParam,
-    getNextPageParam,
-    staleTime,
-  })
+  > => {
+    const queryKey = getQueryKey()
+    return {
+      // How the query function runs, shared with the hook; see
+      // pickFetchOptions. An update method's `retry` defaults as
+      // `Reactor.getQueryRetry` says.
+      ...pickFetchOptions(rest),
+      ...retryOption(rest.retry, reactor.getQueryRetry(functionName, queryKey)),
+      queryKey,
+      queryFn,
+      initialPageParam,
+      getNextPageParam,
+      staleTime,
+    }
+  }
 
   // Fetch function for loaders (cache-first, fetches first page)
   const fetch = async (): Promise<Selected> => {
-    // Use ensureInfiniteQueryData to get cached data or fetch if stale
-    const result = await reactor.queryClient.ensureInfiniteQueryData(
-      getInfiniteQueryOptions()
+    // Use ensureInfiniteQueryData to get cached data or fetch if stale. A
+    // sign-in or sign-out while it is in flight cancels it; it then runs again
+    // for the new identity rather than rejecting with TanStack's
+    // CancelledError, as `reactor.fetchQuery` does.
+    const result = await reactor.clientManager.fetchAcrossIdentitySwitch(() =>
+      reactor.queryClient.ensureInfiniteQueryData(getInfiniteQueryOptions())
     )
 
     // Result is already InfiniteData format
@@ -385,6 +411,8 @@ const createSuspenseInfiniteQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
+    useMountQueryClient(reactor.queryClient)
+
     // Memoized and identity-preserving; see buildChainedSelect for why the
     // function identity matters to the observer's select-result cache.
     const chainedSelect = useMemo(
@@ -392,21 +420,34 @@ const createSuspenseInfiniteQueryImpl = <
       [options?.select]
     )
 
-    return useSuspenseInfiniteQuery(
-      {
-        queryKey: getQueryKey(),
-        queryFn,
-        initialPageParam,
-        getNextPageParam,
-        getPreviousPageParam,
-        maxPages,
-        staleTime,
-        ...rest,
-        ...options,
-        select: chainedSelect,
-      },
-      reactor.queryClient
-    )
+    const queryKey = getQueryKey()
+
+    try {
+      return useSuspenseInfiniteQuery(
+        {
+          queryKey,
+          queryFn,
+          initialPageParam,
+          getNextPageParam,
+          getPreviousPageParam,
+          maxPages,
+          staleTime,
+          ...rest,
+          ...options,
+          select: chainedSelect,
+          // The hook's `retry`, else the config's, else an update method's
+          // default; see `Reactor.getQueryRetry`.
+          ...retryOption(
+            options?.retry ?? rest.retry,
+            reactor.getQueryRetry(functionName, queryKey)
+          ),
+        },
+        reactor.queryClient
+      )
+    } catch (thrown) {
+      mountWhileSuspended(reactor.queryClient, thrown)
+      throw thrown
+    }
   }
 
   // Invalidate function
@@ -445,6 +486,7 @@ const createSuspenseInfiniteQueryImpl = <
     invalidate,
     getQueryKey,
     getCacheData,
+    ...queryCacheControls<TInfiniteData>(reactor, getQueryKey),
   }
 }
 
@@ -504,10 +546,10 @@ export function createSuspenseInfiniteQuery<
  *
  * @param reactor - The Reactor instance
  * @param config - Suspense infinite query configuration (without getArgs)
- * @returns A function that accepts getArgs and returns an SuspenseActorInfiniteQueryResult
+ * @returns A function that accepts getArgs and returns a SuspenseInfiniteQueryResult
  *
  * @example
- * const getPostsQuery = createActorSuspenseInfiniteQueryFactory(reactor, {
+ * const getPostsQuery = createSuspenseInfiniteQueryFactory(reactor, {
  *   functionName: "get_posts",
  *   initialPageParam: 0,
  *   getKeyArgs: (args) => {
@@ -526,6 +568,9 @@ export function createSuspenseInfiniteQuery<
  *   (cursor) => [{ userId, cursor, limit: 10 }],
  *   { queryKey: ["v2"] }
  * )
+ *
+ * // Every list this factory made, whatever its args and pages
+ * await getPostsQuery.invalidate()
  */
 
 export function createSuspenseInfiniteQueryFactory<
@@ -553,13 +598,7 @@ export function createSuspenseInfiniteQueryFactory<
   TPageParam,
   Selected
 > {
-  const factory: SuspenseInfiniteQueryFactoryFn<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  > = (
+  const factory = (
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>,
     options?: SuspenseInfiniteFactoryCallOptions
   ) => {
@@ -597,5 +636,16 @@ export function createSuspenseInfiniteQueryFactory<
     >)
   }
 
-  return factory
+  // What every instance's key starts with: the method, the `callConfig`
+  // segments and the config `queryKey`. A per-call `queryKey` and the args
+  // segment come after them.
+  return withQueryFactoryMethods(factory, reactor, () =>
+    reactor.generateQueryKey(
+      {
+        functionName: config.functionName as Method,
+        queryKey: config.queryKey,
+      },
+      config.callConfig
+    )
+  )
 }

package/src/createSuspenseQuery.ts

@@ -34,9 +34,19 @@ import type {
   UseSuspenseQueryWithSelect,
   SuspenseQueryResult,
   SuspenseQueryFactoryConfig,
+  QueryFactoryFn,
   NoInfer,
 } from "./types.js"
-import { buildChainedSelect, createBoundedCache } from "./utils.js"
+import {
+  buildChainedSelect,
+  createBoundedCache,
+  mountWhileSuspended,
+  pickFetchOptions,
+  queryCacheControls,
+  retryOption,
+  useMountQueryClient,
+  withQueryFactoryMethods,
+} from "./utils.js"
 
 // ============================================================================
 // Internal Implementation
@@ -61,33 +71,51 @@ const createSuspenseQueryImpl = <
   const {
     functionName,
     args,
+    callConfig,
     staleTime = 5 * 60 * 1000,
     select,
     queryKey: customQueryKey,
     ...rest
   } = config
 
-  const params = { functionName, args, queryKey: customQueryKey }
+  // `callConfig` goes wherever the hooks send it: to the call and into the
+  // key, so a query of another canister or agent has an entry of its own.
+  const params = { functionName, args, queryKey: customQueryKey, callConfig }
 
-  const getQueryKey = () => reactor.generateQueryKey(params)
+  const getQueryKey = () => reactor.generateQueryKey(params, callConfig)
 
   const applySelect = (raw: TData): Selected =>
     select ? select(raw) : (raw as unknown as Selected)
 
+  // How the query function runs, shared with the hook; see pickFetchOptions.
+  const fetchOptions = pickFetchOptions(rest)
+
   /** Cache-first fetch for use in loaders / route preloading. */
   const fetch = async (): Promise<Selected> => {
-    const result = await reactor.fetchQuery(params)
+    // Through the reactor rather than straight to the QueryClient: overriding
+    // `fetchQuery` in a Reactor subclass is a documented way to add logic to
+    // every factory fetch.
+    const result = await reactor.fetchQuery(params, fetchOptions)
     return applySelect(result)
   }
 
   /** Fire-and-forget prefetch — warms the cache without blocking. */
   const prefetch = (): Promise<void> => {
     const baseOptions = reactor.getQueryOptions(params)
-    return reactor.queryClient.prefetchQuery({
-      queryKey: baseOptions.queryKey,
-      queryFn: baseOptions.queryFn,
-      staleTime,
-    })
+    // Runs again when a sign-in or sign-out cancels it, and never rejects;
+    // see `prefetch` in createQuery.
+    return reactor.clientManager
+      .fetchAcrossIdentitySwitch(() =>
+        reactor.queryClient.prefetchQuery({
+          ...fetchOptions,
+          // An update method's default `retry`; see `Reactor.getQueryRetry`.
+          ...retryOption(fetchOptions.retry, baseOptions.retry),
+          queryKey: baseOptions.queryKey,
+          queryFn: baseOptions.queryFn,
+          staleTime,
+        })
+      )
+      .catch(() => undefined)
   }
 
   const useSuspenseQueryHook: UseSuspenseQueryWithSelect<
@@ -95,6 +123,7 @@ const createSuspenseQueryImpl = <
     Selected,
     TError
   > = (options: any): any => {
+    useMountQueryClient(reactor.queryClient)
     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.
@@ -102,17 +131,25 @@ const createSuspenseQueryImpl = <
       () => buildChainedSelect(select, options?.select),
       [options?.select]
     )
-    return useSuspenseQuery(
-      {
-        queryKey: baseOptions.queryKey,
-        staleTime,
-        ...rest,
-        ...options,
-        queryFn: baseOptions.queryFn,
-        select: chainedSelect,
-      },
-      reactor.queryClient
-    )
+    try {
+      return useSuspenseQuery(
+        {
+          queryKey: baseOptions.queryKey,
+          staleTime,
+          ...rest,
+          ...options,
+          queryFn: baseOptions.queryFn,
+          select: chainedSelect,
+          // The hook's `retry`, else the config's, else an update method's
+          // default; see `Reactor.getQueryRetry`.
+          ...retryOption(options?.retry ?? rest.retry, baseOptions.retry),
+        },
+        reactor.queryClient
+      )
+    } catch (thrown) {
+      mountWhileSuspended(reactor.queryClient, thrown)
+      throw thrown
+    }
   }
 
   const invalidate = async (): Promise<void> => {
@@ -124,7 +161,7 @@ const createSuspenseQueryImpl = <
     Selected,
     TError
   >["getCacheData"] = (selectFn?: (data: Selected) => unknown): any => {
-    const raw = reactor.getQueryData(params)
+    const raw = reactor.getQueryData(params, callConfig)
     if (raw === undefined) return undefined
     const selected = applySelect(raw)
     return selectFn ? selectFn(selected) : selected
@@ -145,6 +182,7 @@ const createSuspenseQueryImpl = <
     getQueryKey,
     getCacheData,
     setData,
+    ...queryCacheControls<TData>(reactor, getQueryKey),
   }
 }
 
@@ -175,6 +213,27 @@ export function createSuspenseQuery<
 // Convenience: Create suspense query with dynamic args
 // ============================================================================
 
+/**
+ * Create a suspense query factory: a function that takes the method's args
+ * and returns the suspense query object for them, the same object for the
+ * same args.
+ *
+ * The function also has `getQueryKey()`, the key prefix every query it
+ * returns shares, and `invalidate()`, which invalidates all of them whatever
+ * their args. Pass the function itself to a mutation's `invalidateQueries` to
+ * refresh every instance after the mutation.
+ *
+ * @example
+ * const getBalance = createSuspenseQueryFactory(ledger, {
+ *   functionName: "icrc1_balance_of",
+ * })
+ *
+ * // In a component under <Suspense>
+ * const { data } = getBalance([{ owner, subaccount: [] }]).useSuspenseQuery()
+ *
+ * // Refetch every account's balance
+ * await getBalance.invalidate()
+ */
 export function createSuspenseQueryFactory<
   Service,
   Transform extends TransformKey,
@@ -188,12 +247,13 @@ export function createSuspenseQueryFactory<
     Transform,
     Selected
   >
-): (
-  args: ReactorArgs<Service, Method, Transform>
-) => SuspenseQueryResult<
-  QueryFnData<Service, Method, Transform>,
-  Selected,
-  QueryError<Service, Method, Transform>
+): QueryFactoryFn<
+  ReactorArgs<Service, Method, Transform>,
+  SuspenseQueryResult<
+    QueryFnData<Service, Method, Transform>,
+    Selected,
+    QueryError<Service, Method, Transform>
+  >
 > {
   const cache =
     createBoundedCache<
@@ -204,11 +264,11 @@ export function createSuspenseQueryFactory<
       >
     >()
 
-  return (args: ReactorArgs<Service, Method, Transform>) => {
-    const key = reactor.generateQueryKey({
-      functionName: config.functionName as Method,
-      args,
-    })
+  const factory = (args: ReactorArgs<Service, Method, Transform>) => {
+    const key = reactor.generateQueryKey(
+      { functionName: config.functionName as Method, args },
+      config.callConfig
+    )
     const cacheKey = JSON.stringify(key)
 
     const existing = cache.get(cacheKey)
@@ -231,4 +291,14 @@ export function createSuspenseQueryFactory<
     cache.set(cacheKey, result)
     return result
   }
+
+  // The method's own prefix, at the canister and agent the config's
+  // `callConfig` names. A config `queryKey` follows the args segment in every
+  // instance's key, so it cannot narrow the prefix.
+  return withQueryFactoryMethods(factory, reactor, () =>
+    reactor.generateQueryKey(
+      { functionName: config.functionName as Method },
+      config.callConfig
+    )
+  )
 }

package/src/defineDisplayReactor.ts

@@ -0,0 +1,62 @@
+import { DisplayReactor } from "@ic-reactor/core"
+import type { BaseActor, DisplayReactorParameters } from "@ic-reactor/core"
+import { defineReactorWith } from "./defineReactorShared.js"
+import type {
+  DefineReactorSharedParameters,
+  DefineReactorResult,
+} from "./defineReactorShared.js"
+
+/** Options for {@link defineDisplayReactor}: `defineReactor`'s, plus validators. */
+export interface DefineDisplayReactorOptions<
+  Service,
+> extends DefineReactorSharedParameters {
+  /** Optional initial argument validators (receive display types). */
+  validators?: DisplayReactorParameters<Service>["validators"]
+}
+
+/**
+ * One-call bootstrap for a {@link DisplayReactor} and its React hooks: the
+ * display counterpart of `defineReactor`, taking the same options.
+ *
+ * A DisplayReactor takes and returns UI-friendly values — text for
+ * `Principal`, `nat`, `int` and 64-bit integers, hex for blobs — which suits
+ * forms and components. Its codecs are built on zod, so this adds zod to the
+ * bundle. `defineReactor`, which builds a plain `Reactor` with raw Candid
+ * values, does not need zod, but until its deprecated `display` flag is removed
+ * at the next major it bundles zod anyway; `createActorHooks(new Reactor(...))`
+ * is the setup without it.
+ *
+ * Replaces `defineReactor({ display: true })`, which is deprecated.
+ *
+ * @example
+ * ```typescript
+ * import { defineDisplayReactor } from "@ic-reactor/react"
+ * import { idlFactory, type _SERVICE } from "./declarations/backend"
+ *
+ * export const { reactor, useActorQuery, useActorMutation, useAuth } =
+ *   defineDisplayReactor<_SERVICE>({
+ *     name: "backend",
+ *     idlFactory,
+ *     canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+ *   })
+ *
+ * function Balance() {
+ *   // `nat` arrives as text, ready to render.
+ *   const { data } = useActorQuery({ functionName: "get_balance" })
+ *   return <span>{data}</span>
+ * }
+ * ```
+ */
+export function defineDisplayReactor<Service = BaseActor>(
+  params: DefineDisplayReactorOptions<Service>
+): DefineReactorResult<Service, "display", DisplayReactor<Service>> {
+  return defineReactorWith<Service, "display", DisplayReactor<Service>>(
+    "defineDisplayReactor",
+    params,
+    (config) =>
+      new DisplayReactor<Service>({
+        ...config,
+        validators: params.validators,
+      })
+  )
+}