@tanstack/vue-query 5.102.8 → 5.103.0

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.
Files changed (329) hide show
  1. package/build/legacy/devtools/devtools.d.cts +1 -1
  2. package/build/legacy/devtools/devtools.d.ts +1 -1
  3. package/build/legacy/index.d.cts +8 -6
  4. package/build/legacy/index.d.ts +8 -6
  5. package/build/legacy/infiniteQueryOptions-CEDiLwh5.d.ts +365 -0
  6. package/build/legacy/infiniteQueryOptions-CEDiLwh5.d.ts.map +1 -0
  7. package/build/legacy/infiniteQueryOptions-qN6sOJM-.d.cts +365 -0
  8. package/build/legacy/infiniteQueryOptions-qN6sOJM-.d.cts.map +1 -0
  9. package/build/legacy/infiniteQueryOptions.cjs.map +1 -1
  10. package/build/legacy/infiniteQueryOptions.d.cts +1 -1
  11. package/build/legacy/infiniteQueryOptions.d.ts +1 -1
  12. package/build/legacy/infiniteQueryOptions.js.map +1 -1
  13. package/build/legacy/mutationCache.cjs +5 -0
  14. package/build/legacy/mutationCache.cjs.map +1 -1
  15. package/build/legacy/mutationCache.d.cts +6 -1
  16. package/build/legacy/mutationCache.d.cts.map +1 -1
  17. package/build/legacy/mutationCache.d.ts +6 -1
  18. package/build/legacy/mutationCache.d.ts.map +1 -1
  19. package/build/legacy/mutationCache.js +5 -0
  20. package/build/legacy/mutationCache.js.map +1 -1
  21. package/build/legacy/mutationOptions.cjs.map +1 -1
  22. package/build/legacy/mutationOptions.d.cts +121 -1
  23. package/build/legacy/mutationOptions.d.cts.map +1 -1
  24. package/build/legacy/mutationOptions.d.ts +121 -1
  25. package/build/legacy/mutationOptions.d.ts.map +1 -1
  26. package/build/legacy/mutationOptions.js.map +1 -1
  27. package/build/legacy/queryCache.cjs +5 -0
  28. package/build/legacy/queryCache.cjs.map +1 -1
  29. package/build/legacy/queryCache.d.cts +6 -1
  30. package/build/legacy/queryCache.d.cts.map +1 -1
  31. package/build/legacy/queryCache.d.ts +6 -1
  32. package/build/legacy/queryCache.d.ts.map +1 -1
  33. package/build/legacy/queryCache.js +5 -0
  34. package/build/legacy/queryCache.js.map +1 -1
  35. package/build/legacy/queryClient-CZeNAt68.d.cts +71 -0
  36. package/build/legacy/queryClient-CZeNAt68.d.cts.map +1 -0
  37. package/build/legacy/queryClient-Cv73nzNT.d.ts +71 -0
  38. package/build/legacy/queryClient-Cv73nzNT.d.ts.map +1 -0
  39. package/build/legacy/queryClient.cjs +7 -0
  40. package/build/legacy/queryClient.cjs.map +1 -1
  41. package/build/legacy/queryClient.d.cts +1 -1
  42. package/build/legacy/queryClient.d.ts +1 -1
  43. package/build/legacy/queryClient.js +7 -0
  44. package/build/legacy/queryClient.js.map +1 -1
  45. package/build/legacy/queryOptions-DPDwdVBu.d.ts +227 -0
  46. package/build/legacy/queryOptions-DPDwdVBu.d.ts.map +1 -0
  47. package/build/legacy/queryOptions-rkZ3sk6g.d.cts +227 -0
  48. package/build/legacy/queryOptions-rkZ3sk6g.d.cts.map +1 -0
  49. package/build/legacy/queryOptions.cjs.map +1 -1
  50. package/build/legacy/queryOptions.d.cts +2 -19
  51. package/build/legacy/queryOptions.d.ts +2 -19
  52. package/build/legacy/queryOptions.js.map +1 -1
  53. package/build/{modern/types-BzZi3_rS.d.cts → legacy/types-JpJB72CS.d.cts} +19 -1
  54. package/build/legacy/types-JpJB72CS.d.cts.map +1 -0
  55. package/build/legacy/{types-BzZi3_rS.d.cts → types-JpJB72CS.d.ts} +19 -1
  56. package/build/legacy/types-JpJB72CS.d.ts.map +1 -0
  57. package/build/legacy/types.d.cts +1 -1
  58. package/build/legacy/types.d.ts +1 -1
  59. package/build/legacy/useBaseQuery.cjs +8 -0
  60. package/build/legacy/useBaseQuery.cjs.map +1 -1
  61. package/build/legacy/useBaseQuery.d.cts +1 -1
  62. package/build/legacy/useBaseQuery.d.ts +1 -1
  63. package/build/legacy/useBaseQuery.js +8 -0
  64. package/build/legacy/useBaseQuery.js.map +1 -1
  65. package/build/legacy/useInfiniteQuery.cjs.map +1 -1
  66. package/build/legacy/useInfiniteQuery.d.cts +1 -1
  67. package/build/legacy/useInfiniteQuery.d.ts +1 -1
  68. package/build/legacy/useInfiniteQuery.js.map +1 -1
  69. package/build/legacy/useIsFetching.cjs +41 -0
  70. package/build/legacy/useIsFetching.cjs.map +1 -1
  71. package/build/legacy/useIsFetching.d.cts +47 -6
  72. package/build/legacy/useIsFetching.d.cts.map +1 -1
  73. package/build/legacy/useIsFetching.d.ts +47 -6
  74. package/build/legacy/useIsFetching.d.ts.map +1 -1
  75. package/build/legacy/useIsFetching.js +41 -0
  76. package/build/legacy/useIsFetching.js.map +1 -1
  77. package/build/legacy/useMutation.cjs +170 -9
  78. package/build/legacy/useMutation.cjs.map +1 -1
  79. package/build/legacy/useMutation.d.cts +164 -3
  80. package/build/legacy/useMutation.d.cts.map +1 -1
  81. package/build/legacy/useMutation.d.ts +164 -3
  82. package/build/legacy/useMutation.d.ts.map +1 -1
  83. package/build/legacy/useMutation.js +170 -9
  84. package/build/legacy/useMutation.js.map +1 -1
  85. package/build/legacy/useMutationState.cjs +103 -0
  86. package/build/legacy/useMutationState.cjs.map +1 -1
  87. package/build/legacy/useMutationState.d.cts +111 -7
  88. package/build/legacy/useMutationState.d.cts.map +1 -1
  89. package/build/legacy/useMutationState.d.ts +111 -7
  90. package/build/legacy/useMutationState.d.ts.map +1 -1
  91. package/build/legacy/useMutationState.js +103 -0
  92. package/build/legacy/useMutationState.js.map +1 -1
  93. package/build/legacy/usePrefetchInfiniteQuery.cjs +46 -0
  94. package/build/legacy/usePrefetchInfiniteQuery.cjs.map +1 -1
  95. package/build/legacy/usePrefetchInfiniteQuery.d.cts +48 -2
  96. package/build/legacy/usePrefetchInfiniteQuery.d.cts.map +1 -1
  97. package/build/legacy/usePrefetchInfiniteQuery.d.ts +48 -2
  98. package/build/legacy/usePrefetchInfiniteQuery.d.ts.map +1 -1
  99. package/build/legacy/usePrefetchInfiniteQuery.js +46 -0
  100. package/build/legacy/usePrefetchInfiniteQuery.js.map +1 -1
  101. package/build/legacy/usePrefetchQuery.cjs +37 -0
  102. package/build/legacy/usePrefetchQuery.cjs.map +1 -1
  103. package/build/legacy/usePrefetchQuery.d.cts +39 -2
  104. package/build/legacy/usePrefetchQuery.d.cts.map +1 -1
  105. package/build/legacy/usePrefetchQuery.d.ts +39 -2
  106. package/build/legacy/usePrefetchQuery.d.ts.map +1 -1
  107. package/build/legacy/usePrefetchQuery.js +37 -0
  108. package/build/legacy/usePrefetchQuery.js.map +1 -1
  109. package/build/legacy/useQueries.cjs +123 -0
  110. package/build/legacy/useQueries.cjs.map +1 -1
  111. package/build/legacy/useQueries.d.cts +126 -2
  112. package/build/legacy/useQueries.d.cts.map +1 -1
  113. package/build/legacy/useQueries.d.ts +126 -2
  114. package/build/legacy/useQueries.d.ts.map +1 -1
  115. package/build/legacy/useQueries.js +123 -0
  116. package/build/legacy/useQueries.js.map +1 -1
  117. package/build/legacy/useQuery.cjs.map +1 -1
  118. package/build/legacy/useQuery.d.cts +248 -2
  119. package/build/legacy/useQuery.d.cts.map +1 -0
  120. package/build/legacy/useQuery.d.ts +248 -2
  121. package/build/legacy/useQuery.d.ts.map +1 -0
  122. package/build/legacy/useQuery.js.map +1 -1
  123. package/build/legacy/useQueryClient.cjs +21 -0
  124. package/build/legacy/useQueryClient.cjs.map +1 -1
  125. package/build/legacy/useQueryClient.d.cts +22 -1
  126. package/build/legacy/useQueryClient.d.cts.map +1 -1
  127. package/build/legacy/useQueryClient.d.ts +22 -1
  128. package/build/legacy/useQueryClient.d.ts.map +1 -1
  129. package/build/legacy/useQueryClient.js +21 -0
  130. package/build/legacy/useQueryClient.js.map +1 -1
  131. package/build/legacy/utils.cjs +15 -0
  132. package/build/legacy/utils.cjs.map +1 -1
  133. package/build/legacy/utils.d.cts +16 -1
  134. package/build/legacy/utils.d.cts.map +1 -1
  135. package/build/legacy/utils.d.ts +16 -1
  136. package/build/legacy/utils.d.ts.map +1 -1
  137. package/build/legacy/utils.js +15 -0
  138. package/build/legacy/utils.js.map +1 -1
  139. package/build/legacy/vueQueryPlugin.cjs +34 -0
  140. package/build/legacy/vueQueryPlugin.cjs.map +1 -1
  141. package/build/legacy/vueQueryPlugin.d.cts +48 -2
  142. package/build/legacy/vueQueryPlugin.d.cts.map +1 -1
  143. package/build/legacy/vueQueryPlugin.d.ts +48 -2
  144. package/build/legacy/vueQueryPlugin.d.ts.map +1 -1
  145. package/build/legacy/vueQueryPlugin.js +34 -0
  146. package/build/legacy/vueQueryPlugin.js.map +1 -1
  147. package/build/modern/devtools/devtools.d.cts +1 -1
  148. package/build/modern/devtools/devtools.d.ts +1 -1
  149. package/build/modern/index.d.cts +8 -6
  150. package/build/modern/index.d.ts +8 -6
  151. package/build/modern/infiniteQueryOptions-CEDiLwh5.d.ts +365 -0
  152. package/build/modern/infiniteQueryOptions-CEDiLwh5.d.ts.map +1 -0
  153. package/build/modern/infiniteQueryOptions-qN6sOJM-.d.cts +365 -0
  154. package/build/modern/infiniteQueryOptions-qN6sOJM-.d.cts.map +1 -0
  155. package/build/modern/infiniteQueryOptions.cjs.map +1 -1
  156. package/build/modern/infiniteQueryOptions.d.cts +1 -1
  157. package/build/modern/infiniteQueryOptions.d.ts +1 -1
  158. package/build/modern/infiniteQueryOptions.js.map +1 -1
  159. package/build/modern/mutationCache.cjs +5 -0
  160. package/build/modern/mutationCache.cjs.map +1 -1
  161. package/build/modern/mutationCache.d.cts +6 -1
  162. package/build/modern/mutationCache.d.cts.map +1 -1
  163. package/build/modern/mutationCache.d.ts +6 -1
  164. package/build/modern/mutationCache.d.ts.map +1 -1
  165. package/build/modern/mutationCache.js +5 -0
  166. package/build/modern/mutationCache.js.map +1 -1
  167. package/build/modern/mutationOptions.cjs.map +1 -1
  168. package/build/modern/mutationOptions.d.cts +121 -1
  169. package/build/modern/mutationOptions.d.cts.map +1 -1
  170. package/build/modern/mutationOptions.d.ts +121 -1
  171. package/build/modern/mutationOptions.d.ts.map +1 -1
  172. package/build/modern/mutationOptions.js.map +1 -1
  173. package/build/modern/queryCache.cjs +5 -0
  174. package/build/modern/queryCache.cjs.map +1 -1
  175. package/build/modern/queryCache.d.cts +6 -1
  176. package/build/modern/queryCache.d.cts.map +1 -1
  177. package/build/modern/queryCache.d.ts +6 -1
  178. package/build/modern/queryCache.d.ts.map +1 -1
  179. package/build/modern/queryCache.js +5 -0
  180. package/build/modern/queryCache.js.map +1 -1
  181. package/build/modern/queryClient-CZeNAt68.d.cts +71 -0
  182. package/build/modern/queryClient-CZeNAt68.d.cts.map +1 -0
  183. package/build/modern/queryClient-Cv73nzNT.d.ts +71 -0
  184. package/build/modern/queryClient-Cv73nzNT.d.ts.map +1 -0
  185. package/build/modern/queryClient.cjs +7 -0
  186. package/build/modern/queryClient.cjs.map +1 -1
  187. package/build/modern/queryClient.d.cts +1 -1
  188. package/build/modern/queryClient.d.ts +1 -1
  189. package/build/modern/queryClient.js +7 -0
  190. package/build/modern/queryClient.js.map +1 -1
  191. package/build/modern/queryOptions-DPDwdVBu.d.ts +227 -0
  192. package/build/modern/queryOptions-DPDwdVBu.d.ts.map +1 -0
  193. package/build/modern/queryOptions-rkZ3sk6g.d.cts +227 -0
  194. package/build/modern/queryOptions-rkZ3sk6g.d.cts.map +1 -0
  195. package/build/modern/queryOptions.cjs.map +1 -1
  196. package/build/modern/queryOptions.d.cts +2 -19
  197. package/build/modern/queryOptions.d.ts +2 -19
  198. package/build/modern/queryOptions.js.map +1 -1
  199. package/build/modern/{types-BzZi3_rS.d.ts → types-JpJB72CS.d.cts} +19 -1
  200. package/build/modern/types-JpJB72CS.d.cts.map +1 -0
  201. package/build/{legacy/types-BzZi3_rS.d.ts → modern/types-JpJB72CS.d.ts} +19 -1
  202. package/build/modern/types-JpJB72CS.d.ts.map +1 -0
  203. package/build/modern/types.d.cts +1 -1
  204. package/build/modern/types.d.ts +1 -1
  205. package/build/modern/useBaseQuery.cjs +8 -0
  206. package/build/modern/useBaseQuery.cjs.map +1 -1
  207. package/build/modern/useBaseQuery.d.cts +1 -1
  208. package/build/modern/useBaseQuery.d.ts +1 -1
  209. package/build/modern/useBaseQuery.js +8 -0
  210. package/build/modern/useBaseQuery.js.map +1 -1
  211. package/build/modern/useInfiniteQuery.cjs.map +1 -1
  212. package/build/modern/useInfiniteQuery.d.cts +1 -1
  213. package/build/modern/useInfiniteQuery.d.ts +1 -1
  214. package/build/modern/useInfiniteQuery.js.map +1 -1
  215. package/build/modern/useIsFetching.cjs +41 -0
  216. package/build/modern/useIsFetching.cjs.map +1 -1
  217. package/build/modern/useIsFetching.d.cts +47 -6
  218. package/build/modern/useIsFetching.d.cts.map +1 -1
  219. package/build/modern/useIsFetching.d.ts +47 -6
  220. package/build/modern/useIsFetching.d.ts.map +1 -1
  221. package/build/modern/useIsFetching.js +41 -0
  222. package/build/modern/useIsFetching.js.map +1 -1
  223. package/build/modern/useMutation.cjs +170 -9
  224. package/build/modern/useMutation.cjs.map +1 -1
  225. package/build/modern/useMutation.d.cts +164 -3
  226. package/build/modern/useMutation.d.cts.map +1 -1
  227. package/build/modern/useMutation.d.ts +164 -3
  228. package/build/modern/useMutation.d.ts.map +1 -1
  229. package/build/modern/useMutation.js +170 -9
  230. package/build/modern/useMutation.js.map +1 -1
  231. package/build/modern/useMutationState.cjs +103 -0
  232. package/build/modern/useMutationState.cjs.map +1 -1
  233. package/build/modern/useMutationState.d.cts +111 -7
  234. package/build/modern/useMutationState.d.cts.map +1 -1
  235. package/build/modern/useMutationState.d.ts +111 -7
  236. package/build/modern/useMutationState.d.ts.map +1 -1
  237. package/build/modern/useMutationState.js +103 -0
  238. package/build/modern/useMutationState.js.map +1 -1
  239. package/build/modern/usePrefetchInfiniteQuery.cjs +46 -0
  240. package/build/modern/usePrefetchInfiniteQuery.cjs.map +1 -1
  241. package/build/modern/usePrefetchInfiniteQuery.d.cts +48 -2
  242. package/build/modern/usePrefetchInfiniteQuery.d.cts.map +1 -1
  243. package/build/modern/usePrefetchInfiniteQuery.d.ts +48 -2
  244. package/build/modern/usePrefetchInfiniteQuery.d.ts.map +1 -1
  245. package/build/modern/usePrefetchInfiniteQuery.js +46 -0
  246. package/build/modern/usePrefetchInfiniteQuery.js.map +1 -1
  247. package/build/modern/usePrefetchQuery.cjs +37 -0
  248. package/build/modern/usePrefetchQuery.cjs.map +1 -1
  249. package/build/modern/usePrefetchQuery.d.cts +39 -2
  250. package/build/modern/usePrefetchQuery.d.cts.map +1 -1
  251. package/build/modern/usePrefetchQuery.d.ts +39 -2
  252. package/build/modern/usePrefetchQuery.d.ts.map +1 -1
  253. package/build/modern/usePrefetchQuery.js +37 -0
  254. package/build/modern/usePrefetchQuery.js.map +1 -1
  255. package/build/modern/useQueries.cjs +123 -0
  256. package/build/modern/useQueries.cjs.map +1 -1
  257. package/build/modern/useQueries.d.cts +126 -2
  258. package/build/modern/useQueries.d.cts.map +1 -1
  259. package/build/modern/useQueries.d.ts +126 -2
  260. package/build/modern/useQueries.d.ts.map +1 -1
  261. package/build/modern/useQueries.js +123 -0
  262. package/build/modern/useQueries.js.map +1 -1
  263. package/build/modern/useQuery.cjs.map +1 -1
  264. package/build/modern/useQuery.d.cts +248 -2
  265. package/build/modern/useQuery.d.cts.map +1 -0
  266. package/build/modern/useQuery.d.ts +248 -2
  267. package/build/modern/useQuery.d.ts.map +1 -0
  268. package/build/modern/useQuery.js.map +1 -1
  269. package/build/modern/useQueryClient.cjs +21 -0
  270. package/build/modern/useQueryClient.cjs.map +1 -1
  271. package/build/modern/useQueryClient.d.cts +22 -1
  272. package/build/modern/useQueryClient.d.cts.map +1 -1
  273. package/build/modern/useQueryClient.d.ts +22 -1
  274. package/build/modern/useQueryClient.d.ts.map +1 -1
  275. package/build/modern/useQueryClient.js +21 -0
  276. package/build/modern/useQueryClient.js.map +1 -1
  277. package/build/modern/utils.cjs +15 -0
  278. package/build/modern/utils.cjs.map +1 -1
  279. package/build/modern/utils.d.cts +16 -1
  280. package/build/modern/utils.d.cts.map +1 -1
  281. package/build/modern/utils.d.ts +16 -1
  282. package/build/modern/utils.d.ts.map +1 -1
  283. package/build/modern/utils.js +15 -0
  284. package/build/modern/utils.js.map +1 -1
  285. package/build/modern/vueQueryPlugin.cjs +34 -0
  286. package/build/modern/vueQueryPlugin.cjs.map +1 -1
  287. package/build/modern/vueQueryPlugin.d.cts +48 -2
  288. package/build/modern/vueQueryPlugin.d.cts.map +1 -1
  289. package/build/modern/vueQueryPlugin.d.ts +48 -2
  290. package/build/modern/vueQueryPlugin.d.ts.map +1 -1
  291. package/build/modern/vueQueryPlugin.js +34 -0
  292. package/build/modern/vueQueryPlugin.js.map +1 -1
  293. package/package.json +10 -10
  294. package/src/index.ts +9 -9
  295. package/src/infiniteQueryOptions.ts +86 -0
  296. package/src/mutationCache.ts +5 -0
  297. package/src/mutationOptions.ts +123 -0
  298. package/src/queryCache.ts +5 -0
  299. package/src/queryClient.ts +17 -1
  300. package/src/queryOptions.ts +276 -10
  301. package/src/types.ts +18 -0
  302. package/src/useBaseQuery.ts +9 -1
  303. package/src/useInfiniteQuery.ts +240 -0
  304. package/src/useIsFetching.ts +46 -3
  305. package/src/useMutation.ts +170 -17
  306. package/src/useMutationState.ts +111 -4
  307. package/src/usePrefetchInfiniteQuery.ts +46 -0
  308. package/src/usePrefetchQuery.ts +37 -0
  309. package/src/useQueries.ts +124 -1
  310. package/src/useQuery.ts +240 -79
  311. package/src/useQueryClient.ts +21 -0
  312. package/src/utils.ts +15 -0
  313. package/src/vueQueryPlugin.ts +46 -0
  314. package/build/legacy/queryClient-C07d0chJ.d.cts +0 -97
  315. package/build/legacy/queryClient-C07d0chJ.d.cts.map +0 -1
  316. package/build/legacy/queryClient-hf6i_vCa.d.ts +0 -97
  317. package/build/legacy/queryClient-hf6i_vCa.d.ts.map +0 -1
  318. package/build/legacy/queryOptions.d.cts.map +0 -1
  319. package/build/legacy/queryOptions.d.ts.map +0 -1
  320. package/build/legacy/types-BzZi3_rS.d.cts.map +0 -1
  321. package/build/legacy/types-BzZi3_rS.d.ts.map +0 -1
  322. package/build/modern/queryClient-C07d0chJ.d.cts +0 -97
  323. package/build/modern/queryClient-C07d0chJ.d.cts.map +0 -1
  324. package/build/modern/queryClient-hf6i_vCa.d.ts +0 -97
  325. package/build/modern/queryClient-hf6i_vCa.d.ts.map +0 -1
  326. package/build/modern/queryOptions.d.cts.map +0 -1
  327. package/build/modern/queryOptions.d.ts.map +0 -1
  328. package/build/modern/types-BzZi3_rS.d.cts.map +0 -1
  329. package/build/modern/types-BzZi3_rS.d.ts.map +0 -1
