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

types.ts

345 lines13.4 KB

1/* istanbul ignore file */
2​
3import type {
4 DefaultError,
5 DefinedInfiniteQueryObserverResult,
6 DefinedQueryObserverResult,
7 InfiniteQueryObserverResult,
8 MutateFunction,
9 MutationObserverOptions,
10 MutationObserverResult,
11 OmitKeyof,
12 Override,
13 QueryKey,
14 QueryObserverResult,
15} from '@tanstack/query-core'
16import type { Accessor } from 'solid-js'
17import type {
18 InfiniteQueryObserverOptions,
19 QueryObserverOptions,
20} from './QueryClient'
21​
22/**
23 * The options accepted by `useQuery`. Extends {@link QueryObserverOptions} from `@tanstack/query-core` with
24 * the `solid-query`-specific `deferStream` and `suspense` options.
25 * @template TQueryFnData - The type your `queryFn` resolves to.
26 * @template TError - The type of errors your `queryFn` may throw.
27 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
28 * `select` is used.
29 * @template TQueryData - The type of the data actually held in the query cache β€” the input to `select` and
30 * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
31 * @template TQueryKey - The type of your `queryKey`.
32 */
33export interface UseBaseQueryOptions<
34 TQueryFnData = unknown,
35 TError = DefaultError,
36 TData = TQueryFnData,
37 TQueryData = TQueryFnData,
38 TQueryKey extends QueryKey = QueryKey,
39> extends OmitKeyof<
40 QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
41 'suspense'
42> {
43 /**
44 * Only applicable while rendering queries on the server with streaming.
45 * Set `deferStream` to `true` to wait for the query to resolve on the server before flushing the stream.
46 * This can be useful to avoid sending a loading state to the client before the query has resolved.
47 * @defaultValue false
48 */
49 deferStream?: boolean
50 /**
51 * @deprecated The `suspense` option has been deprecated in v5 and will be removed in the next major version.
52 * The `data` property on useQuery is a SolidJS resource and will automatically suspend when the data is loading.
53 * Setting `suspense` to `false` will be a no-op.
54 */
55 suspense?: boolean
57​
58/**
59 * The options accepted by `useQuery` and `queryOptions`.
60 * @template TQueryFnData - The type your `queryFn` resolves to.
61 * @template TError - The type of errors your `queryFn` may throw.
62 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
63 * `select` is used.
64 * @template TQueryKey - The type of your `queryKey`.
65 */
66export interface QueryOptions<
67 TQueryFnData = unknown,
68 TError = DefaultError,
69 TData = TQueryFnData,
70 TQueryKey extends QueryKey = QueryKey,
71> extends UseBaseQueryOptions<
72 TQueryFnData,
73 TError,
74 TData,
75 TQueryFnData,
76 TQueryKey
77> {}
78​
79/**
80 * The accessor `useQuery` expects as its first argument β€” Solid re-evaluates it reactively, so `queryKey` and
81 * other options can depend on signals.
82 * @template TQueryFnData - The type your `queryFn` resolves to.
83 * @template TError - The type of errors your `queryFn` may throw.
84 * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
85 * `select` is used.
86 * @template TQueryKey - The type of your `queryKey`.
87 */
88export type UseQueryOptions<
89 TQueryFnData = unknown,
90 TError = DefaultError,
91 TData = TQueryFnData,
92 TQueryKey extends QueryKey = QueryKey,
93> = Accessor<QueryOptions<TQueryFnData, TError, TData, TQueryKey>>
94​
95/* --- Create Query and Create Base Query Types --- */
96​
97/**
98 * The object `useQuery` returns when `initialData` isn't set β€” `data`/`error` may still be `undefined`/`null`
99 * while the query is `pending`. Re-exports {@link QueryObserverResult} from `@tanstack/query-core`.
100 * `useInfiniteQuery` returns {@link UseInfiniteQueryResult} instead.
101 * @template TData - The type `data` ends up as, after `select` runs (if set).
102 * @template TError - The type of errors this query may hold.
103 */
104export type UseBaseQueryResult<
105 TData = unknown,
106 TError = DefaultError,
107> = QueryObserverResult<TData, TError>
108​
109/**
110 * The object `useQuery` returns β€” `data`/`error` may still be `undefined`/`null` while the query is
111 * `pending`.
112 * @template TData - The type `data` ends up as, after `select` runs (if set).
113 * @template TError - The type of errors this query may hold.
114 */
115export type UseQueryResult<
116 TData = unknown,
117 TError = DefaultError,
118> = UseBaseQueryResult<TData, TError>
119​
120/**
121 * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
122 * `select` changes `TData` to include `undefined`).
123 * @template TData - The type `data` ends up as, after `select` runs (if set).
124 * @template TError - The type of errors this query may hold.
125 */
126export type DefinedUseBaseQueryResult<
127 TData = unknown,
128 TError = DefaultError,
129> = DefinedQueryObserverResult<TData, TError>
130​
131/**
132 * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
133 * `select` changes `TData` to include `undefined`).
134 * @template TData - The type `data` ends up as, after `select` runs (if set).
135 * @template TError - The type of errors this query may hold.
136 */
137export type DefinedUseQueryResult<
138 TData = unknown,
139 TError = DefaultError,
140> = DefinedUseBaseQueryResult<TData, TError>
141​
142/* --- Create Infinite Queries Types --- */
143/**
144 * The options accepted by `useInfiniteQuery`.
145 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
146 * @template TError - The type of errors your `queryFn` may throw.
147 * @template TData - The type `data` ends up as after `select` runs.
148 * @template TQueryKey - The type of your `queryKey`.
149 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
150 */
151export interface InfiniteQueryOptions<
152 TQueryFnData = unknown,
153 TError = DefaultError,
154 TData = TQueryFnData,
155 TQueryKey extends QueryKey = QueryKey,
156 TPageParam = unknown,
157> extends OmitKeyof<
158 InfiniteQueryObserverOptions<
159 TQueryFnData,
160 TError,
161 TData,
162 TQueryKey,
163 TPageParam
164 >,
165 'queryKey' | 'suspense'
166> {
167 /**
168 * The query key to use for this query. Required here, unlike on the options this type extends.
169 *
170 * The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/solid/guides/query-keys)
171 * for more information.
172 *
173 * The query will automatically update when this key changes (as long as `enabled` is not set to `false`).
174 */
175 queryKey: TQueryKey
176 /**
177 * Only applicable while rendering queries on the server with streaming.
178 * Set `deferStream` to `true` to wait for the query to resolve on the server before flushing the stream.
179 * This can be useful to avoid sending a loading state to the client before the query has resolved.
180 * @defaultValue false
181 */
182 deferStream?: boolean
183 /**
184 * @deprecated The `suspense` option has been deprecated in v5 and will be removed in the next major version.
185 * The `data` property on useInfiniteQuery is a SolidJS resource and will automatically suspend when the data is loading.
186 * Setting `suspense` to `false` will be a no-op.
187 */
188 suspense?: boolean
190​
191/**
192 * The accessor `useInfiniteQuery` expects as its first argument β€” Solid re-evaluates it reactively, so
193 * `queryKey` and other options can depend on signals.
194 * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
195 * @template TError - The type of errors your `queryFn` may throw.
196 * @template TData - The type `data` ends up as after `select` runs.
197 * @template TQueryKey - The type of your `queryKey`.
198 * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
199 */
200export type UseInfiniteQueryOptions<
201 TQueryFnData = unknown,
202 TError = DefaultError,
203 TData = TQueryFnData,
204 TQueryKey extends QueryKey = QueryKey,
205 TPageParam = unknown,
206> = Accessor<
207 InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
209​
210/**
211 * The object `useInfiniteQuery` returns β€” `data`/`error` may still be `undefined`/`null` while the query is
212 * `pending`.
213 * @template TData - The type `data` ends up as, after `select` runs (if set).
214 * @template TError - The type of errors this query may hold.
215 */
216export type UseInfiniteQueryResult<
217 TData = unknown,
218 TError = DefaultError,
219> = InfiniteQueryObserverResult<TData, TError>
220​
221/**
222 * The object `useInfiniteQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
223 * `select` changes `TData` to include `undefined`).
224 * @template TData - The type `data` ends up as, after `select` runs (if set).
225 * @template TError - The type of errors this query may hold.
226 */
227export type DefinedUseInfiniteQueryResult<
228 TData = unknown,
229 TError = DefaultError,
230> = DefinedInfiniteQueryObserverResult<TData, TError>
231​
232/* --- Create Mutation Types --- */
233/**
234 * The options accepted by `useMutation` and `mutationOptions`.
235 * @template TData - The type your `mutationFn` resolves to.
236 * @template TError - The type of errors your `mutationFn` may throw.
237 * @template TVariables - The type of the variables your `mutationFn` accepts.
238 * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
239 */
240export interface MutationOptions<
241 TData = unknown,
242 TError = DefaultError,
243 TVariables = void,
244 TOnMutateResult = unknown,
245> extends OmitKeyof<
246 MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
247 '_defaulted'
248> {}
249​
250/**
251 * The accessor `useMutation` expects as its first argument β€” Solid re-evaluates it reactively, so callbacks
252 * and other options can depend on signals.
253 * @template TData - The type your `mutationFn` resolves to.
254 * @template TError - The type of errors your `mutationFn` may throw.
255 * @template TVariables - The type of the variables your `mutationFn` accepts.
256 * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
257 */
258export type UseMutationOptions<
259 TData = unknown,
260 TError = DefaultError,
261 TVariables = void,
262 TOnMutateResult = unknown,
263> = Accessor<MutationOptions<TData, TError, TVariables, TOnMutateResult>>
264​
265/**
266 * The type of `mutate`, as returned by `useMutation`. Forwards the variables (and an optional per-call
267 * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget β€” errors are surfaced
268 * through the mutation result instead of being thrown by `mutate`, unless `throwOnError` makes `useMutation`
269 * rethrow them.
270 * @template TData - The type your mutation function resolves to.
271 * @template TError - The type of errors your mutation function may throw.
272 * @template TVariables - The type of the variable passed to `mutate`.
273 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
274 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
275 */
276export type UseMutateFunction<
277 TData = unknown,
278 TError = DefaultError,
279 TVariables = void,
280 TOnMutateResult = unknown,
281> = (
282 ...args: Parameters<
283 MutateFunction<TData, TError, TVariables, TOnMutateResult>
284 >
285) => void
286​
287/**
288 * The type of `mutateAsync`, as returned by `useMutation`. Similar to {@link UseMutateFunction}, but returns a
289 * promise which can be awaited.
290 * @template TData - The type your `mutationFn` resolves to.
291 * @template TError - The type of errors your `mutationFn` may throw.
292 * @template TVariables - The type of the variable passed to `mutateAsync`.
293 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
294 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
295 */
296export type UseMutateAsyncFunction<
297 TData = unknown,
298 TError = DefaultError,
299 TVariables = void,
300 TOnMutateResult = unknown,
301> = MutateFunction<TData, TError, TVariables, TOnMutateResult>
302​
303/**
304 * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
305 * `mutate` narrowed to the fire-and-forget {@link UseMutateFunction} signature, plus the added `mutateAsync`.
306 * @template TData - The type your `mutationFn` resolves to.
307 * @template TError - The type of errors your `mutationFn` may throw.
308 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
309 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
310 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
311 */
312export type UseBaseMutationResult<
313 TData = unknown,
314 TError = DefaultError,
315 TVariables = unknown,
316 TOnMutateResult = unknown,
317> = Override<
318 MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
319 { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
320> & {
321 /**
322 * Similar to `mutate`, but returns a promise which can be awaited.
323 */
324 mutateAsync: UseMutateAsyncFunction<
325 TData,
326 TError,
327 TVariables,
328 TOnMutateResult
329 >
331​
332/**
333 * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
334 * @template TData - The type your `mutationFn` resolves to.
335 * @template TError - The type of errors your `mutationFn` may throw.
336 * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
337 * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
338 * their `onMutateResult` parameter β€” useful for optimistic-update rollback data.
339 */
340export type UseMutationResult<
341 TData = unknown,
342 TError = DefaultError,
343 TVariables = unknown,
344 TOnMutateResult = unknown,
345> = UseBaseMutationResult<TData, TError, TVariables, TOnMutateResult>