@ic-reactor/react 3.12.5 → 3.13.0

package/src/createInfiniteQuery.ts

@@ -8,7 +8,7 @@
  * const postsQuery = createInfiniteQuery(reactor, {
  *   functionName: "get_posts",
  *   initialPageParam: 0,
- *   getArgs: (cursor) => [{ cursor, limit: 10 }],
+ *   getArgs: (cursor) => [{ cursor, limit: 10 }] as const,
  *   getNextPageParam: (lastPage) => lastPage.nextCursor,
  * })
  *
@@ -42,13 +42,24 @@ import {
   QueryFunctionContext,
   FetchInfiniteQueryOptions,
   InfiniteQueryObserverOptions,
+  SkipToken,
 } 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,
   normalizeQueryData,
+  pickFetchOptions,
+  queryCacheControls,
+  retryOption,
+  useMountQueryClient,
+  withQueryFactoryMethods,
 } from "./utils.js"
 
 type InfiniteQueryFactoryFn<
@@ -57,7 +68,7 @@ type InfiniteQueryFactoryFn<
   Transform extends TransformKey,
   TPageParam,
   Selected,
-> = {
+> = QueryFactoryMethods & {
   (
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ): InfiniteQueryResult<
@@ -91,7 +102,7 @@ export type InfiniteQueryError<
 // ============================================================================
 
 /**
- * Configuration for createActorInfiniteQuery.
+ * Configuration for createInfiniteQuery.
  * Extends InfiniteQueryObserverOptions to accept standard TanStack Query
  * infinite-query options at the create level (e.g. refetchInterval,
  * refetchOnMount, refetchOnWindowFocus, retry, gcTime, networkMode).
@@ -158,7 +169,56 @@ export interface InfiniteQueryConfig<
 }
 
 /**
- * Configuration for createActorInfiniteQueryFactory (without initialPageParam, getArgs determined at call time).
+ * Configuration for the non-suspense infinite query hook of
+ * `createActorHooks` and `defineReactor` (`useActorInfiniteQuery`): an
+ * {@link InfiniteQueryConfig} whose `getArgs` may also be TanStack Query's
+ * `skipToken`, for a list whose arguments are not known yet.
+ *
+ * A skipped list does not fetch. It has an entry of its own under its method
+ * and config `queryKey` (at the canister and agent `callConfig` names), which
+ * no call's key shares, so it shows no data until the arguments arrive. Once
+ * `getArgs` is a function, the list is keyed and fetched as usual. Its
+ * `refetch()` has nothing to run: TanStack Query answers it with a "Missing
+ * queryFn" error. `useActorSuspenseInfiniteQuery` does not take `skipToken`.
+ *
+ * @example
+ * ```typescript
+ * import { skipToken } from "@ic-reactor/react"
+ *
+ * const { data } = useActorInfiniteQuery({
+ *   functionName: "get_transactions",
+ *   getArgs: account
+ *     ? (start: bigint) => [{ account, start, length: 20n }]
+ *     : skipToken,
+ *   initialPageParam: 0n,
+ *   getNextPageParam: (lastPage) => lastPage.next[0],
+ * })
+ * ```
+ */
+export interface SkippableInfiniteQueryConfig<
+  Service = BaseActor,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  TPageParam = unknown,
+  Selected = InfiniteData<
+    InfiniteQueryPageData<Service, Method, Transform>,
+    TPageParam
+  >,
+> extends Omit<
+  InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
+  "getArgs"
+> {
+  /**
+   * Function to get args from page parameter, or `skipToken` while the args
+   * are not known: the list then waits without fetching.
+   */
+  getArgs:
+    | ((pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>)
+    | SkipToken
+}
+
+/**
+ * Configuration for createInfiniteQueryFactory (without getArgs; provided at call time).
  */
 export type InfiniteQueryFactoryConfig<
   Service = BaseActor,
@@ -230,7 +290,11 @@ export interface UseInfiniteQueryWithSelect<
 // ============================================================================
 
 /**
- * Result from createActorInfiniteQuery
+ * Result from createInfiniteQuery
+ *
+ * `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
@@ -242,7 +306,7 @@ export interface InfiniteQueryResult<
   TPageParam,
   Selected = InfiniteData<TPageData, TPageParam>,
   TError = Error,
-> {
+> extends QueryCacheControls<InfiniteData<TPageData, TPageParam>> {
   /** Fetch first page in loader (uses ensureQueryData for cache-first) */
   fetch: () => Promise<Selected>
 
@@ -342,7 +406,7 @@ const createInfiniteQueryImpl = <
     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>
@@ -356,12 +420,20 @@ const createInfiniteQueryImpl = <
     TPageData,
     QueryKey,
     TPageParam
-  > => ({
-    queryKey: getQueryKey(),
-    queryFn,
-    initialPageParam,
-    getNextPageParam,
-  })
+  > => {
+    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,
+    }
+  }
 
   // Fetch function for loaders (cache-first, fetches first page)
   const fetch = async (): Promise<Selected> => {
@@ -373,9 +445,11 @@ const createInfiniteQueryImpl = <
       return select ? select(cachedData) : (cachedData as Selected)
     }
 
-    // Fetch if not in cache
-    const result = await reactor.queryClient.fetchInfiniteQuery(
-      getInfiniteQueryOptions()
+    // Fetch if not in cache. 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.fetchInfiniteQuery(getInfiniteQueryOptions())
     )
 
     // Result is already InfiniteData format
@@ -389,6 +463,8 @@ const createInfiniteQueryImpl = <
     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(
@@ -396,9 +472,11 @@ const createInfiniteQueryImpl = <
       [options?.select]
     )
 
+    const queryKey = getQueryKey()
+
     return useInfiniteQuery(
       {
-        queryKey: getQueryKey(),
+        queryKey,
         queryFn,
         initialPageParam,
         getNextPageParam,
@@ -408,6 +486,12 @@ const createInfiniteQueryImpl = <
         ...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)
+        ),
       } as any,
       reactor.queryClient
     )