@@ -1,4 +1,10 @@
1
- import type { DeepUnwrapRef, MaybeRefOrGetter, ShallowOption } from './types'
1
+ import type {
2
+ DeepUnwrapRef,
3
+ MaybeRef,
4
+ MaybeRefDeep,
5
+ MaybeRefOrGetter,
6
+ ShallowOption,
7
+ } from './types'
2
8
  import type {
3
9
  DefaultError,
4
10
  InitialDataFunction,
@@ -9,6 +15,18 @@ import type {
9
15
  QueryObserverOptions,
10
16
  } from '@tanstack/query-core'
11
17
 
18
+ /**
19
+ * The plain, unwrapped options that `queryOptions` hands back, and what `useQuery`, `useQueries`, and the
20
+ * `queryClient` methods see once `ref`s have been resolved. To pass options in, use
21
+ * {@link UseQueryOptions}, which accepts the same options as `ref`s and `computed`s too.
22
+ *
23
+ * @template TQueryFnData - The type your `queryFn` resolves to.
24
+ * @template TError - The type of errors your `queryFn` may throw.
25
+ * @template TData - The type `data` ends up as after `select` runs.
26
+ * @template TQueryData - The type of data stored in the cache, before `select` runs. Defaults to
27
+ * `TQueryFnData` and can be configured independently of it.
28
+ * @template TQueryKey - The type of your `queryKey`.
29
+ */
12
30
  export type QueryOptions<
13
31
  TQueryFnData = unknown,
14
32
  TError = DefaultError,
@@ -42,35 +60,147 @@ export type QueryOptions<
42
60
  >[Property]
43
61
  } & ShallowOption
