@tanstack/solid-query 6.0.0-rc.5 → 6.0.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,27 @@
1
1
  import type {
2
- DataTag,
3
2
  DefaultError,
4
3
  InfiniteData,
4
+ InitialDataFunction,
5
5
  NonUndefinedGuard,
6
6
  QueryKey,
7
+ QueryKeyWithDataTag,
7
8
  } from '@tanstack/query-core'
8
9
  import type { InfiniteQueryOptions } from './types'
9
10
  import type { Accessor } from 'solid-js'
10
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
+ */
11
25
  export type UndefinedInitialDataInfiniteOptions<
12
26
  TQueryFnData,
13
27
  TError = DefaultError,
@@ -16,10 +30,25 @@ export type UndefinedInitialDataInfiniteOptions<
16
30
  TPageParam = unknown,
17
31
  > = Accessor<
18
32
  InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
19
- initialData?: undefined
33
+ initialData?:
34
+ | undefined
35
+ | NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
36
+ | InitialDataFunction<
37
+ NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>
38
+ >
20
39
  }
21
40
  >
22
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
+ */
23
52
  export type DefinedInitialDataInfiniteOptions<
24
53
  TQueryFnData,
25
54
  TError = DefaultError,
@@ -34,6 +63,47 @@ export type DefinedInitialDataInfiniteOptions<
34
63
  | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
35
64
  }
36
65
  >
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
+ */
37
107
  export function infiniteQueryOptions<
38
108
  TQueryFnData,
39
109
  TError = DefaultError,
@@ -58,9 +128,49 @@ export function infiniteQueryOptions<
58
128
  TQueryKey,
59
129
  TPageParam
60
130
  >
61
- > & {
62
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>>
63
- }
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
+ */
64
174
  export function infiniteQueryOptions<
65
175
  TQueryFnData,
66
176
  TError = DefaultError,
@@ -85,9 +195,8 @@ export function infiniteQueryOptions<
85
195
  TQueryKey,
86
196
  TPageParam
87
197
  >
88
- > & {
89
- queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>>
90
- }
198
+ > &
199
+ QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>
91
200
 
92
201
  export function infiniteQueryOptions(options: unknown) {
93
202
  return options
@@ -3,4 +3,10 @@ import type { Accessor } from 'solid-js'
3
3
 
4
4
  export const IsRestoringContext = createContext<Accessor<boolean>>(() => false)
5
5
 
6
+ /**
7
+ * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` primitive alongside it to
8
+ * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
9
+ * race conditions between the restore and mounting queries.
10
+ * @returns An accessor that reads `true` while a persisted client is being restored, `false` otherwise.
11
+ */
6
12
  export const useIsRestoring = () => useContext(IsRestoringContext)
@@ -1,6 +1,33 @@
1
1
  import type { DefaultError, WithRequired } from '@tanstack/query-core'
2
2
  import type { MutationOptions } from './types'
3
3
 
4
+ /**
5
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A
6
+ * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
7
+ * `useMutationState`.
8
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, with a
9
+ * required `mutationKey`.
10
+ * @returns The same options object, unchanged.
11
+ * @see {@link useMutation} to run the mutation these options describe.
12
+ * @example
13
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
14
+ * ```tsx
15
+ * import { mutationOptions, useMutationState } from '@tanstack/solid-query'
16
+ *
17
+ * const createPostOptions = mutationOptions({
18
+ * mutationKey: ['posts', 'create'],
19
+ * mutationFn: createPost,
20
+ * })
21
+ *
22
+ * function SavingIndicator() {
23
+ * const isCreatingPost = useMutationState(() => ({
24
+ * filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
25
+ * }))
26
+ *
27
+ * return isCreatingPost().length > 0 ? <span>Saving…</span> : null
28
+ * }
29
+ * ```
30
+ */
4
31
  export function mutationOptions<
5
32
  TData = unknown,
6
33
  TError = DefaultError,
@@ -15,6 +42,30 @@ export function mutationOptions<
15
42
  MutationOptions<TData, TError, TVariables, TOnMutateResult>,
16
43
  'mutationKey'
17
44
  >
45
+ /**
46
+ * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
47
+ * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
48
+ * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
49
+ * such as `status`.
50
+ * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
51
+ * `mutationKey`.
52
+ * @returns The same options object, unchanged.
53
+ * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
54
+ * @see {@link useMutation} to run the mutation these options describe.
55
+ * @example
56
+ * ```tsx
57
+ * import { mutationOptions, useMutation } from '@tanstack/solid-query'
58
+ *
59
+ * const createPostOptions = mutationOptions({
60
+ * mutationFn: createPost,
61
+ * })
62
+ *
63
+ * function CreatePost() {
64
+ * const createPostMutation = useMutation(() => createPostOptions)
65
+ * return <button onClick={() => createPostMutation.mutate({ title: 'Hello' })}>Create</button>
66
+ * }
67
+ * ```
68
+ */
18
69
  export function mutationOptions<
19
70
  TData = unknown,
20
71
  TError = DefaultError,
@@ -1,7 +1,24 @@
1
- import type { DataTag, DefaultError, QueryKey } from '@tanstack/query-core'
1
+ import type {
2
+ DefaultError,
3
+ InitialDataFunction,
4
+ NonUndefinedGuard,
5
+ QueryKey,
6
+ QueryKeyWithDataTag,
7
+ } from '@tanstack/query-core'
2
8
  import type { QueryOptions } from './types'
3
9
  import type { Accessor } from 'solid-js'
4
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
+ */
5
22
  export type UndefinedInitialDataOptions<
6
23
  TQueryFnData = unknown,
7
24
  TError = DefaultError,
@@ -9,10 +26,21 @@ export type UndefinedInitialDataOptions<
9
26
  TQueryKey extends QueryKey = QueryKey,
10
27
  > = Accessor<
11
28
  QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
12
- initialData?: undefined
29
+ initialData?:
30
+ | undefined
31
+ | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
32
+ | NonUndefinedGuard<TQueryFnData>
13
33
  }