@@ -449,6 +533,7 @@ const createInfiniteQueryImpl = <
     invalidate,
     getQueryKey,
     getCacheData,
+    ...queryCacheControls<TInfiniteData>(reactor, getQueryKey),
   }
 }
 
@@ -508,10 +593,10 @@ export function createInfiniteQuery<
  *
  * @param reactor - The Reactor instance
  * @param config - Infinite query configuration (without getArgs)
- * @returns A function that accepts getArgs and returns an ActorInfiniteQueryResult
+ * @returns A function that accepts getArgs and returns an InfiniteQueryResult
  *
  * @example
- * const getPostsQuery = createActorInfiniteQueryFactory(reactor, {
+ * const getPostsQuery = createInfiniteQueryFactory(reactor, {
  *   functionName: "get_posts",
  *   initialPageParam: 0,
  *   getKeyArgs: (args) => {
@@ -524,6 +609,9 @@ export function createInfiniteQuery<
  * // Create query with specific args builder
  * const userPostsQuery = getPostsQuery((cursor) => [{ userId, cursor, limit: 10 }])
  * const { data, fetchNextPage } = userPostsQuery.useInfiniteQuery()
+ *
+ * // Every list this factory made, whatever its args and pages
+ * await getPostsQuery.invalidate()
  */
 
 export function createInfiniteQueryFactory<
@@ -545,13 +633,7 @@ export function createInfiniteQueryFactory<
     Selected
   >
 ): InfiniteQueryFactoryFn<Service, Method, Transform, TPageParam, Selected> {
-  const factory: InfiniteQueryFactoryFn<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  > = (
+  const factory = (
     getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
   ) => {
     // `getKeyArgs` and the args-derived key segment are applied by the impl,
@@ -574,5 +656,15 @@ export function createInfiniteQueryFactory<
     })
   }
 
-  return factory
+  // What every instance's key starts with: the method, the `callConfig`
+  // segments and the config `queryKey`. The args segment comes after them.
+  return withQueryFactoryMethods(factory, reactor, () =>
+    reactor.generateQueryKey(
+      {
+        functionName: config.functionName as Method,
+        queryKey: config.queryKey,
+      },
+      config.callConfig
+    )
+  )
 }