44
62
 
45
- export type UndefinedInitialQueryOptions<
63
+ // Widen the type of the symbol to enable type inference even if skipToken is not immutable.
64
+ type SkipTokenForUseQuery = symbol
65
+
66
+ /**
67
+ * The options accepted by `queryOptions`, `useQuery`, and the other query hooks. `enabled` tracks reactive
68
+ * dependencies automatically as a `ref`, a plain value, or a reactive getter (`() => ...`). `queryKey` reacts
69
+ * through a `ref` or a reactive getter for the array itself, or `ref`s and reactive getters as individual
70
+ * entries. Other options are read once when passed as a plain value, and stay reactive when passed as a `ref`
71
+ * or a `computed`. Only `enabled` and `queryKey` read a function as a getter, so `queryFn` reacts through a
72
+ * `computed`: a function there is the query function itself.
73
+ *
74
+ * If you instead pass a getter for the whole options object (`useQuery(() => ({ ... }))`), every option
75
+ * inside it — including `staleTime`, `retry`, and `select` — is re-evaluated whenever the getter's own
76
+ * reactive dependencies change, since the entire object is recomputed.
77
+ *
78
+ * `select` only re-runs when `data` changes, or when the `select` function's own reference changes. Since a
79
+ * Vue `setup()` function runs only once per component instance, an inline `select` function passed directly
80
+ * to `queryOptions`/`useQuery` already has a stable reference across reactive updates. An inline `select`
81
+ * created inside a whole-options getter is recreated — and so can change reference — every time that getter
82
+ * re-evaluates.
83
+ *
84
+ * @template TQueryFnData - The type your `queryFn` resolves to.
85
+ * @template TError - The type of errors your `queryFn` may throw.
86
+ * @template TData - The type `data` ends up as after `select` runs.
87
+ * @template TQueryData - The type of data stored in the cache, before `select` runs. Defaults to
88
+ * `TQueryFnData` and can be configured independently of it.
89
+ * @template TQueryKey - The type of your `queryKey`.
90
+ */
91
+ export type UseQueryOptions<
46
92
  TQueryFnData = unknown,