14
34
  >
15
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
+ */
16
44
  export type DefinedInitialDataOptions<
17
45
  TQueryFnData = unknown,
18
46
  TError = DefaultError,
@@ -20,10 +48,49 @@ export type DefinedInitialDataOptions<
20
48
  TQueryKey extends QueryKey = QueryKey,
21
49
  > = Accessor<
22
50
  QueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
23
- initialData: TQueryFnData | (() => TQueryFnData)
51
+ initialData:
52
+ | NonUndefinedGuard<TQueryFnData>
53
+ | (() => NonUndefinedGuard<TQueryFnData>)
24
54
  }
25
55
  >
26
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
+ */
27
94
  export function queryOptions<
28
95
  TQueryFnData = unknown,
29
96
  TError = DefaultError,
@@ -31,14 +98,47 @@ export function queryOptions<
31
98
  TQueryKey extends QueryKey = QueryKey,
32
99
  >(
33
100
  options: ReturnType<
34
- UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
101
+ DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
35
102
  >,
36
103
  ): ReturnType<
37
- UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
38
- > & {
39
- queryKey: DataTag<TQueryKey, TQueryFnData, TError>
40
- }
104
+ DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
105
+ > &
106
+ QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
41
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
+ */
42
142
  export function queryOptions<
43
143
  TQueryFnData = unknown,
44
144
  TError = DefaultError,
@@ -46,13 +146,12 @@ export function queryOptions<
46
146
  TQueryKey extends QueryKey = QueryKey,
47
147
  >(
48
148
  options: ReturnType<
49
- DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
149
+ UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
50
150
  >,
51
151
  ): ReturnType<
52
- DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
53
- > & {
54
- queryKey: DataTag<TQueryKey, TQueryFnData, TError>
55
- }
152
+ UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
153
+ > &
154
+ QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
56
155
 
57
156
  export function queryOptions(options: unknown) {
58
157
  return options
package/src/types.ts CHANGED
@@ -18,6 +18,17 @@ import type {
18
18
  } from './QueryClient'
19
19
  import type { Accessor } from 'solid-js'
20
20
 
21
+ /**
22
+ * The options accepted by `useQuery`. Extends {@link QueryObserverOptions} from `@tanstack/query-core` with
23
+ * the `solid-query`-specific `deferStream` and `reconcile` options.
24
+ * @template TQueryFnData - The type your `queryFn` resolves to.
25
+ * @template TError - The type of errors your `queryFn` may throw.
26
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
27
+ * `select` is used.
28
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
29
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
30
+ * @template TQueryKey - The type of your `queryKey`.
31
+ */
21
32
  export interface UseBaseQueryOptions<
22
33
  TQueryFnData = unknown,
23
34
  TError = DefaultError,
@@ -47,6 +58,14 @@ export interface UseBaseQueryOptions<
47
58
  reconcile?: string | ((item: NonNullable<any>) => any) | null
48
59
  }
