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

queryOptions.ts

158 lines5.7 KB

1import type {
2 DefaultError,
3 InitialDataFunction,
4 NonUndefinedGuard,
5 QueryKey,
6 QueryKeyWithDataTag,
7} from '@tanstack/query-core'
8import type { QueryOptions } from './types'
9import type { Accessor } from 'solid-js'
10​
11/**
12 * The options accepted by the `queryOptions` overload selected when `initialData` is omitted, may be
13 * `undefined`, or is a function that may return `undefined` β€” `data` may be `undefined` while the query is
14 * `pending`. `queryOptions` itself accepts and returns a plain object (its parameter type is
15 * `ReturnType<UndefinedInitialDataOptions<...>>`, i.e. this `Accessor` called); Solid's reactivity applies
16 * where the result is consumed instead, e.g. `useQuery(() => options)`.
17 * @template TQueryFnData - The type your `queryFn` resolves to.
18 * @template TError - The type of errors your `queryFn` may throw.
19 * @template TData - The type `data` ends up as after `select` runs.
20 * @template TQueryKey - The type of your `queryKey`.
21 */
22export type UndefinedInitialDataOptions<
23 TQueryFnData = unknown,
24 TError = DefaultError,
25 TData = TQueryFnData,
26 TQueryKey extends QueryKey = QueryKey,
27> = Accessor<
28 QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
29 initialData?:
30 | undefined
31 | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
32 | NonUndefinedGuard<TQueryFnData>
33 }
35​
36/**
37 * The options accepted by the `queryOptions` overload selected when `initialData` is known to be defined β€”
38 * `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`).
39 * @template TQueryFnData - The type your `queryFn` resolves to.
40 * @template TError - The type of errors your `queryFn` may throw.
41 * @template TData - The type `data` ends up as after `select` runs.
42 * @template TQueryKey - The type of your `queryKey`.
43 */
44export type DefinedInitialDataOptions<
45 TQueryFnData = unknown,
46 TError = DefaultError,
47 TData = TQueryFnData,
48 TQueryKey extends QueryKey = QueryKey,
49> = Accessor<
50 QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
51 initialData:
52 | NonUndefinedGuard<TQueryFnData>
53 | (() => NonUndefinedGuard<TQueryFnData>)
54 }
56​
57/**
58 * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
59 * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
60 * is the query key to generate options for.
61 *
62 * This overload is selected when `initialData` is known to be defined, so the resulting `data` is never
63 * `undefined` (unless a `select` changes `TData` to include `undefined`).
64 * @param options - The {@link DefinedInitialDataOptions} to use β€” everything you can pass to `useQuery`, with `initialData` known to be defined.
65 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
66 * @see {@link useQuery} to run a query with these options.
67 * @example
68 * ```tsx
69 * import { For } from 'solid-js'
70 * import { queryOptions, useQuery } from '@tanstack/solid-query'
71 *
72 * const postsOptions = queryOptions({
73 * queryKey: ['posts'],
74 * queryFn: fetchPosts,
75 * initialData: [],
76 * })
77 *
78 * function Posts() {
79 * // `postsQuery.data` is `Post[]`, never `undefined`, thanks to `initialData` β€” even if a refetch fails,
80 * // so the list stays visible alongside the error.
81 * const postsQuery = useQuery(() => postsOptions)
82 *
83 * return (
84 * <div>
85 * {postsQuery.isError ? <span>Error: {postsQuery.error.message}</span> : null}
86 * <ul>
87 * <For each={postsQuery.data}>{(post) => <li>{post.title}</li>}</For>
88 * </ul>
89 * </div>
90 * )
91 * }
92 * ```
93 */
94export function queryOptions<
95 TQueryFnData = unknown,
96 TError = DefaultError,
97 TData = TQueryFnData,
98 TQueryKey extends QueryKey = QueryKey,
99>(
100 options: ReturnType<
101 DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
102 >,
103): ReturnType<
104 DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
105> &
106 QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
107​
108/**
109 * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
110 * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
111 * is the query key to generate options for.
112 * @param options - The {@link UndefinedInitialDataOptions} to use β€” everything you can pass to `useQuery`.
113 * @returns The same options object, typed so that `queryKey` carries the inferred data type.
114 * @see {@link useQuery} to run a query with these options.
115 * @example
116 * A parameterized factory, so the same options object can be reused per `id`:
117 * ```tsx
118 * import { Match, Switch } from 'solid-js'
119 * import { queryOptions, useQuery } from '@tanstack/solid-query'
120 *
121 * const postOptions = (id: string) =>
122 * queryOptions({
123 * queryKey: ['post', id],
124 * queryFn: () => fetchPost(id),
125 * })
126 *
127 * function Post(props: { id: string }) {
128 * const postQuery = useQuery(() => postOptions(props.id))
129 *
130 * return (
131 * <Switch>
132 * <Match when={postQuery.isPending}>Loading...</Match>
133 * <Match when={postQuery.isError}>Error: {postQuery.error.message}</Match>
134 * <Match when={postQuery.isSuccess}>
135 * <h1>{postQuery.data.title}</h1>
136 * </Match>
137 * </Switch>
138 * )
139 * }
140 * ```
141 */
142export function queryOptions<
143 TQueryFnData = unknown,
144 TError = DefaultError,
145 TData = TQueryFnData,
146 TQueryKey extends QueryKey = QueryKey,
147>(
148 options: ReturnType<
149 UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
150 >,
151): ReturnType<
152 UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
153> &
154 QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
155​
156export function queryOptions(options: unknown) {
157 return options