Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

infiniteQueryOptions.ts

203 lines7.4 KB

1import type {
2 DefaultError,
3 InfiniteData,
4 InitialDataFunction,
5 NonUndefinedGuard,
6 QueryKey,
7 QueryKeyWithDataTag,
8} from '@tanstack/query-core'
9import type { Accessor } from 'solid-js'
10import type { InfiniteQueryOptions } from './types'
11​
12/**
13 * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is omitted, may be
14 * `undefined`, or is a function that may return `undefined` β€” `data` may be `undefined` while the query is
15 * `pending`. `infiniteQueryOptions` itself accepts and returns a plain object (its parameter type is
16 * `ReturnType<UndefinedInitialDataInfiniteOptions<...>>`, i.e. this `Accessor` called); Solid's reactivity
17 * applies where the result is consumed instead, e.g. `useInfiniteQuery(() => options)`.
18 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
19 * @template TError - The type of errors your `queryFn` may throw.
20 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
21 * the shape of all fetched pages plus their page params.
22 * @template TQueryKey - The type of your `queryKey`.
23 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
24 */
25export type UndefinedInitialDataInfiniteOptions<
26 TQueryFnData,
27 TError = DefaultError,
28 TData = InfiniteData<TQueryFnData>,
29 TQueryKey extends QueryKey = QueryKey,
30 TPageParam = unknown,
31> = Accessor<
32 InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
33 initialData?:
34 | undefined
35 | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
36 | InitialDataFunction<
37 NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
38 >
39 }
41​
42/**
43 * The options accepted by the `infiniteQueryOptions` overload selected when `initialData` is known to be
44 * defined β€” `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
45 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
46 * @template TError - The type of errors your `queryFn` may throw.
47 * @template TData - The type `data` ends up as after `select` runs β€” defaults to `InfiniteData<TQueryFnData>`,
48 * the shape of all fetched pages plus their page params.
49 * @template TQueryKey - The type of your `queryKey`.
50 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
51 */
52export type DefinedInitialDataInfiniteOptions<
53 TQueryFnData,
54 TError = DefaultError,
55 // should we handle page param correctly
56 TData = InfiniteData<TQueryFnData>,
57 TQueryKey extends QueryKey = QueryKey,
58 TPageParam = unknown,
59> = Accessor<
60 InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
61 initialData:
62 | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
63 | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
64 }
66​
67/**
68 * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
69 * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
70 * `options.queryKey` is required and is the query key to generate options for.
71 *
72 * This overload is selected when `initialData` is known to be defined.
73 * @param options - The {@link DefinedInitialDataInfiniteOptions} to use β€” everything you can pass to `useInfiniteQuery`, with `initialData` known to be defined.
74 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
75 * @see {@link useInfiniteQuery} to run an infinite query with these options.
76 * @example
77 * ```tsx
78 * import { For } from 'solid-js'
79 * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
80 *
81 * const projectsOptions = infiniteQueryOptions({
82 * queryKey: ['projects'],
83 * queryFn: ({ pageParam }) => fetchProjects(pageParam),
84 * initialPageParam: 0,
85 * getNextPageParam: (lastPage) => lastPage.nextId,
86 * initialData: { pages: [], pageParams: [] },
87 * })
88 *
89 * function Projects() {
90 * // `projectsQuery.data` is never `undefined`, thanks to `initialData` β€” even if a refetch fails, so the
91 * // list stays visible alongside the error.
92 * const projectsQuery = useInfiniteQuery(() => projectsOptions)
93 *
94 * return (
95 * <div>
96 * {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}
97 * <ul>
98 * <For each={projectsQuery.data.pages}>
99 * {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}
100 * </For>
101 * </ul>
102 * </div>
103 * )
104 * }
105 * ```
106 */
107export function infiniteQueryOptions<
108 TQueryFnData,
109 TError = DefaultError,
110 TData = InfiniteData<TQueryFnData>,
111 TQueryKey extends QueryKey = QueryKey,
112 TPageParam = unknown,
113>(
114 options: ReturnType<
115 DefinedInitialDataInfiniteOptions<
116 TQueryFnData,
117 TError,
118 TData,
119 TQueryKey,
120 TPageParam
121 >
122 >,
123): ReturnType<
124 DefinedInitialDataInfiniteOptions<
125 TQueryFnData,
126 TError,
127 TData,
128 TQueryKey,
129 TPageParam
130 >
131> &
132 QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
133​
134/**
135 * You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
136 * These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
137 * `options.queryKey` is required and is the query key to generate options for.
138 * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use β€” everything you can pass to `useInfiniteQuery`.
139 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
140 * @see {@link useInfiniteQuery} to run an infinite query with these options.
141 * @example
142 * A parameterized factory, so the same options object can be reused per `postId`:
143 * ```tsx
144 * import { For, Match, Switch } from 'solid-js'
145 * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/solid-query'
146 *
147 * const commentsOptions = (postId: string) =>
148 * infiniteQueryOptions({
149 * queryKey: ['post', postId, 'comments'],
150 * queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
151 * initialPageParam: 0,
152 * getNextPageParam: (lastPage) => lastPage.nextId,
153 * })
154 *
155 * function Comments(props: { postId: string }) {
156 * const commentsQuery = useInfiniteQuery(() => commentsOptions(props.postId))
157 *
158 * return (
159 * <Switch>
160 * <Match when={commentsQuery.isPending}>Loading...</Match>
161 * <Match when={commentsQuery.isError}>Error: {commentsQuery.error.message}</Match>
162 * <Match when={commentsQuery.isSuccess}>
163 * <ul>
164 * <For each={commentsQuery.data.pages}>
165 * {(page) => <For each={page.comments}>{(c) => <li>{c.text}</li>}</For>}
166 * </For>
167 * </ul>
168 * </Match>
169 * </Switch>
170 * )
171 * }
172 * ```
173 */
174export function infiniteQueryOptions<
175 TQueryFnData,
176 TError = DefaultError,
177 TData = InfiniteData<TQueryFnData>,
178 TQueryKey extends QueryKey = QueryKey,
179 TPageParam = unknown,
180>(
181 options: ReturnType<
182 UndefinedInitialDataInfiniteOptions<
183 TQueryFnData,
184 TError,
185 TData,
186 TQueryKey,
187 TPageParam
188 >
189 >,
190): ReturnType<
191 UndefinedInitialDataInfiniteOptions<
192 TQueryFnData,
193 TError,
194 TData,
195 TQueryKey,
196 TPageParam
197 >
198> &
199 QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
200​
201export function infiniteQueryOptions(options: unknown) {
202 return options