47
93
  TError = DefaultError,
48
94
  TData = TQueryFnData,
95
+ TQueryData = TQueryFnData,
49
96
  TQueryKey extends QueryKey = QueryKey,
50
- > = QueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> & {
97
+ > = MaybeRef<
98
+ {
99
+ [Property in keyof QueryObserverOptions<
100
+ TQueryFnData,
101
+ TError,
102
+ TData,
103
+ TQueryData,
104
+ TQueryKey
105
+ >]: Property extends 'enabled' | 'queryKey'
106
+ ? QueryOptions<
107
+ TQueryFnData,
108
+ TError,
109
+ TData,
110
+ TQueryData,
111
+ TQueryKey
112
+ >[Property]
113
+ : Property extends 'queryFn'
114
+ ? MaybeRefDeep<
115
+ | QueryOptions<
116
+ TQueryFnData,
117
+ TError,
118
+ TData,
119
+ TQueryData,
120
+ TQueryKey
121
+ >[Property]
122
+ | SkipTokenForUseQuery
123
+ >
124
+ : MaybeRefDeep<
125
+ QueryOptions<
126
+ TQueryFnData,
127
+ TError,
128
+ TData,
129
+ TQueryData,
130
+ TQueryKey
131
+ >[Property]
132
+ >
133
+ } & ShallowOption
134
+ >
135
+
136
+ type WithUndefinedInitialData<TQueryFnData> = {
137
+ /**
138
+ * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
139
+ * created or cached yet). If set to a function, the function will be called **once** during the shared/root
140
+ * query initialization, and be expected to synchronously return the initial data. Initial data is
141
+ * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
142
+ * cache. Unlike `queryKey`/`enabled`, this is not reactive — it isn't re-evaluated on `ref` changes.
143
+ */
51
144
  initialData?:
52
145
  | undefined
53
146
  | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
54
147
  | NonUndefinedGuard<TQueryFnData>
55
148
  }
56
149
 
150
+ type WithDefinedInitialData<TQueryFnData> = {
151
+ /**
152
+ * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
153
+ * created or cached yet). If set to a function, the function will be called **once** during the shared/root
154
+ * query initialization, and be expected to synchronously return the initial data. Initial data is
155
+ * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
156
+ * cache. Unlike `queryKey`/`enabled`, this is not reactive — it isn't re-evaluated on `ref` changes.
157
+ */
158
+ initialData:
159
+ | NonUndefinedGuard<TQueryFnData>
160
+ | (() => NonUndefinedGuard<TQueryFnData>)
161
+ }
162
+
163
+ /**
164
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
165
+ * `undefined` while the query is `pending`.
166
+ *
167
+ * @template TQueryFnData - The type your `queryFn` resolves to.
168
+ * @template TError - The type of errors your `queryFn` may throw.
169
+ * @template TData - The type `data` ends up as after `select` runs.
170
+ * @template TQueryKey - The type of your `queryKey`.
171
+ */
172
+ export type UndefinedInitialQueryOptions<
173
+ TQueryFnData = unknown,
174
+ TError = DefaultError,
175
+ TData = TQueryFnData,
176
+ TQueryKey extends QueryKey = QueryKey,
177
+ > = UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> &
178
+ WithUndefinedInitialData<TQueryFnData>
179
+
180
+ /**
181
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
182
+ * `undefined`.
183
+ *
184
+ * @template TQueryFnData - The type your `queryFn` resolves to.
185
+ * @template TError - The type of errors your `queryFn` may throw.
186
+ * @template TData - The type `data` ends up as after `select` runs.
187
+ * @template TQueryKey - The type of your `queryKey`.
188
+ */
57
189
  export type DefinedInitialQueryOptions<
58
190
  TQueryFnData = unknown,
59
191
  TError = DefaultError,
60
192
  TData = TQueryFnData,
61
193
  TQueryKey extends QueryKey = QueryKey,
62
- > = QueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> & {
63
- initialData:
64
- | NonUndefinedGuard<TQueryFnData>
65
- | (() => NonUndefinedGuard<TQueryFnData>)
66
- }
194
+ > = UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> &
195
+ WithDefinedInitialData<TQueryFnData>
67
196
 
68
197
  export type UndefinedInitialQueryOptionsWithDataTag<
69
198
  TQueryFnData = unknown,
70
199
  TError = DefaultError,
71
200
  TData = TQueryFnData,
72
201
  TQueryKey extends QueryKey = QueryKey,
73
- > = UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey> &
202
+ > = QueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> &
203
+ WithUndefinedInitialData<TQueryFnData> &
74
204
  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
75
205
 
76
206
  export type DefinedInitialQueryOptionsWithDataTag<
@@ -78,9 +208,39 @@ export type DefinedInitialQueryOptionsWithDataTag<
78
208
  TError = DefaultError,
79
209
  TData = TQueryFnData,
80
210
  TQueryKey extends QueryKey = QueryKey,
81
- > = DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey> &
211
+ > = QueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey> &
212
+ WithDefinedInitialData<TQueryFnData> &
82
213
  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>
83
214
 
215
+ /**
216
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
217
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
218
+ * is the query key to generate options for.
219
+ *
220
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
221
+ *
222
+ * @see {@link useQuery} to run a query with these options.
223
+ * @param options - The {@link DefinedInitialQueryOptions} to use — everything you can pass to `useQuery`, with
224
+ * `initialData` set.
225
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
226
+ *
227
+ * @example
228
+ * ```vue
229
+ * <script setup lang="ts">
230
+ * import { queryOptions, useQuery } from '@tanstack/vue-query'
231
+ *
232
+ * const postsOptions = queryOptions({
233
+ * queryKey: ['posts'],
234
+ * queryFn: fetchPosts,
235
+ * initialData: [],
236
+ * })
237
+ *
238
+ * // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
239
+ * // so the list stays visible alongside the error.
240
+ * const { data, isError, error } = useQuery(postsOptions)
241
+ * </script>
242
+ * ```
243
+ */
84
244
  export function queryOptions<
85
245
  TQueryFnData = unknown,
86
246
  TError = DefaultError,
@@ -90,6 +250,34 @@ export function queryOptions<
90
250
  options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
91
251
  ): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>