49
60
 
61
+ /**
62
+ * The options accepted by `useQuery` and `queryOptions`.
63
+ * @template TQueryFnData - The type your `queryFn` resolves to.
64
+ * @template TError - The type of errors your `queryFn` may throw.
65
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
66
+ * `select` is used.
67
+ * @template TQueryKey - The type of your `queryKey`.
68
+ */
50
69
  export interface QueryOptions<
51
70
  TQueryFnData = unknown,
52
71
  TError = DefaultError,
@@ -60,6 +79,15 @@ export interface QueryOptions<
60
79
  TQueryKey
61
80
  > {}
62
81
 
82
+ /**
83
+ * The accessor `useQuery` expects as its first argument — Solid re-evaluates it reactively, so `queryKey` and
84
+ * other options can depend on signals.
85
+ * @template TQueryFnData - The type your `queryFn` resolves to.
86
+ * @template TError - The type of errors your `queryFn` may throw.
87
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
88
+ * `select` is used.
89
+ * @template TQueryKey - The type of your `queryKey`.
90
+ */
63
91
  export type UseQueryOptions<
64
92
  TQueryFnData = unknown,
65
93
  TError = DefaultError,
@@ -85,6 +113,11 @@ export type UseBaseQueryResult<
85
113
  { data: TData }
86
114
  >
87
115
 
116
+ /**
117
+ * The object `useQuery` returns. Same as {@link UseBaseQueryResult}.
118
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
119
+ * @template TError - The type of errors this query may hold.
120
+ */
88
121
  export type UseQueryResult<
89
122
  TData = unknown,
90
123
  TError = DefaultError,
@@ -98,17 +131,37 @@ type OmitIsInitialLoading<T> = T extends unknown
98
131
  ? OmitKeyof<T, 'isInitialLoading' & keyof T>
99
132
  : never
100
133
 
134
+ /**
135
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
136
+ * `select` changes `TData` to include `undefined`).
137
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
138
+ * @template TError - The type of errors this query may hold.
139
+ */
101
140
  export type DefinedUseBaseQueryResult<
102
141
  TData = unknown,
103
142
  TError = DefaultError,
104
143
  > = OmitIsInitialLoading<DefinedQueryObserverResult<TData, TError>>
105
144
 
145
+ /**
146
+ * The object `useQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
147
+ * `select` changes `TData` to include `undefined`).
148
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
149
+ * @template TError - The type of errors this query may hold.
150
+ */
106
151
  export type DefinedUseQueryResult<
107
152
  TData = unknown,
108
153
  TError = DefaultError,
109
154
  > = DefinedUseBaseQueryResult<TData, TError>
110
155
 
111
156
  /* --- Create Infinite Queries Types --- */
157
+ /**
158
+ * The options accepted by `useInfiniteQuery`.
159
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
160
+ * @template TError - The type of errors your `queryFn` may throw.
161
+ * @template TData - The type `data` ends up as after `select` runs.
162
+ * @template TQueryKey - The type of your `queryKey`.
163
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
164
+ */
112
165
  export interface InfiniteQueryOptions<
113
166
  TQueryFnData = unknown,
114
167
  TError = DefaultError,
@@ -125,6 +178,14 @@ export interface InfiniteQueryOptions<
125
178
  >,
126
179
  'queryKey' | 'suspense'
