Open History to see the last commit
1import { InfiniteQueryObserver } from '@tanstack/query-core'
2import { createMemo } from 'solid-js'
3import { useBaseQuery } from './useBaseQuery'
4import type {
5 DefaultError,
6 InfiniteData,
7 QueryKey,
8 QueryObserver,
9} from '@tanstack/query-core'
10import type { Accessor } from 'solid-js'
11import type { QueryClient } from './QueryClient'
12import type {
13 DefinedInitialDataInfiniteOptions,
14 UndefinedInitialDataInfiniteOptions,
15} from './infiniteQueryOptions'
16import type {
17 DefinedUseInfiniteQueryResult,
18 UseInfiniteQueryOptions,
19 UseInfiniteQueryResult,
20} from './types'
21β
22/**
23 * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
24 * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
25 *
26 * This overload is selected when `initialData` is known to be defined.
27 * @param options - An accessor returning the {@link DefinedInitialDataInfiniteOptions} to use β everything
28 * you can pass to `useInfiniteQuery`, with `initialData` known to be defined.
29 * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
30 * will be used.
31 * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
32 * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
33 * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
34 * `InfiniteData<TQueryFnData>` shape.
35 * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
36 * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
37 * actions, or add conditions like `hasNextPage && !isFetching`.
38 * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
39 * @example
40 * ```tsx
41 * import { For } from 'solid-js'
42 * import { useInfiniteQuery } from '@tanstack/solid-query'
43 *
44 * function Projects() {
45 * // `projectsQuery.data` is never `undefined`, thanks to `initialData` β even if a refetch fails, so the
46 * // list stays visible alongside the error.
47 * const projectsQuery = useInfiniteQuery(() => ({
48 * queryKey: ['projects'],
49 * queryFn: ({ pageParam }) => fetchProjects(pageParam),
50 * initialPageParam: 0,
51 * getNextPageParam: (lastPage) => lastPage.nextId,
52 * initialData: { pages: [], pageParams: [] },
53 * }))
54 *
55 * return (
56 * <div>
57 * {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
58 * <ul>
59 * <For each={projectsQuery.data.pages}>
60 * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
61 * </For>
62 * </ul>
63 * </div>
64 * )
65 * }
66 * ```
67 */
68export function useInfiniteQuery<
69 TQueryFnData,
70 TError = DefaultError,
71 TData = InfiniteData<TQueryFnData>,
72 TQueryKey extends QueryKey = QueryKey,
73 TPageParam = unknown,
74>(
75 options: DefinedInitialDataInfiniteOptions<
76 TQueryFnData,
77 TError,
78 TData,
79 TQueryKey,
80 TPageParam
81 >,
82 queryClient?: Accessor<QueryClient>,
83): DefinedUseInfiniteQueryResult<TData, TError>
84β
85/**
86 * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
87 * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
88 * @param options - An accessor returning the {@link UndefinedInitialDataInfiniteOptions} to use β everything
89 * you can pass to `useInfiniteQuery`.
90 * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
91 * will be used.
92 * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
93 * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and
94 * `data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
95 * `InfiniteData<TQueryFnData>` shape.
96 * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
97 * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
98 * actions, or add conditions like `hasNextPage && !isFetching`.
99 * @see {@link infiniteQueryOptions} to share these options between `useInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`.
100 * @example
101 * Fetching the next page from a "Load More" button click:
102 * ```tsx
103 * import { For, Match, Switch } from 'solid-js'
104 * import { useInfiniteQuery } from '@tanstack/solid-query'
105 *
106 * function Projects() {
107 * const projectsQuery = useInfiniteQuery(() => ({
108 * queryKey: ['projects'],
109 * queryFn: ({ pageParam }) => fetchProjects(pageParam),
110 * initialPageParam: 0,
111 * getNextPageParam: (lastPage) => lastPage.nextId,
112 * }))
113 *
114 * return (
115 * <Switch>
116 * <Match when={projectsQuery.isPending}>Loading...</Match>
117 * <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
118 * <Match when={projectsQuery.isSuccess}>
119 * <ul>
120 * <For each={projectsQuery.data.pages}>
121 * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
122 * </For>
123 * </ul>
124 * <button
125 * onClick={() => projectsQuery.fetchNextPage()}
126 * disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
127 * >
128 * {projectsQuery.isFetchingNextPage
129 * ? 'Loading more...'
130 * : projectsQuery.hasNextPage
131 * ? 'Load More'
132 * : 'Nothing more to load'}
133 * </button>
134 * </Match>
135 * </Switch>
136 * )
137 * }
138 * ```
139 * @example
140 * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
141 * sentinel element after the list:
142 * ```tsx
143 * import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'
144 * import { useInfiniteQuery } from '@tanstack/solid-query'
145 *
146 * function Projects() {
147 * const projectsQuery = useInfiniteQuery(() => ({
148 * queryKey: ['projects'],
149 * queryFn: ({ pageParam }) => fetchProjects(pageParam),
150 * initialPageParam: 0,
151 * getNextPageParam: (lastPage) => lastPage.nextId,
152 * }))
153 *
154 * let sentinelRef: HTMLDivElement | undefined
155 *
156 * createEffect(() => {
157 * if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return
158 *
159 * const observer = new IntersectionObserver(([entry]) => {
160 * if (entry?.isIntersecting) projectsQuery.fetchNextPage()
161 * })
162 * observer.observe(sentinelRef)
163 *
164 * onCleanup(() => observer.disconnect())
165 * })
166 *
167 * return (
168 * <Switch>
169 * <Match when={projectsQuery.isPending}>Loading...</Match>
170 * <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>
171 * <Match when={projectsQuery.isSuccess}>
172 * <ul>
173 * <For each={projectsQuery.data.pages}>
174 * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
175 * </For>
176 * </ul>
177 * <div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>
178 * </Match>
179 * </Switch>
180 * )
181 * }
182 * ```
183 */
184export function useInfiniteQuery<
185 TQueryFnData,
186 TError = DefaultError,
187 TData = InfiniteData<TQueryFnData>,
188 TQueryKey extends QueryKey = QueryKey,
189 TPageParam = unknown,
190>(
191 options: UndefinedInitialDataInfiniteOptions<
192 TQueryFnData,
193 TError,
194 TData,
195 TQueryKey,
196 TPageParam
197 >,
198 queryClient?: Accessor<QueryClient>,
199): UseInfiniteQueryResult<TData, TError>
200β
201export function useInfiniteQuery<
202 TQueryFnData,
203 TError = DefaultError,
204 TData = InfiniteData<TQueryFnData>,
205 TQueryKey extends QueryKey = QueryKey,
206 TPageParam = unknown,
207>(
208 options: UseInfiniteQueryOptions<
209 TQueryFnData,
210 TError,
211 TData,
212 TQueryKey,
213 TPageParam
214 >,
215 queryClient?: Accessor<QueryClient>,
216): UseInfiniteQueryResult<TData, TError> {
217 return useBaseQuery(
218 createMemo(() => options()),
219 InfiniteQueryObserver as typeof QueryObserver,
220 queryClient,
221 ) as UseInfiniteQueryResult<TData, TError>
222}