92
252
 
253
+ /**
254
+ * Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the
255
+ * function body). Wrap them in a getter so `queryClient` methods like `invalidateQueries`/`fetchQuery` always
256
+ * read the current values instead of the ones captured when the options were created.
257
+ *
258
+ * @see {@link useQuery} to run a query with these options.
259
+ * @param options - A function returning the {@link DefinedInitialQueryOptions} to use, re-evaluated on demand.
260
+ * @returns A function that returns the same options object, typed so that `queryKey` carries the inferred data
261
+ * type.
262
+ *
263
+ * @example
264
+ * ```vue
265
+ * <script setup lang="ts">
266
+ * import { ref } from 'vue'
267
+ * import { queryOptions, useQuery } from '@tanstack/vue-query'
268
+ *
269
+ * const postId = ref(1)
270
+ * const postOptions = queryOptions(() => ({
271
+ * queryKey: ['post', postId.value],
272
+ * queryFn: () => fetchPost(postId.value),
273
+ * initialData: { id: postId.value, title: '' },
274
+ * }))
275
+ *
276
+ * // Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.
277
+ * const { data } = useQuery(postOptions)
278
+ * </script>
279
+ * ```
280
+ */
93
281
  export function queryOptions<
94
282
  TQueryFnData = unknown,
95
283
  TError = DefaultError,