127
180
  > {
181
+ /**
182
+ * The query key to use for this query. Required here, unlike on the options this type extends.
183
+ *
184
+ * The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/solid/guides/query-keys)
185
+ * for more information.
186
+ *
187
+ * The query will automatically update when this key changes (as long as `enabled` is not set to `false`).
188
+ */
128
189
  queryKey: TQueryKey
129
190
  /**
130
191
  * Defer the SSR stream flush until this query resolves on the server —
@@ -139,6 +200,15 @@ export interface InfiniteQueryOptions<
139
200
  reconcile?: string | ((item: NonNullable<any>) => any) | null
140
201
  }
141
202
 
203
+ /**
204
+ * The accessor `useInfiniteQuery` expects as its first argument — Solid re-evaluates it reactively, so
205
+ * `queryKey` and other options can depend on signals.
206
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
207
+ * @template TError - The type of errors your `queryFn` may throw.
208
+ * @template TData - The type `data` ends up as after `select` runs.
209
+ * @template TQueryKey - The type of your `queryKey`.
210
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
211
+ */
142
212
  export type UseInfiniteQueryOptions<
143
213
  TQueryFnData = unknown,
144
214
  TError = DefaultError,
@@ -158,12 +228,25 @@ export type UseInfiniteQueryResult<
158
228
  { data: TData }
159
229
  >
160
230
 
231
+ /**
232
+ * The object `useInfiniteQuery` returns when `initialData` guarantees `data` is never `undefined` (unless a
233
+ * `select` changes `TData` to include `undefined`).
234
+ * @template TData - The type `data` ends up as, after `select` runs (if set).
235
+ * @template TError - The type of errors this query may hold.
236
+ */
161
237
  export type DefinedUseInfiniteQueryResult<
162
238
  TData = unknown,
163
239
  TError = DefaultError,
164
240
  > = OmitIsInitialLoading<DefinedInfiniteQueryObserverResult<TData, TError>>
165
241
 
166
242
  /* --- Create Mutation Types --- */
243
+ /**
244
+ * The options accepted by `useMutation` and `mutationOptions`.
245
+ * @template TData - The type your `mutationFn` resolves to.
246
+ * @template TError - The type of errors your `mutationFn` may throw.
247
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
248
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
249
+ */
167
250
  export interface MutationOptions<
168
251
  TData = unknown,
169
252
  TError = DefaultError,
@@ -174,6 +257,14 @@ export interface MutationOptions<
174
257
  '_defaulted'
175
258
  > {}
176
259
 
260
+ /**
261
+ * The accessor `useMutation` expects as its first argument — Solid re-evaluates it reactively, so callbacks
262
+ * and other options can depend on signals.
263
+ * @template TData - The type your `mutationFn` resolves to.
264
+ * @template TError - The type of errors your `mutationFn` may throw.
265
+ * @template TVariables - The type of the variables your `mutationFn` accepts.
266
+ * @template TOnMutateResult - The type returned by `onMutate`, passed on to `onSuccess`/`onError`/`onSettled`.
267
+ */
177
268
  export type UseMutationOptions<
178
269
  TData = unknown,
179
270
  TError = DefaultError,
@@ -190,13 +281,26 @@ export type UseMutationOptions<
190
281
  */
191
282
  export type UseMutateFunction<
192
283
  TData = unknown,
193
- // eslint-disable-next-line @typescript-eslint/naming-convention
284
+ // oxlint-disable-next-line tanstack-query/type-parameter-naming
194
285
  _TError = DefaultError,
195
286
  TVariables = void,
196
- // eslint-disable-next-line @typescript-eslint/naming-convention
287
+ // oxlint-disable-next-line tanstack-query/type-parameter-naming
197
288
  _TOnMutateResult = unknown,
198
- > = (variables: TVariables) => Promise<TData>
289
+ > = (
290
+ ...args: undefined extends TVariables
291
+ ? [variables?: TVariables]
292
+ : [variables: TVariables]
293
+ ) => Promise<TData>
199
294
 
295
+ /**
296
+ * The result of `useMutation`. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with
297
+ * `mutate` replaced by the promise-returning {@link UseMutateFunction}.
298
+ * @template TData - The type your `mutationFn` resolves to.
299
+ * @template TError - The type of errors your `mutationFn` may throw.
300
+ * @template TVariables - The type of the variable passed to `mutate`.
301
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
302
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
303
+ */
200
304
  export type UseBaseMutationResult<
201
305
  TData = unknown,
202
306
  TError = DefaultError,
@@ -210,6 +314,14 @@ export type UseBaseMutationResult<
210
314
  { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
211
315
  >
212
316
 
317
+ /**
318
+ * The result of `useMutation`. Same as {@link UseBaseMutationResult}.
319
+ * @template TData - The type your `mutationFn` resolves to.
320
+ * @template TError - The type of errors your `mutationFn` may throw.
321
+ * @template TVariables - The type of the variable passed to `mutate`.
322
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
323
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
324
+ */
213
325
  export type UseMutationResult<
214
326
  TData = unknown,
215
327
  TError = DefaultError,