@ic-reactor/react 3.13.0 → 4.0.0-beta.1

package/src/createInfiniteQuery.ts

@@ -1,670 +0,0 @@
-/**
- * Infinite Query Factory - Generic wrapper for React Query paginated canister data
- *
- * Creates unified fetch/hook/invalidate functions for any paginated canister method.
- * Works with any Reactor instance.
- *
- * @example
- * const postsQuery = createInfiniteQuery(reactor, {
- *   functionName: "get_posts",
- *   initialPageParam: 0,
- *   getArgs: (cursor) => [{ cursor, limit: 10 }] as const,
- *   getNextPageParam: (lastPage) => lastPage.nextCursor,
- * })
- *
- * // In component
- * const { data, fetchNextPage, hasNextPage } = postsQuery.useInfiniteQuery()
- *
- * // Flatten all pages
- * const allPosts = data?.pages.flatMap(page => page.posts)
- *
- * // Invalidate cache
- * postsQuery.invalidate()
- */
-
-import { useMemo } from "react"
-import type {
-  Reactor,
-  FunctionName,
-  ReactorArgs,
-  BaseActor,
-  TransformKey,
-  ReactorReturnOk,
-  ReactorQueryData,
-  ReactorReturnErr,
-} from "@ic-reactor/core"
-import {
-  QueryKey,
-  useInfiniteQuery,
-  InfiniteData,
-  UseInfiniteQueryResult,
-  UseInfiniteQueryOptions,
-  QueryFunctionContext,
-  FetchInfiniteQueryOptions,
-  InfiniteQueryObserverOptions,
-  SkipToken,
-} from "@tanstack/react-query"
-import { CallConfig } from "@icp-sdk/core/agent"
-import type {
-  NoInfer,
-  QueryCacheControls,
-  QueryFactoryMethods,
-} from "./types.js"
-import {
-  buildChainedSelect,
-  callConfigForKey,
-  mergeFactoryQueryKey,
-  normalizeQueryData,
-  pickFetchOptions,
-  queryCacheControls,
-  retryOption,
-  useMountQueryClient,
-  withQueryFactoryMethods,
-} from "./utils.js"
-
-type InfiniteQueryFactoryFn<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey,
-  TPageParam,
-  Selected,
-> = QueryFactoryMethods & {
-  (
-    getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
-  ): InfiniteQueryResult<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam,
-    Selected,
-    InfiniteQueryError<Service, Method, Transform>
-  >
-}
-
-// ============================================================================
-// Type Definitions
-// ============================================================================
-
-/** The raw page data type returned by the query function */
-export type InfiniteQueryPageData<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
-
-/** The error type for infinite queries */
-export type InfiniteQueryError<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> = ReactorReturnErr<Service, Method, Transform>
-
-// ============================================================================
-// Configuration Types
-// ============================================================================
-
-/**
- * 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).
- *
- * @template Service - The actor interface type
- * @template Method - The method name on the actor
- * @template Transform - The transformation key (identity, display, etc.)
- * @template TPageParam - The type of the page parameter
- * @template Selected - The type returned after select transformation
- */
-export interface InfiniteQueryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam
-  >,
-> extends Omit<
-  InfiniteQueryObserverOptions<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    InfiniteQueryError<Service, Method, Transform>,
-    Selected,
-    QueryKey,
-    TPageParam
-  >,
-  "queryKey" | "queryFn"
-> {
-  /** The method to call on the canister */
-  functionName: Method
-  /** Call configuration for the actor method */
-  callConfig?: CallConfig
-  /** Custom query key (optional, auto-generated if not provided) */
-  queryKey?: QueryKey
-  /** Initial page parameter */
-  initialPageParam: TPageParam
-  /** 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 — return the stable, serializable
-   * portion (typically everything except the pagination field).
-   */
-  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
-  /** Function to determine next page parameter */
-  getNextPageParam: (
-    lastPage: InfiniteQueryPageData<Service, Method, Transform>,
-    allPages: InfiniteQueryPageData<Service, Method, Transform>[],
-    lastPageParam: TPageParam,
-    allPageParams: TPageParam[]
-  ) => TPageParam | undefined | null
-  /** Function to determine previous page parameter (for bi-directional) */
-  getPreviousPageParam?: (
-    firstPage: InfiniteQueryPageData<Service, Method, Transform>,
-    allPages: InfiniteQueryPageData<Service, Method, Transform>[],
-    firstPageParam: TPageParam,
-    allPageParams: TPageParam[]
-  ) => TPageParam | undefined | null
-}
-
-/**
- * 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,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam
-  >,
-> = Omit<
-  // `getArgs` is supplied per factory call. `getKeyArgs` is inherited from
-  // InfiniteQueryConfig, which now applies it for every infinite query rather
-  // than only for factory-created ones.
-  InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>,
-  "getArgs"
->
-
-// ============================================================================
-// Hook Interface
-// ============================================================================
-
-/**
- * useInfiniteQuery hook with chained select support.
- */
-export interface UseInfiniteQueryWithSelect<
-  TPageData,
-  TPageParam,
-  Selected = InfiniteData<TPageData, TPageParam>,
-  TError = Error,
-> {
-  // Overload 1: Without select - returns Selected
-  (
-    options?: Omit<
-      UseInfiniteQueryOptions<
-        TPageData,
-        TError,
-        Selected,
-        QueryKey,
-        TPageParam
-      >,
-      | "select"
-      | "queryKey"
-      | "queryFn"
-      | "initialPageParam"
-      | "getNextPageParam"
-      | "getPreviousPageParam"
-    >
-  ): UseInfiniteQueryResult<Selected, TError>
-
-  // Overload 2: With select - chains on top and returns TFinal
-  <TFinal = Selected>(
-    options: Omit<
-      UseInfiniteQueryOptions<TPageData, TError, TFinal, QueryKey, TPageParam>,
-      | "queryKey"
-      | "queryFn"
-      | "select"
-      | "initialPageParam"
-      | "getNextPageParam"
-      | "getPreviousPageParam"
-    > & {
-      select: (data: Selected) => TFinal
-    }
-  ): UseInfiniteQueryResult<TFinal, TError>
-}
-
-// ============================================================================
-// Result Interface
-// ============================================================================
-
-/**
- * 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
- * @template Selected - The type after select transformation
- * @template TError - The error type
- */
-export interface InfiniteQueryResult<
-  TPageData,
-  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>
-
-  /** React hook for components - supports pagination */
-  useInfiniteQuery: UseInfiniteQueryWithSelect<
-    TPageData,
-    TPageParam,
-    Selected,
-    TError
-  >
-
-  /** Invalidate the cache (refetches if query is active) */
-  invalidate: () => Promise<void>
-
-  /** Get query key (for advanced React Query usage) */
-  getQueryKey: () => QueryKey
-
-  /**
-   * Read data directly from cache without fetching.
-   * Returns undefined if data is not in cache.
-   */
-  getCacheData: {
-    (): Selected | undefined
-    <TFinal>(select: (data: Selected) => TFinal): TFinal | undefined
-  }
-}
-
-// ============================================================================
-// Internal Implementation
-// ============================================================================
-
-const createInfiniteQueryImpl = <
-  Service,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam
-  >,
->(
-  reactor: Reactor<Service, Transform>,
-  config: InfiniteQueryConfig<Service, Method, Transform, TPageParam, Selected>
-): InfiniteQueryResult<
-  InfiniteQueryPageData<Service, Method, Transform>,
-  TPageParam,
-  Selected,
-  InfiniteQueryError<Service, Method, Transform>
-> => {
-  type TPageData = InfiniteQueryPageData<Service, Method, Transform>
-  type TError = InfiniteQueryError<Service, Method, Transform>
-  type TInfiniteData = InfiniteData<TPageData, TPageParam>
-
-  const {
-    functionName,
-    callConfig,
-    queryKey: customQueryKey,
-    initialPageParam,
-    getArgs,
-    getKeyArgs,
-    getNextPageParam,
-    getPreviousPageParam,
-    maxPages,
-    staleTime = 5 * 60 * 1000,
-    select,
-    ...rest
-  } = config
-
-  // Fold the call arguments into the key. Without them every infinite query on
-  // a method shares one cache entry, so two lists with different `getArgs` (a
-  // different page size, a different filter) serve each other's pages — the
-  // arguments live in a closure, not in the config, so nothing else
-  // distinguishes them.
-  //
-  // The first page's args stand for the query's identity; `getKeyArgs` lets a
-  // caller drop the cursor field when it is part of those args.
-  const getQueryKey = (): QueryKey => {
-    const initialArgs = getArgs(initialPageParam)
-    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
-
-    return reactor.generateQueryKey(
-      {
-        functionName,
-        queryKey: mergeFactoryQueryKey(customQueryKey, undefined, keyArgs),
-      },
-      callConfig
-    )
-  }
-
-  // Query function - accepts QueryFunctionContext
-  const queryFn = async (
-    context: QueryFunctionContext<QueryKey, TPageParam>
-  ): Promise<TPageData> => {
-    // pageParam is typed as unknown in QueryFunctionContext, but we know its type
-    const pageParam = context.pageParam as TPageParam
-    const args = getArgs(pageParam)
-    const result = await reactor.callMethod({
-      functionName,
-      args,
-      callConfig: callConfigForKey(context.queryKey, callConfig),
-    })
-    return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
-      result as ReactorReturnOk<Service, Method, Transform>
-    )
-  }
-
-  // Get infinite query options for fetchInfiniteQuery
-  const getInfiniteQueryOptions = (): FetchInfiniteQueryOptions<
-    TPageData,
-    TError,
-    TPageData,
-    QueryKey,
-    TPageParam
-  > => {
-    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> => {
-    // Check cache first
-    const cachedData = reactor.queryClient.getQueryData(getQueryKey()) as
-      TInfiniteData | undefined
-
-    if (cachedData !== undefined) {
-      return select ? select(cachedData) : (cachedData as Selected)
-    }
-
-    // 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
-    return select ? select(result) : (result as unknown as Selected)
-  }
-
-  // Implementation
-  const useInfiniteQueryHook: UseInfiniteQueryWithSelect<
-    TPageData,
-    TPageParam,
-    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(
-      () => buildChainedSelect(select as never, options?.select),
-      [options?.select]
-    )
-
-    const queryKey = getQueryKey()
-
-    return useInfiniteQuery(
-      {
-        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)
-        ),
-      } as any,
-      reactor.queryClient
-    )
-  }
-
-  // Invalidate function
-  const invalidate = async (): Promise<void> => {
-    const queryKey = getQueryKey()
-    await reactor.queryClient.invalidateQueries({ queryKey })
-  }
-
-  // Get data from cache without fetching
-  const getCacheData: any = (selectFn?: (data: Selected) => any) => {
-    const queryKey = getQueryKey()
-    const cachedRawData = reactor.queryClient.getQueryData(
-      queryKey
-    ) as TInfiniteData
-
-    if (cachedRawData === undefined) {
-      return undefined
-    }
-
-    // Apply config.select to raw cache data
-    const selectedData = (
-      select ? select(cachedRawData) : cachedRawData
-    ) as Selected
-
-    // Apply optional select parameter
-    if (selectFn) {
-      return selectFn(selectedData)
-    }
-
-    return selectedData
-  }
-
-  return {
-    fetch,
-    useInfiniteQuery: useInfiniteQueryHook,
-    invalidate,
-    getQueryKey,
-    getCacheData,
-    ...queryCacheControls<TInfiniteData>(reactor, getQueryKey),
-  }
-}
-
-// ============================================================================
-// Factory Function
-// ============================================================================
-
-export function createInfiniteQuery<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam
-  >,
->(
-  reactor: Reactor<Service, Transform>,
-  config: InfiniteQueryConfig<
-    NoInfer<Service>,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >
-): InfiniteQueryResult<
-  InfiniteQueryPageData<Service, Method, Transform>,
-  TPageParam,
-  Selected,
-  InfiniteQueryError<Service, Method, Transform>
-> {
-  return createInfiniteQueryImpl(
-    reactor,
-    config as InfiniteQueryConfig<
-      Service,
-      Method,
-      Transform,
-      TPageParam,
-      Selected
-    >
-  )
-}
-
-// ============================================================================
-// Factory with Dynamic Args
-// ============================================================================
-
-/**
- * Create an infinite query factory that accepts getArgs at call time.
- * Useful when pagination logic varies by context.
- *
- * @template Service - The actor interface type
- * @template Method - The method name on the actor
- * @template Transform - The transformation key (identity, display, etc.)
- * @template TPageParam - The page parameter type
- * @template Selected - The type returned after select transformation
- *
- * @param reactor - The Reactor instance
- * @param config - Infinite query configuration (without getArgs)
- * @returns A function that accepts getArgs and returns an InfiniteQueryResult
- *
- * @example
- * const getPostsQuery = createInfiniteQueryFactory(reactor, {
- *   functionName: "get_posts",
- *   initialPageParam: 0,
- *   getKeyArgs: (args) => {
- *     const [{ userId }] = args
- *     return [{ userId }]
- *   },
- *   getNextPageParam: (lastPage) => lastPage.nextCursor,
- * })
- *
- * // 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<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    InfiniteQueryPageData<Service, Method, Transform>,
-    TPageParam
-  >,
->(
-  reactor: Reactor<Service, Transform>,
-  config: InfiniteQueryFactoryConfig<
-    NoInfer<Service>,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >
-): 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,
-    // which now does it for every infinite query rather than only for factories.
-    return createInfiniteQueryImpl<
-      Service,
-      Method,
-      Transform,
-      TPageParam,
-      Selected
-    >(reactor, {
-      ...(config as InfiniteQueryFactoryConfig<
-        Service,
-        Method,
-        Transform,
-        TPageParam,
-        Selected
-      >),
-      getArgs,
-    })
-  }
-
-  // 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
-    )
-  )
-}