@@ -109,6 +297,32 @@ export function queryOptions<
109
297
  TQueryKey
110
298
  >
111
299
 
300
+ /**
301
+ * You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can
302
+ * be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and
303
+ * is the query key to generate options for.
304
+ *
305
+ * @see {@link useQuery} to run a query with these options.
306
+ * @param options - The {@link UndefinedInitialQueryOptions} to use — everything you can pass to `useQuery`.
307
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
308
+ *
309
+ * @example
310
+ * A parameterized factory, so the same options object can be reused per `id`:
311
+ * ```vue
312
+ * <script setup lang="ts">
313
+ * import { queryOptions, useQuery } from '@tanstack/vue-query'
314
+ *
315
+ * function postOptions(id: string) {
316
+ * return queryOptions({
317
+ * queryKey: ['post', id],
318
+ * queryFn: () => fetchPost(id),
319
+ * })
320
+ * }
321
+ *
322
+ * const { data, isPending, isError, error } = useQuery(postOptions('1'))
323
+ * </script>
324
+ * ```
325
+ */
112
326
  export function queryOptions<
113
327
  TQueryFnData = unknown,
114
328
  TError = DefaultError,
@@ -123,6 +337,58 @@ export function queryOptions<
123
337
  TQueryKey
124
338
  >
125
339
 
340
+ /**
341
+ * Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the
342
+ * function body). Wrap them in a getter so the `queryKey` — and anything else derived from a `ref` — reacts
343
+ * to changes, and so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current
344
+ * values instead of the ones captured when the options were created.
345
+ *
346
+ * @see {@link useQuery} to run a query with these options.
347
+ * @param options - A function returning the {@link UndefinedInitialQueryOptions} to use, re-evaluated on
348
+ * demand.
349
+ * @returns A function that returns the same options object, typed so that `queryKey` carries the inferred
350
+ * data type.
351
+ *
352
+ * @example
353
+ * ```vue
354
+ * <script setup lang="ts">
355
+ * import { ref } from 'vue'
356
+ * import { queryOptions, useQuery, useQueryClient } from '@tanstack/vue-query'
357
+ *
358
+ * const postId = ref(1)
359
+ * const postOptions = queryOptions(() => ({
360
+ * queryKey: ['post', postId.value],
361
+ * queryFn: () => fetchPost(postId.value),
362
+ * }))
363
+ *
364
+ * // Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.
365
+ * const { data } = useQuery(postOptions)
366
+ * const queryClient = useQueryClient()
367
+ * // Here, call `postOptions()` so `invalidateQueries` reads the current `queryKey` right away.
368
+ * queryClient.invalidateQueries(postOptions())
369
+ * </script>
370
+ * ```
371
+ *
372
+ * @example
373
+ * A parameterized factory that disables the query, type safe, until `postId` is set. The whole-options getter
374
+ * re-evaluates `queryFn` on every change to `postId`. `queryFn` can also be a `computed`, but never a bare
375
+ * getter, since a function there is the query function itself:
376
+ * ```vue
377
+ * <script setup lang="ts">
378
+ * import { queryOptions, skipToken, useQuery } from '@tanstack/vue-query'
379
+ *
380
+ * function postOptions(postId: number | undefined) {
381
+ * return queryOptions(() => ({
382
+ * queryKey: ['post', postId],
383
+ * queryFn: postId != null ? () => fetchPost(postId) : skipToken,
384
+ * }))
385
+ * }
386
+ *
387
+ * const props = defineProps<{ postId: number | undefined }>()
388
+ * const { data, isLoading, isError, error } = useQuery(postOptions(props.postId))
389
+ * </script>
390
+ * ```
391
+ */
126
392
  export function queryOptions<
127
393
  TQueryFnData = unknown,
128
394
  TError = DefaultError,
package/src/types.ts CHANGED
@@ -22,12 +22,27 @@ type UnwrapLeaf =
22
22
  | Set<any>
23
23
  | WeakSet<any>
24
24
 
25
+ /** A plain value or a reactive getter (`() => T`) that returns one. */
25
26
  export type MaybeGetter<T> = T | (() => T)
26
27
 
28
+ /**
29
+ * A plain value, a `Ref`, or a `ComputedRef`. Accepting this instead of a bare `T` lets a composable take
30
+ * either a reactive or a static value for a given option — see the [Reactivity guide](../../reactivity.md).
31
+ */
27
32
  export type MaybeRef<T> = Ref<T> | ComputedRef<T> | T
28
33
 
34
+ /**
35
+ * A {@link MaybeRef}, or a reactive getter (`() => T`). Reactive getters are a lighter-weight alternative to
36
+ * `computed` for deriving a value from other reactive state — see the
37
+ * [Reactivity guide](../../reactivity.md#using-derived-state-inside-queries).
38
+ */
29
39
  export type MaybeRefOrGetter<T> = MaybeRef<T> | (() => T)
30
40
 
41
+ /**
42
+ * Like {@link MaybeRef}, but applied recursively to every property of `T` — so each field of an options object
43
+ * (for example, an entry inside a `queryKey` array) can independently be a plain value or a `ref`, not just the
44
+ * object as a whole.
45
+ */
31
46
  export type MaybeRefDeep<T> = MaybeRef<
32
47
  T extends Function
33
48
  ? T
@@ -38,8 +53,10 @@ export type MaybeRefDeep<T> = MaybeRef<
38
53
  : T
39
54
  >
40
55
 
56
+ /** @internal Rejects `unknown`, collapsing it to `never` — used to keep generic inference from silently widening. */
41
57
  export type NoUnknown<T> = Equal<unknown, T> extends true ? never : T
42
58
 
59
+ /** @internal Type-level equality check between `TTargetA` and `TTargetB`. */
43
60
  export type Equal<TTargetA, TTargetB> =
44
61
  (<T>() => T extends TTargetA ? 1 : 2) extends <T>() => T extends TTargetB
45
62
  ? 1
@@ -47,6 +64,7 @@ export type Equal<TTargetA, TTargetB> =
47
64
  ? true
48
65
  : false
49
66
 
67
+ /** The inverse of {@link MaybeRefDeep} — recursively unwraps any `Ref`s in `T` back to their plain value types. */
50
68
  export type DeepUnwrapRef<T> = T extends UnwrapLeaf
51
69
  ? T
52
70
  : T extends Ref<infer U>
@@ -20,7 +20,7 @@ import type {
20
20
  QueryObserverResult,
21
21
  } from '@tanstack/query-core'
22
22
  import type { QueryClient } from './queryClient'
23
- import type { UseQueryOptions } from './useQuery'
23
+ import type { UseQueryOptions } from './queryOptions'
24
24
  import type { UseInfiniteQueryOptions } from './useInfiniteQuery'
25
25
  import type { MaybeRefOrGetter } from './types'
26
26
 
@@ -50,6 +50,14 @@ type UseQueryOptionsGeneric<
50
50
  | UseQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
51
51
  | UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
52
52
 
53
+ /**
54
+ * Base implementation shared by `useQuery` and `useInfiniteQuery`.
55
+ *
56
+ * @param Observer - The observer class from query-core (`QueryObserver` or `InfiniteQueryObserver`).
57
+ * @param options - A `ref`, plain value, or reactive getter resolving to the query options.
58
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
59
+ * will be used.
60
+ */
53
61
  export function useBaseQuery<
54
62
  TQueryFnData,
55
63
  TError,
@@ -66,6 +66,54 @@ export type UseInfiniteQueryReturnType<TData, TError> = UseBaseQueryReturnType<
66
66
  InfiniteQueryObserverResult<TData, TError>
67
67
  >
68
68
 
69
+ /**
70
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
71
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
72
+ *
73
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
74
+ *
75
+ * `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
76
+ * (`() => ...`). `queryKey` reacts through a `ref` for the array itself, or `ref`s and reactive getters as
77
+ * individual entries — the array itself can't be a bare getter.
78
+ *
79
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
80
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
81
+ * actions, or add conditions like `hasNextPage && !isFetching`.
82
+ * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to
83
+ * `useInfiniteQuery`, with `initialData` set.
84
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
85
+ * will be used.
86
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
87
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.value.pages` and
88
+ * `data.value.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
89
+ * `InfiniteData<TQueryFnData>` shape.
90
+ *
91
+ * @example
92
+ * ```vue
93
+ * <script setup lang="ts">
94
+ * import { useInfiniteQuery } from '@tanstack/vue-query'
95
+ *
96
+ * // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
97
+ * // list stays visible alongside the error.
98
+ * const { data, isError, error } = useInfiniteQuery({
99
+ * queryKey: ['projects'],
100
+ * queryFn: ({ pageParam }) => fetchProjects(pageParam),
101
+ * initialPageParam: 0,
102
+ * getNextPageParam: (lastPage) => lastPage.nextId,
103
+ * initialData: { pages: [], pageParams: [] },
104
+ * })
105
+ * </script>
106
+ *
107
+ * <template>
108
+ * <span v-if="isError">Error: {{ error.message }}</span>
109
+ * <ul>
110
+ * <template v-for="page in data.pages" :key="page.nextId">
111
+ * <li v-for="project in page.projects" :key="project.id">{{ project.name }}</li>
112
+ * </template>
113
+ * </ul>
114
+ * </template>
115
+ * ```
116
+ */
69
117
  export function useInfiniteQuery<
70
118
  TQueryFnData,
71
119
  TError = DefaultError,
@@ -85,6 +133,121 @@ export function useInfiniteQuery<
85
133
  queryClient?: QueryClient,
86
134
  ): UseInfiniteQueryReturnType<TData, TError>
87
135
 
136
+ /**
137
+ * The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of
138
+ * `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`.
139
+ *
140
+ * `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
141
+ * (`() => ...`). `queryKey` reacts through a `ref` for the array itself, or `ref`s and reactive getters as
142
+ * individual entries — the array itself can't be a bare getter.
143
+ *
144
+ * @remarks Keep in mind that imperative fetch calls, such as `fetchNextPage`, may interfere with the default
145
+ * refetch behavior, resulting in outdated data. Make sure to call these functions only in response to user
146
+ * actions, or add conditions like `hasNextPage && !isFetching`.
147
+ * @param options - The {@link UndefinedInitialDataInfiniteOptions} to use — everything you can pass to
148
+ * `useInfiniteQuery`.
149
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
150
+ * will be used.
151
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
152
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.value.pages` and
153
+ * `data.value.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default
154
+ * `InfiniteData<TQueryFnData>` shape.
155
+ *
156
+ * @example
157
+ * Fetching the next page from a "Load More" button click:
158
+ * ```vue
159
+ * <script setup lang="ts">
160
+ * import { useInfiniteQuery } from '@tanstack/vue-query'
161
+ *
162
+ * const {
163
+ * data,
164
+ * isPending,
165
+ * isError,
166
+ * error,
167
+ * fetchNextPage,
168
+ * hasNextPage,
169
+ * isFetching,
170
+ * isFetchingNextPage,
171
+ * } = useInfiniteQuery({
172
+ * queryKey: ['projects'],
173
+ * queryFn: ({ pageParam }) => fetchProjects(pageParam),
174
+ * initialPageParam: 0,
175
+ * getNextPageParam: (lastPage) => lastPage.nextId,
176
+ * })
177
+ * </script>
178
+ *
179
+ * <template>
180
+ * <span v-if="isPending">Loading...</span>
181
+ * <span v-else-if="isError">Error: {{ error.message }}</span>
182
+ * <template v-else>
183
+ * <ul>
184
+ * <template v-for="page in data.pages" :key="page.nextId">
185
+ * <li v-for="project in page.projects" :key="project.id">{{ project.name }}</li>
186
+ * </template>
187
+ * </ul>
188
+ * <button @click="fetchNextPage()" :disabled="!hasNextPage || isFetching">
189
+ * {{ isFetchingNextPage ? 'Loading more...' : hasNextPage ? 'Load More' : 'Nothing more to load' }}
190
+ * </button>
191
+ * </template>
192
+ * </template>
193
+ * ```
194
+ *
195
+ * @example
196
+ * Fetching the next page automatically as the user scrolls, using an `IntersectionObserver` on a
197
+ * sentinel element after the list:
198
+ * ```vue
199
+ * <script setup lang="ts">
200
+ * import { onUnmounted, ref, watch } from 'vue'
201
+ * import { useInfiniteQuery } from '@tanstack/vue-query'
202
+ *
203
+ * const {
204
+ * data,
205
+ * isPending,
206
+ * isError,
207
+ * error,
208
+ * fetchNextPage,
209
+ * hasNextPage,
210
+ * isFetching,
211
+ * isFetchingNextPage,
212
+ * } = useInfiniteQuery({
213
+ * queryKey: ['projects'],
214
+ * queryFn: ({ pageParam }) => fetchProjects(pageParam),
215
+ * initialPageParam: 0,
216
+ * getNextPageParam: (lastPage) => lastPage.nextId,
217
+ * })
218
+ *
219
+ * const sentinel = ref<HTMLElement>()
220
+ * let observer: IntersectionObserver | undefined
221
+ *
222
+ * watch(sentinel, (el) => {
223
+ * observer?.disconnect()
224
+ * if (el == null) return
225
+ *
226
+ * observer = new IntersectionObserver(([entry]) => {
227
+ * if (entry?.isIntersecting && hasNextPage.value && !isFetching.value) {
228
+ * fetchNextPage()
229
+ * }
230
+ * })
231
+ * observer.observe(el)
232
+ * })
233
+ *
234
+ * onUnmounted(() => observer?.disconnect())
235
+ * </script>
236
+ *
237
+ * <template>
238
+ * <span v-if="isPending">Loading...</span>
239
+ * <span v-else-if="isError">Error: {{ error.message }}</span>
240
+ * <template v-else>
241
+ * <ul>
242
+ * <template v-for="page in data.pages" :key="page.nextId">
243
+ * <li v-for="project in page.projects" :key="project.id">{{ project.name }}</li>
244
+ * </template>
245
+ * </ul>
246
+ * <div ref="sentinel">{{ isFetchingNextPage ? 'Loading more...' : '' }}</div>
247
+ * </template>
248
+ * </template>
249
+ * ```
250
+ */
88
251
  export function useInfiniteQuery<
89
252
  TQueryFnData,
90
253
  TError = DefaultError,
@@ -104,6 +267,83 @@ export function useInfiniteQuery<
104
267
  queryClient?: QueryClient,
105
268
  ): UseInfiniteQueryReturnType<TData, TError>
106
269
 
270
+ /**
271
+ * Fallback overload for options whose `initialData` presence isn't statically known — for example, a
272
+ * `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other
273
+ * overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly.
274
+ *
275
+ * `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter
276
+ * (`() => ...`). `queryKey` reacts through a `ref` for the array itself, or `ref`s and reactive getters as
277
+ * individual entries — the array itself can't be a bare getter.
278
+ *
279
+ * @param options - A `ref`, plain value, or reactive getter resolving to the {@link UseInfiniteQueryOptions} to
280
+ * use.
281
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin`
282
+ * will be used.
283
+ * @returns The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`,
284
+ * `hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`.
285
+ *
286
+ * @example
287
+ * Passing a whole-options getter so `maxPages` reacts to a setting stored elsewhere, not just `queryKey`:
288
+ * ```vue
289
+ * <script setup lang="ts">
290
+ * import { useInfiniteQuery } from '@tanstack/vue-query'
291
+ *
292
+ * const props = defineProps<{ projectId: number; maxPages: number }>()
293
+ *
294
+ * const { data } = useInfiniteQuery(() => ({
295
+ * queryKey: ['project', props.projectId, 'issues'],
296
+ * queryFn: ({ pageParam }) => fetchIssues(props.projectId, pageParam),
297
+ * initialPageParam: 0,
298
+ * getNextPageParam: (lastPage) => lastPage.nextId,
299
+ * maxPages: props.maxPages,
300
+ * }))
301
+ * </script>
302
+ *
303
+ * <template>
304
+ * <template v-for="page in data?.pages" :key="page.nextId">
305
+ * <li v-for="issue in page.issues" :key="issue.id">{{ issue.title }}</li>
306
+ * </template>
307
+ * </template>
308
+ * ```
309
+ *
310
+ * @example
311
+ * A query that's disabled, type-safe, until `postId` is set — pass `skipToken` as `queryFn` instead of
312
+ * setting `enabled: false`. This requires a whole-options getter: `queryFn` isn't itself reactive, so the
313
+ * getter is what re-evaluates it on every change to `props.postId`:
314
+ * ```vue
315
+ * <script setup lang="ts">
316
+ * import { skipToken, useInfiniteQuery } from '@tanstack/vue-query'
317
+ *
318
+ * const props = defineProps<{ postId: string | undefined }>()
319
+ *
320
+ * // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.
321
+ * const { data, isLoading, isError, error } = useInfiniteQuery(() => {
322
+ * const postId = props.postId
323
+ * return {
324
+ * queryKey: ['post', postId, 'comments'],
325
+ * queryFn:
326
+ * postId != null
327
+ * ? ({ pageParam }) => fetchComments(postId, pageParam)
328
+ * : skipToken,
329
+ * initialPageParam: 0,
330
+ * getNextPageParam: (lastPage) => lastPage.nextId,
331
+ * }
332
+ * })
333
+ * </script>
334
+ *
335
+ * <template>
336
+ * <span v-if="props.postId == null">Select a post</span>
337
+ * <span v-else-if="isLoading">Loading...</span>
338
+ * <span v-else-if="isError">Error: {{ error.message }}</span>
339
+ * <ul v-else>
340
+ * <template v-for="page in data.pages" :key="page.nextId">
341
+ * <li v-for="comment in page.comments" :key="comment.id">{{ comment.text }}</li>
342
+ * </template>
343
+ * </ul>
344
+ * </template>
345
+ * ```
346
+ */
107
347
  export function useInfiniteQuery<
108
348
  TQueryFnData,
109
349
  TError = DefaultError,