@tanstack/query-core 5.104.1 → 5.104.3

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 (359) hide show
  1. package/build/legacy/environmentManager.cjs +3 -1
  2. package/build/legacy/environmentManager.cjs.map +1 -1
  3. package/build/legacy/environmentManager.d.cts +6 -1
  4. package/build/legacy/environmentManager.d.cts.map +1 -1
  5. package/build/legacy/environmentManager.d.ts +6 -1
  6. package/build/legacy/environmentManager.d.ts.map +1 -1
  7. package/build/legacy/environmentManager.js +3 -1
  8. package/build/legacy/environmentManager.js.map +1 -1
  9. package/build/legacy/focusManager.cjs +4 -2
  10. package/build/legacy/focusManager.cjs.map +1 -1
  11. package/build/legacy/focusManager.d.cts +5 -3
  12. package/build/legacy/focusManager.d.cts.map +1 -1
  13. package/build/legacy/focusManager.d.ts +5 -3
  14. package/build/legacy/focusManager.d.ts.map +1 -1
  15. package/build/legacy/focusManager.js +4 -2
  16. package/build/legacy/focusManager.js.map +1 -1
  17. package/build/legacy/{hydration-B9t5w6NC.d.ts → hydration-Bf0oMcwO.d.ts} +1411 -129
  18. package/build/legacy/hydration-Bf0oMcwO.d.ts.map +1 -0
  19. package/build/legacy/{hydration-Br9VIGXa.d.cts → hydration-C6zghADG.d.cts} +1411 -129
  20. package/build/legacy/hydration-C6zghADG.d.cts.map +1 -0
  21. package/build/legacy/hydration.cjs +35 -0
  22. package/build/legacy/hydration.cjs.map +1 -1
  23. package/build/legacy/hydration.d.cts +1 -1
  24. package/build/legacy/hydration.d.ts +1 -1
  25. package/build/legacy/hydration.js +35 -0
  26. package/build/legacy/hydration.js.map +1 -1
  27. package/build/legacy/index.d.cts +1 -1
  28. package/build/legacy/index.d.ts +1 -1
  29. package/build/legacy/infiniteQueryBehavior.cjs +29 -0
  30. package/build/legacy/infiniteQueryBehavior.cjs.map +1 -1
  31. package/build/legacy/infiniteQueryBehavior.d.cts +16 -1
  32. package/build/legacy/infiniteQueryBehavior.d.cts.map +1 -1
  33. package/build/legacy/infiniteQueryBehavior.d.ts +16 -1
  34. package/build/legacy/infiniteQueryBehavior.d.ts.map +1 -1
  35. package/build/legacy/infiniteQueryBehavior.js +29 -0
  36. package/build/legacy/infiniteQueryBehavior.js.map +1 -1
  37. package/build/legacy/infiniteQueryObserver.cjs +13 -7
  38. package/build/legacy/infiniteQueryObserver.cjs.map +1 -1
  39. package/build/legacy/infiniteQueryObserver.d.cts +15 -9
  40. package/build/legacy/infiniteQueryObserver.d.cts.map +1 -1
  41. package/build/legacy/infiniteQueryObserver.d.ts +15 -9
  42. package/build/legacy/infiniteQueryObserver.d.ts.map +1 -1
  43. package/build/legacy/infiniteQueryObserver.js +13 -7
  44. package/build/legacy/infiniteQueryObserver.js.map +1 -1
  45. package/build/legacy/mutation.cjs +27 -10
  46. package/build/legacy/mutation.cjs.map +1 -1
  47. package/build/legacy/mutation.d.cts +1 -1
  48. package/build/legacy/mutation.d.ts +1 -1
  49. package/build/legacy/mutation.js +27 -10
  50. package/build/legacy/mutation.js.map +1 -1
  51. package/build/legacy/mutationCache.cjs +53 -12
  52. package/build/legacy/mutationCache.cjs.map +1 -1
  53. package/build/legacy/mutationCache.d.cts +1 -1
  54. package/build/legacy/mutationCache.d.ts +1 -1
  55. package/build/legacy/mutationCache.js +53 -12
  56. package/build/legacy/mutationCache.js.map +1 -1
  57. package/build/legacy/mutationObserver.cjs +27 -16
  58. package/build/legacy/mutationObserver.cjs.map +1 -1
  59. package/build/legacy/mutationObserver.d.cts +1 -1
  60. package/build/legacy/mutationObserver.d.ts +1 -1
  61. package/build/legacy/mutationObserver.js +27 -16
  62. package/build/legacy/mutationObserver.js.map +1 -1
  63. package/build/legacy/notifyManager.cjs +12 -2
  64. package/build/legacy/notifyManager.cjs.map +1 -1
  65. package/build/legacy/notifyManager.d.cts +19 -4
  66. package/build/legacy/notifyManager.d.cts.map +1 -1
  67. package/build/legacy/notifyManager.d.ts +19 -4
  68. package/build/legacy/notifyManager.d.ts.map +1 -1
  69. package/build/legacy/notifyManager.js +12 -2
  70. package/build/legacy/notifyManager.js.map +1 -1
  71. package/build/legacy/onlineManager.cjs +4 -2
  72. package/build/legacy/onlineManager.cjs.map +1 -1
  73. package/build/legacy/onlineManager.d.cts +5 -3
  74. package/build/legacy/onlineManager.d.cts.map +1 -1
  75. package/build/legacy/onlineManager.d.ts +5 -3
  76. package/build/legacy/onlineManager.d.ts.map +1 -1
  77. package/build/legacy/onlineManager.js +4 -2
  78. package/build/legacy/onlineManager.js.map +1 -1
  79. package/build/legacy/queriesObserver.cjs +15 -3
  80. package/build/legacy/queriesObserver.cjs.map +1 -1
  81. package/build/legacy/queriesObserver.d.cts +14 -5
  82. package/build/legacy/queriesObserver.d.cts.map +1 -1
  83. package/build/legacy/queriesObserver.d.ts +14 -5
  84. package/build/legacy/queriesObserver.d.ts.map +1 -1
  85. package/build/legacy/queriesObserver.js +15 -3
  86. package/build/legacy/queriesObserver.js.map +1 -1
  87. package/build/legacy/query.cjs +89 -15
  88. package/build/legacy/query.cjs.map +1 -1
  89. package/build/legacy/query.d.cts +1 -1
  90. package/build/legacy/query.d.ts +1 -1
  91. package/build/legacy/query.js +89 -15
  92. package/build/legacy/query.js.map +1 -1
  93. package/build/legacy/queryCache.cjs +34 -12
  94. package/build/legacy/queryCache.cjs.map +1 -1
  95. package/build/legacy/queryCache.d.cts +1 -1
  96. package/build/legacy/queryCache.d.ts +1 -1
  97. package/build/legacy/queryCache.js +34 -12
  98. package/build/legacy/queryCache.js.map +1 -1
  99. package/build/legacy/queryClient.cjs +104 -32
  100. package/build/legacy/queryClient.cjs.map +1 -1
  101. package/build/legacy/queryClient.d.cts +1 -1
  102. package/build/legacy/queryClient.d.ts +1 -1
  103. package/build/legacy/queryClient.js +104 -32
  104. package/build/legacy/queryClient.js.map +1 -1
  105. package/build/legacy/queryObserver.cjs +78 -6
  106. package/build/legacy/queryObserver.cjs.map +1 -1
  107. package/build/legacy/queryObserver.d.cts +1 -1
  108. package/build/legacy/queryObserver.d.ts +1 -1
  109. package/build/legacy/queryObserver.js +78 -6
  110. package/build/legacy/queryObserver.js.map +1 -1
  111. package/build/{modern/removable-0GzhW1PK.d.cts → legacy/removable-Cw9GNGyK.d.cts} +17 -1
  112. package/build/legacy/removable-Cw9GNGyK.d.cts.map +1 -0
  113. package/build/legacy/{removable-0GzhW1PK.d.cts → removable-Cw9GNGyK.d.ts} +17 -1
  114. package/build/legacy/removable-Cw9GNGyK.d.ts.map +1 -0
  115. package/build/legacy/removable.cjs +12 -0
  116. package/build/legacy/removable.cjs.map +1 -1
  117. package/build/legacy/removable.d.cts +1 -1
  118. package/build/legacy/removable.d.ts +1 -1
  119. package/build/legacy/removable.js +12 -0
  120. package/build/legacy/removable.js.map +1 -1
  121. package/build/legacy/retryer.cjs +26 -4
  122. package/build/legacy/retryer.cjs.map +1 -1
  123. package/build/legacy/retryer.d.cts +1 -1
  124. package/build/legacy/retryer.d.ts +1 -1
  125. package/build/legacy/retryer.js +26 -4
  126. package/build/legacy/retryer.js.map +1 -1
  127. package/build/legacy/streamedQuery.cjs +3 -1
  128. package/build/legacy/streamedQuery.cjs.map +1 -1
  129. package/build/legacy/streamedQuery.d.cts +4 -2
  130. package/build/legacy/streamedQuery.d.cts.map +1 -1
  131. package/build/legacy/streamedQuery.d.ts +4 -2
  132. package/build/legacy/streamedQuery.d.ts.map +1 -1
  133. package/build/legacy/streamedQuery.js +3 -1
  134. package/build/legacy/streamedQuery.js.map +1 -1
  135. package/build/{modern/subscribable-CysQ0tne.d.cts → legacy/subscribable-czlHOxMP.d.cts} +11 -1
  136. package/build/legacy/subscribable-czlHOxMP.d.cts.map +1 -0
  137. package/build/legacy/{subscribable-CysQ0tne.d.cts → subscribable-czlHOxMP.d.ts} +11 -1
  138. package/build/legacy/subscribable-czlHOxMP.d.ts.map +1 -0
  139. package/build/legacy/subscribable.cjs +10 -0
  140. package/build/legacy/subscribable.cjs.map +1 -1
  141. package/build/legacy/subscribable.d.cts +1 -1
  142. package/build/legacy/subscribable.d.ts +1 -1
  143. package/build/legacy/subscribable.js +10 -0
  144. package/build/legacy/subscribable.js.map +1 -1
  145. package/build/legacy/timeoutManager.cjs +11 -6
  146. package/build/legacy/timeoutManager.cjs.map +1 -1
  147. package/build/legacy/timeoutManager.d.cts +23 -6
  148. package/build/legacy/timeoutManager.d.cts.map +1 -1
  149. package/build/legacy/timeoutManager.d.ts +23 -6
  150. package/build/legacy/timeoutManager.d.ts.map +1 -1
  151. package/build/legacy/timeoutManager.js +11 -6
  152. package/build/legacy/timeoutManager.js.map +1 -1
  153. package/build/legacy/types.cjs.map +1 -1
  154. package/build/legacy/types.d.cts +1 -1
  155. package/build/legacy/types.d.ts +1 -1
  156. package/build/legacy/types.js.map +1 -1
  157. package/build/legacy/utils.cjs +117 -8
  158. package/build/legacy/utils.cjs.map +1 -1
  159. package/build/legacy/utils.d.cts +1 -1
  160. package/build/legacy/utils.d.ts +1 -1
  161. package/build/legacy/utils.js +117 -8
  162. package/build/legacy/utils.js.map +1 -1
  163. package/build/modern/environmentManager.cjs +3 -1
  164. package/build/modern/environmentManager.cjs.map +1 -1
  165. package/build/modern/environmentManager.d.cts +6 -1
  166. package/build/modern/environmentManager.d.cts.map +1 -1
  167. package/build/modern/environmentManager.d.ts +6 -1
  168. package/build/modern/environmentManager.d.ts.map +1 -1
  169. package/build/modern/environmentManager.js +3 -1
  170. package/build/modern/environmentManager.js.map +1 -1
  171. package/build/modern/focusManager.cjs +4 -2
  172. package/build/modern/focusManager.cjs.map +1 -1
  173. package/build/modern/focusManager.d.cts +5 -3
  174. package/build/modern/focusManager.d.cts.map +1 -1
  175. package/build/modern/focusManager.d.ts +5 -3
  176. package/build/modern/focusManager.d.ts.map +1 -1
  177. package/build/modern/focusManager.js +4 -2
  178. package/build/modern/focusManager.js.map +1 -1
  179. package/build/modern/{hydration-B9t5w6NC.d.ts → hydration-Bf0oMcwO.d.ts} +1411 -129
  180. package/build/modern/hydration-Bf0oMcwO.d.ts.map +1 -0
  181. package/build/modern/{hydration-Br9VIGXa.d.cts → hydration-C6zghADG.d.cts} +1411 -129
  182. package/build/modern/hydration-C6zghADG.d.cts.map +1 -0
  183. package/build/modern/hydration.cjs +35 -0
  184. package/build/modern/hydration.cjs.map +1 -1
  185. package/build/modern/hydration.d.cts +1 -1
  186. package/build/modern/hydration.d.ts +1 -1
  187. package/build/modern/hydration.js +35 -0
  188. package/build/modern/hydration.js.map +1 -1
  189. package/build/modern/index.d.cts +1 -1
  190. package/build/modern/index.d.ts +1 -1
  191. package/build/modern/infiniteQueryBehavior.cjs +29 -0
  192. package/build/modern/infiniteQueryBehavior.cjs.map +1 -1
  193. package/build/modern/infiniteQueryBehavior.d.cts +16 -1
  194. package/build/modern/infiniteQueryBehavior.d.cts.map +1 -1
  195. package/build/modern/infiniteQueryBehavior.d.ts +16 -1
  196. package/build/modern/infiniteQueryBehavior.d.ts.map +1 -1
  197. package/build/modern/infiniteQueryBehavior.js +29 -0
  198. package/build/modern/infiniteQueryBehavior.js.map +1 -1
  199. package/build/modern/infiniteQueryObserver.cjs +13 -7
  200. package/build/modern/infiniteQueryObserver.cjs.map +1 -1
  201. package/build/modern/infiniteQueryObserver.d.cts +15 -9
  202. package/build/modern/infiniteQueryObserver.d.cts.map +1 -1
  203. package/build/modern/infiniteQueryObserver.d.ts +15 -9
  204. package/build/modern/infiniteQueryObserver.d.ts.map +1 -1
  205. package/build/modern/infiniteQueryObserver.js +13 -7
  206. package/build/modern/infiniteQueryObserver.js.map +1 -1
  207. package/build/modern/mutation.cjs +27 -10
  208. package/build/modern/mutation.cjs.map +1 -1
  209. package/build/modern/mutation.d.cts +1 -1
  210. package/build/modern/mutation.d.ts +1 -1
  211. package/build/modern/mutation.js +27 -10
  212. package/build/modern/mutation.js.map +1 -1
  213. package/build/modern/mutationCache.cjs +53 -12
  214. package/build/modern/mutationCache.cjs.map +1 -1
  215. package/build/modern/mutationCache.d.cts +1 -1
  216. package/build/modern/mutationCache.d.ts +1 -1
  217. package/build/modern/mutationCache.js +53 -12
  218. package/build/modern/mutationCache.js.map +1 -1
  219. package/build/modern/mutationObserver.cjs +23 -12
  220. package/build/modern/mutationObserver.cjs.map +1 -1
  221. package/build/modern/mutationObserver.d.cts +1 -1
  222. package/build/modern/mutationObserver.d.ts +1 -1
  223. package/build/modern/mutationObserver.js +23 -12
  224. package/build/modern/mutationObserver.js.map +1 -1
  225. package/build/modern/notifyManager.cjs +12 -2
  226. package/build/modern/notifyManager.cjs.map +1 -1
  227. package/build/modern/notifyManager.d.cts +19 -4
  228. package/build/modern/notifyManager.d.cts.map +1 -1
  229. package/build/modern/notifyManager.d.ts +19 -4
  230. package/build/modern/notifyManager.d.ts.map +1 -1
  231. package/build/modern/notifyManager.js +12 -2
  232. package/build/modern/notifyManager.js.map +1 -1
  233. package/build/modern/onlineManager.cjs +4 -2
  234. package/build/modern/onlineManager.cjs.map +1 -1
  235. package/build/modern/onlineManager.d.cts +5 -3
  236. package/build/modern/onlineManager.d.cts.map +1 -1
  237. package/build/modern/onlineManager.d.ts +5 -3
  238. package/build/modern/onlineManager.d.ts.map +1 -1
  239. package/build/modern/onlineManager.js +4 -2
  240. package/build/modern/onlineManager.js.map +1 -1
  241. package/build/modern/queriesObserver.cjs +15 -3
  242. package/build/modern/queriesObserver.cjs.map +1 -1
  243. package/build/modern/queriesObserver.d.cts +14 -5
  244. package/build/modern/queriesObserver.d.cts.map +1 -1
  245. package/build/modern/queriesObserver.d.ts +14 -5
  246. package/build/modern/queriesObserver.d.ts.map +1 -1
  247. package/build/modern/queriesObserver.js +15 -3
  248. package/build/modern/queriesObserver.js.map +1 -1
  249. package/build/modern/query.cjs +89 -15
  250. package/build/modern/query.cjs.map +1 -1
  251. package/build/modern/query.d.cts +1 -1
  252. package/build/modern/query.d.ts +1 -1
  253. package/build/modern/query.js +89 -15
  254. package/build/modern/query.js.map +1 -1
  255. package/build/modern/queryCache.cjs +34 -12
  256. package/build/modern/queryCache.cjs.map +1 -1
  257. package/build/modern/queryCache.d.cts +1 -1
  258. package/build/modern/queryCache.d.ts +1 -1
  259. package/build/modern/queryCache.js +34 -12
  260. package/build/modern/queryCache.js.map +1 -1
  261. package/build/modern/queryClient.cjs +104 -32
  262. package/build/modern/queryClient.cjs.map +1 -1
  263. package/build/modern/queryClient.d.cts +1 -1
  264. package/build/modern/queryClient.d.ts +1 -1
  265. package/build/modern/queryClient.js +104 -32
  266. package/build/modern/queryClient.js.map +1 -1
  267. package/build/modern/queryObserver.cjs +78 -6
  268. package/build/modern/queryObserver.cjs.map +1 -1
  269. package/build/modern/queryObserver.d.cts +1 -1
  270. package/build/modern/queryObserver.d.ts +1 -1
  271. package/build/modern/queryObserver.js +78 -6
  272. package/build/modern/queryObserver.js.map +1 -1
  273. package/build/modern/{removable-0GzhW1PK.d.ts → removable-Cw9GNGyK.d.cts} +17 -1
  274. package/build/modern/removable-Cw9GNGyK.d.cts.map +1 -0
  275. package/build/{legacy/removable-0GzhW1PK.d.ts → modern/removable-Cw9GNGyK.d.ts} +17 -1
  276. package/build/modern/removable-Cw9GNGyK.d.ts.map +1 -0
  277. package/build/modern/removable.cjs +12 -0
  278. package/build/modern/removable.cjs.map +1 -1
  279. package/build/modern/removable.d.cts +1 -1
  280. package/build/modern/removable.d.ts +1 -1
  281. package/build/modern/removable.js +12 -0
  282. package/build/modern/removable.js.map +1 -1
  283. package/build/modern/retryer.cjs +26 -4
  284. package/build/modern/retryer.cjs.map +1 -1
  285. package/build/modern/retryer.d.cts +1 -1
  286. package/build/modern/retryer.d.ts +1 -1
  287. package/build/modern/retryer.js +26 -4
  288. package/build/modern/retryer.js.map +1 -1
  289. package/build/modern/streamedQuery.cjs +3 -1
  290. package/build/modern/streamedQuery.cjs.map +1 -1
  291. package/build/modern/streamedQuery.d.cts +4 -2
  292. package/build/modern/streamedQuery.d.cts.map +1 -1
  293. package/build/modern/streamedQuery.d.ts +4 -2
  294. package/build/modern/streamedQuery.d.ts.map +1 -1
  295. package/build/modern/streamedQuery.js +3 -1
  296. package/build/modern/streamedQuery.js.map +1 -1
  297. package/build/modern/{subscribable-CysQ0tne.d.ts → subscribable-czlHOxMP.d.cts} +11 -1
  298. package/build/modern/subscribable-czlHOxMP.d.cts.map +1 -0
  299. package/build/{legacy/subscribable-CysQ0tne.d.ts → modern/subscribable-czlHOxMP.d.ts} +11 -1
  300. package/build/modern/subscribable-czlHOxMP.d.ts.map +1 -0
  301. package/build/modern/subscribable.cjs +10 -0
  302. package/build/modern/subscribable.cjs.map +1 -1
  303. package/build/modern/subscribable.d.cts +1 -1
  304. package/build/modern/subscribable.d.ts +1 -1
  305. package/build/modern/subscribable.js +10 -0
  306. package/build/modern/subscribable.js.map +1 -1
  307. package/build/modern/timeoutManager.cjs +11 -6
  308. package/build/modern/timeoutManager.cjs.map +1 -1
  309. package/build/modern/timeoutManager.d.cts +23 -6
  310. package/build/modern/timeoutManager.d.cts.map +1 -1
  311. package/build/modern/timeoutManager.d.ts +23 -6
  312. package/build/modern/timeoutManager.d.ts.map +1 -1
  313. package/build/modern/timeoutManager.js +11 -6
  314. package/build/modern/timeoutManager.js.map +1 -1
  315. package/build/modern/types.cjs.map +1 -1
  316. package/build/modern/types.d.cts +1 -1
  317. package/build/modern/types.d.ts +1 -1
  318. package/build/modern/types.js.map +1 -1
  319. package/build/modern/utils.cjs +117 -8
  320. package/build/modern/utils.cjs.map +1 -1
  321. package/build/modern/utils.d.cts +1 -1
  322. package/build/modern/utils.d.ts +1 -1
  323. package/build/modern/utils.js +117 -8
  324. package/build/modern/utils.js.map +1 -1
  325. package/package.json +3 -3
  326. package/src/environmentManager.ts +6 -1
  327. package/src/focusManager.ts +8 -6
  328. package/src/hydration.ts +42 -1
  329. package/src/infiniteQueryBehavior.ts +29 -0
  330. package/src/infiniteQueryObserver.ts +20 -14
  331. package/src/mutation.ts +32 -11
  332. package/src/mutationCache.ts +53 -12
  333. package/src/mutationObserver.ts +29 -14
  334. package/src/notifyManager.ts +12 -2
  335. package/src/onlineManager.ts +7 -5
  336. package/src/queriesObserver.ts +20 -5
  337. package/src/query.ts +153 -20
  338. package/src/queryCache.ts +54 -13
  339. package/src/queryClient.ts +114 -42
  340. package/src/queryObserver.ts +88 -12
  341. package/src/removable.ts +16 -0
  342. package/src/retryer.ts +57 -4
  343. package/src/streamedQuery.ts +4 -3
  344. package/src/subscribable.ts +10 -0
  345. package/src/timeoutManager.ts +23 -6
  346. package/src/types.ts +801 -27
  347. package/src/utils.ts +130 -10
  348. package/build/legacy/hydration-B9t5w6NC.d.ts.map +0 -1
  349. package/build/legacy/hydration-Br9VIGXa.d.cts.map +0 -1
  350. package/build/legacy/removable-0GzhW1PK.d.cts.map +0 -1
  351. package/build/legacy/removable-0GzhW1PK.d.ts.map +0 -1
  352. package/build/legacy/subscribable-CysQ0tne.d.cts.map +0 -1
  353. package/build/legacy/subscribable-CysQ0tne.d.ts.map +0 -1
  354. package/build/modern/hydration-B9t5w6NC.d.ts.map +0 -1
  355. package/build/modern/hydration-Br9VIGXa.d.cts.map +0 -1
  356. package/build/modern/removable-0GzhW1PK.d.cts.map +0 -1
  357. package/build/modern/removable-0GzhW1PK.d.ts.map +0 -1
  358. package/build/modern/subscribable-CysQ0tne.d.cts.map +0 -1
  359. package/build/modern/subscribable-CysQ0tne.d.ts.map +0 -1
@@ -1,5 +1,5 @@
1
- import { t as Subscribable } from "./subscribable-CysQ0tne.cjs";
2
- import { t as Removable } from "./removable-0GzhW1PK.cjs";
1
+ import { t as Subscribable } from "./subscribable-czlHOxMP.cjs";
2
+ import { t as Removable } from "./removable-Cw9GNGyK.cjs";
3
3
  //#region src/queryObserver.d.ts
4
4
  type QueryObserverListener<TData, TError> = (result: QueryObserverResult<TData, TError>) => void;
5
5
  interface ObserverFetchOptions extends FetchOptions {
@@ -12,7 +12,6 @@ interface ObserverFetchOptions extends FetchOptions {
12
12
  * the primitive that framework adapters (e.g. `useQuery`) build their hooks
13
13
  * on top of, but it can also be used directly to observe and switch between
14
14
  * queries outside of any framework.
15
- *
16
15
  * @example
17
16
  * ```ts
18
17
  * const observer = new QueryObserver(queryClient, {
@@ -29,6 +28,10 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
29
28
  #private;
30
29
  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
31
30
  constructor(client: QueryClient, options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>);
31
+ /**
32
+ * Binds the methods of the result (`refetch`) to the observer, so they keep working when destructured
33
+ * from it. Subclasses override it to bind their own result methods as well.
34
+ */
32
35
  protected bindMethods(): void;
33
36
  protected onSubscribe(): void;
34
37
  protected onUnsubscribe(): void;
@@ -36,12 +39,14 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
36
39
  * Returns whether the observed query is currently stale and configured
37
40
  * (via the `refetchOnReconnect` option) to refetch when the network
38
41
  * reconnects.
42
+ * @returns `true` if the observer should refetch the query on reconnect.
39
43
  */
40
44
  shouldFetchOnReconnect(): boolean;
41
45
  /**
42
46
  * Returns whether the observed query is currently stale and configured
43
47
  * (via the `refetchOnWindowFocus` option) to refetch when the window
44
48
  * regains focus.
49
+ * @returns `true` if the observer should refetch the query on window focus.
45
50
  */
46
51
  shouldFetchOnWindowFocus(): boolean;
47
52
  /**
@@ -56,7 +61,9 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
56
61
  * trigger a fetch if the new options require one and the observer has
57
62
  * subscribers, recompute the current result, and reschedule the stale and
58
63
  * refetch-interval timers as needed.
59
- *
64
+ * @param options - The new observer options. They are defaulted with {@link
65
+ * QueryClient#defaultQueryOptions} before being applied.
66
+ * @throws {Error} If `enabled` is neither a boolean nor a function.
60
67
  * @example
61
68
  * ```ts
62
69
  * observer.setOptions({ queryKey: ['posts', 1], queryFn: () => fetchPost(1) })
@@ -70,6 +77,8 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
70
77
  * right now, building the underlying `Query` if it doesn't exist yet, without waiting for a
71
78
  * subscription callback. Called by framework adapters on every render (e.g. `useQuery`) so the
72
79
  * returned value is available synchronously, ahead of `setOptions` triggering an actual fetch.
80
+ * @param options - The defaulted observer options to compute the result for.
81
+ * @returns The result for the given options.
73
82
  */
74
83
  getOptimisticResult(options: DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverResult<TData, TError>;
75
84
  /**
@@ -77,7 +86,7 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
77
86
  * observed query. This is a point-in-time read; to be notified of updates
78
87
  * as they happen, subscribe to the observer instead (its inherited
79
88
  * `subscribe` method).
80
- *
89
+ * @returns The observer's latest result.
81
90
  * @example
82
91
  * ```ts
83
92
  * const result = observer.getCurrentResult()
@@ -90,6 +99,9 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
90
99
  * {@link QueryObserver#trackProp} (and an optional `onPropTracked` callback). Used by framework
91
100
  * adapters when `notifyOnChangeProps` is not set, to implement its default "only re-render on
92
101
  * properties you actually read" behavior.
102
+ * @param result - The result to wrap.
103
+ * @param onPropTracked - Called with the name of each property that is read.
104
+ * @returns A proxy of `result` that tracks property reads.
93
105
  */
94
106
  trackResult(result: QueryObserverResult<TData, TError>, onPropTracked?: (key: keyof QueryObserverResult) => void): QueryObserverResult<TData, TError>;
95
107
  /**
@@ -97,16 +109,20 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
97
109
  * notifies this observer if a tracked property actually changed. Normally called indirectly via
98
110
  * {@link QueryObserver#trackResult}'s proxy; exposed directly for adapters that track property
99
111
  * access themselves (e.g. through their own reactivity system) instead of via the proxy.
112
+ * @param key - The name of the property that was read.
100
113
  */
101
114
  trackProp(key: keyof QueryObserverResult): void;
102
115
  /**
103
116
  * Returns the `Query` instance this observer is currently observing.
117
+ * @returns The observed query.
104
118
  */
105
119
  getCurrentQuery(): Query<TQueryFnData, TError, TQueryData, TQueryKey>;
106
120
  /**
107
121
  * Refetches the observed query and returns a promise that resolves with
108
122
  * the resulting `QueryObserverResult`.
109
- *
123
+ * @param options - Set `cancelRefetch` to `false` to keep a running fetch instead of cancelling
124
+ * it, and `throwOnError` to `true` to reject when the refetch fails.
125
+ * @returns A promise that resolves with the result after the refetch.
110
126
  * @example
111
127
  * ```ts
112
128
  * const result = await observer.refetch({ cancelRefetch: false })
@@ -120,7 +136,8 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
120
136
  * resolves with the `QueryObserverResult` for that fetch. This is useful
121
137
  * for prefetching data that another observer (e.g. a query about to be
122
138
  * navigated to) will need, ahead of time.
123
- *
139
+ * @param options - The observer options of the query to fetch.
140
+ * @returns A promise that resolves with the result for the fetched query.
124
141
  * @example
125
142
  * ```ts
126
143
  * const result = await observer.fetchOptimistic({
@@ -131,7 +148,20 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
131
148
  * ```
132
149
  */
133
150
  fetchOptimistic(options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): Promise<QueryObserverResult<TData, TError>>;
151
+ /**
152
+ * Fetches the observed query and updates the result once the fetch settles. Used by `refetch` and,
153
+ * in `InfiniteQueryObserver`, to fetch more pages.
154
+ * @param fetchOptions - Options for this fetch. `cancelRefetch` defaults to `true`.
155
+ * @returns A promise that resolves with the updated result.
156
+ */
134
157
  protected fetch(fetchOptions: ObserverFetchOptions): Promise<QueryObserverResult<TData, TError>>;
158
+ /**
159
+ * Computes the result for a query and options from the query's state, applying `select`,
160
+ * `placeholderData`, and the derived flags. Subclasses override it to add their own fields.
161
+ * @param query - The query to compute the result for.
162
+ * @param options - The observer options to compute the result with.
163
+ * @returns The computed result.
164
+ */
135
165
  protected createResult(query: Query<TQueryFnData, TError, TQueryData, TQueryKey>, options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverResult<TData, TError>;
136
166
  /**
137
167
  * Recomputes and stores the current result from the current query/options, notifying listeners
@@ -139,7 +169,11 @@ declare class QueryObserver<TQueryFnData = unknown, TError = DefaultError, TData
139
169
  * update was missed in the gap between creating the observer and subscribing to it.
140
170
  */
141
171
  updateResult(): void;
142
- /** @internal */
172
+ /**
173
+ * Updates the observer's result when the observed query changes, and reschedules its timers if it
174
+ * has listeners.
175
+ * @internal
176
+ */
143
177
  onQueryUpdate(): void;
144
178
  }
145
179
  //#endregion
@@ -218,27 +252,82 @@ interface QueryState<TData = unknown, TError = DefaultError> {
218
252
  */
219
253
  fetchStatus: FetchStatus;
220
254
  }
255
+ /**
256
+ * The context passed to a {@link QueryBehavior}'s `onFetch`, which can replace `fetchFn` to change
257
+ * how the query fetches (e.g. to fetch pages for an infinite query).
258
+ */
221
259
  interface FetchContext<TQueryFnData, TError, TData, TQueryKey extends QueryKey = QueryKey> {
260
+ /**
261
+ * The function that runs the fetch. By default it calls `queryFn`; `onFetch` can replace it.
262
+ */
222
263
  fetchFn: () => unknown | Promise<unknown>;
264
+ /**
265
+ * The options of this fetch.
266
+ */
223
267
  fetchOptions?: FetchOptions;
268
+ /**
269
+ * The `AbortSignal` that aborts when the fetch is cancelled.
270
+ */
224
271
  signal: AbortSignal;
272
+ /**
273
+ * The options of the query.
274
+ */
225
275
  options: QueryOptions<TQueryFnData, TError, TData, any>;
276
+ /**
277
+ * The `QueryClient` the query belongs to.
278
+ */
226
279
  client: QueryClient;
280
+ /**
281
+ * The key of the query.
282
+ */
227
283
  queryKey: TQueryKey;
284
+ /**
285
+ * The state of the query when the fetch starts.
286
+ */
228
287
  state: QueryState<TData, TError>;
229
288
  }
289
+ /**
290
+ * Customizes how a query fetches, e.g. the behavior that fetches the pages of an infinite query.
291
+ */
230
292
  interface QueryBehavior<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> {
293
+ /**
294
+ * Called before each fetch of the query, e.g. to replace `fetchFn` in the context.
295
+ */
231
296
  onFetch: (context: FetchContext<TQueryFnData, TError, TData, TQueryKey>, query: Query) => void;
232
297
  }
298
+ /**
299
+ * The direction an infinite query fetches in: `'forward'` for the next page, `'backward'` for the
300
+ * previous one.
301
+ */
233
302
  type FetchDirection = 'forward' | 'backward';
303
+ /**
304
+ * Metadata for a fetch, e.g. the direction when an infinite query fetches more pages.
305
+ */
234
306
  interface FetchMeta {
307
+ /**
308
+ * Set when an infinite query fetches another page, with the direction to fetch in.
309
+ */
235
310
  fetchMore?: {
236
311
  direction: FetchDirection;
237
312
  };
238
313
  }
314
+ /**
315
+ * Options for a single fetch of a query.
316
+ */
239
317
  interface FetchOptions<TData = unknown> {
318
+ /**
319
+ * If `true`, an in-flight fetch is cancelled before starting a new one, when the query already
320
+ * has data. Otherwise, the in-flight fetch is reused.
321
+ */
240
322
  cancelRefetch?: boolean;
323
+ /**
324
+ * Metadata of the fetch, stored in the query's `fetchMeta` state.
325
+ */
241
326
  meta?: FetchMeta;
327
+ /**
328
+ * A promise to use for the first attempt instead of calling `fetchFn`, e.g. a pending promise
329
+ * restored by `hydrate`.
330
+ */
242
331
  initialPromise?: Promise<TData>;
243
332
  }
244
333
  interface FailedAction$1<TError> {
@@ -273,6 +362,10 @@ interface SetStateAction<TData, TError> {
273
362
  type: 'setState';
274
363
  state: Partial<QueryState<TData, TError>>;
275
364
  }
365
+ /**
366
+ * The actions a query dispatches to update its state, e.g. when it starts fetching, fails, or
367
+ * succeeds.
368
+ */
276
369
  type Action$1<TData, TError> = ContinueAction$1 | ErrorAction$1<TError> | FailedAction$1<TError> | FetchAction | InvalidateAction | PauseAction$1 | SetStateAction<TData, TError> | SuccessAction$1<TData>;
277
370
  /**
278
371
  * Represents a single cached query. A `Query` holds the query's key, options,
@@ -282,7 +375,6 @@ type Action$1<TData, TError> = ContinueAction$1 | ErrorAction$1<TError> | Failed
282
375
  * code typically interacts with queries indirectly through `QueryClient` or
283
376
  * a framework hook like `useQuery`. Direct access to a `Query` instance is
284
377
  * possible via `queryCache.find()`/`findAll()` for inspecting cache state.
285
- *
286
378
  * @example
287
379
  * ```ts
288
380
  * const queryCache = queryClient.getQueryCache()
@@ -303,19 +395,37 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
303
395
  constructor(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>);
304
396
  /**
305
397
  * The `meta` object passed in the query's options, if any.
398
+ * @returns The query's `meta`, or `undefined` if none was set.
306
399
  */
307
400
  get meta(): QueryMeta | undefined;
308
- /** @internal */
401
+ /**
402
+ * `'infinite'` for an infinite query, otherwise `undefined`.
403
+ * @internal
404
+ * @returns The type of the query, set from the `_type` option (e.g. `'infinite'`).
405
+ */
309
406
  get queryType(): "infinite" | undefined;
310
407
  /**
311
408
  * The promise for the currently in-flight fetch, if the query is fetching.
312
409
  * `undefined` when the query is not fetching.
410
+ * @returns The promise of the in-flight fetch, or `undefined`.
313
411
  */
314
412
  get promise(): Promise<TData> | undefined;
315
- /** @internal */
413
+ /**
414
+ * Replaces the query's options and applies their `gcTime`. If the query has no data yet, it gets
415
+ * the `initialData` from the new options, if any.
416
+ * @internal
417
+ * @param options - The new query options, merged on top of the query's default options.
418
+ */
316
419
  setOptions(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>): void;
317
420
  protected optionalRemove(): void;
318
- /** @internal */
421
+ /**
422
+ * Writes new data to the query and marks it as successfully fetched.
423
+ * @internal
424
+ * @param newData - The data to write. Structural sharing with the current data is applied.
425
+ * @param options - Set `updatedAt` to override the timestamp, and `manual` to mark the write as
426
+ * manual (e.g. from `queryClient.setQueryData`).
427
+ * @returns The data that was written.
428
+ */
319
429
  setData(newData: TData, options?: SetDataOptions & {
320
430
  manual: boolean;
321
431
  }): TData;
@@ -323,13 +433,16 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
323
433
  * Merges the given partial state directly into this query's state, notifying observers. Used
324
434
  * by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
325
435
  * user manually trigger a loading/error state or edit the cached data.
436
+ * @param state - The partial state to merge into the query's state.
326
437
  */
327
438
  setState(state: Partial<QueryState<TData, TError>>): void;
328
439
  /**
329
440
  * Cancels the query's currently in-flight fetch, if any.
330
441
  * - Returns a promise that resolves once the cancellation has settled.
331
442
  * - If no fetch is in progress, resolves immediately.
332
- *
443
+ * @param options - Set `revert` to restore the state from before the fetch started, and `silent`
444
+ * to suppress the cancellation error when a new fetch replaces the cancelled one.
445
+ * @returns A promise that resolves once the cancellation has settled.
333
446
  * @example
334
447
  * ```ts
335
448
  * await query.cancel()
@@ -340,11 +453,14 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
340
453
  * Clears the query's garbage collection timeout and silently cancels any
341
454
  * in-flight fetch. Called by `QueryCache` when the query is removed from
342
455
  * the cache.
343
- *
344
456
  * @see {@link Query#cancel}
345
457
  */
346
458
  destroy(): void;
347
- /** @internal */
459
+ /**
460
+ * The state the query was created with.
461
+ * @internal
462
+ * @returns The state the query had when it was first created, used by {@link Query#reset}.
463
+ */
348
464
  get resetState(): QueryState<TData, TError>;
349
465
  /**
350
466
  * Resets the query back to its initial state (the state it had when it was
@@ -355,6 +471,7 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
355
471
  /**
356
472
  * Returns `true` if the query has at least one observer for which `enabled`
357
473
  * does not resolve to `false`.
474
+ * @returns `true` if the query has an enabled observer.
358
475
  */
359
476
  isActive(): boolean;
360
477
  /**
@@ -364,16 +481,19 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
364
481
  * (see `isActive`).
365
482
  * - If the query has no observers, it is disabled when its `queryFn` is
366
483
  * `skipToken` or it has never been fetched.
484
+ * @returns `true` if the query is disabled.
367
485
  */
368
486
  isDisabled(): boolean;
369
487
  /**
370
488
  * Returns `true` if the query has been fetched, i.e. it has resolved with
371
489
  * either data or an error at least once.
490
+ * @returns `true` if the query has been fetched.
372
491
  */
373
492
  isFetched(): boolean;
374
493
  /**
375
494
  * Returns `true` if the query has at least one observer configured with
376
495
  * `staleTime: 'static'`, meaning it is treated as never stale.
496
+ * @returns `true` if the query is static.
377
497
  */
378
498
  isStatic(): boolean;
379
499
  /**
@@ -383,7 +503,7 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
383
503
  * `staleTime` and `enabled` state).
384
504
  * - If the query has no observers, it is considered stale when it has no
385
505
  * data or has been invalidated.
386
- *
506
+ * @returns `true` if the query is stale.
387
507
  * @see {@link Query#isStaleByTime}
388
508
  * @example
389
509
  * ```ts
@@ -400,7 +520,9 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
400
520
  * - `staleTime: 'static'` is never stale.
401
521
  * - An invalidated query is always stale.
402
522
  * - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
403
- *
523
+ * @param staleTime - The time, in milliseconds, after which data is considered stale, or
524
+ * `'static'` to never treat existing data as stale. A query without data is stale either way.
525
+ * @returns `true` if the query's data is stale.
404
526
  * @see {@link Query#isStale}
405
527
  * @example
406
528
  * ```ts
@@ -408,17 +530,36 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
408
530
  * ```
409
531
  */
410
532
  isStaleByTime(staleTime?: StaleTime): boolean;
411
- /** @internal */
533
+ /**
534
+ * Refetches the query when the window regains focus, if an observer wants that, and continues a
535
+ * paused fetch.
536
+ * @internal
537
+ */
412
538
  onFocus(): void;
413
- /** @internal */
539
+ /**
540
+ * Refetches the query when the app reconnects, if an observer wants that, and continues a paused
541
+ * fetch.
542
+ * @internal
543
+ */
414
544
  onOnline(): void;
415
- /** @internal */
545
+ /**
546
+ * Subscribes an observer to the query and stops its garbage collection.
547
+ * @internal
548
+ * @param observer - The observer to add. Adding an observer that is already subscribed does
549
+ * nothing.
550
+ */
416
551
  addObserver(observer: QueryObserver<any, any, any, any, any>): void;
417
- /** @internal */
552
+ /**
553
+ * Unsubscribes an observer from the query.
554
+ * @internal
555
+ * @param observer - The observer to remove. When the last observer is removed, the in-flight
556
+ * fetch is cancelled if its abort signal was consumed (otherwise only its retries are stopped),
557
+ * and garbage collection is scheduled.
558
+ */
418
559
  removeObserver(observer: QueryObserver<any, any, any, any, any>): void;
419
560
  /**
420
561
  * Returns the number of observers currently subscribed to this query.
421
- *
562
+ * @returns The number of observers.
422
563
  * @example
423
564
  * ```ts
424
565
  * if (query.getObserversCount() === 0) {
@@ -431,7 +572,6 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
431
572
  * Marks the query as invalidated, unless it is already invalidated. This
432
573
  * updates `state.isInvalidated` and notifies observers, but does not by
433
574
  * itself trigger a refetch.
434
- *
435
575
  * @example
436
576
  * ```ts
437
577
  * query.invalidate()
@@ -447,9 +587,24 @@ declare class Query<TQueryFnData = unknown, TError = DefaultError, TData = TQuer
447
587
  * cancelled first.
448
588
  * - If `options` is passed, it replaces the query's current options
449
589
  * before fetching.
590
+ * @param options - Query options that replace the query's current options before fetching. They
591
+ * are not applied when an in-flight fetch is reused.
592
+ * @param fetchOptions - Set `cancelRefetch` to cancel an in-flight fetch first (only if the query
593
+ * already has data), and `meta` to pass extra information to the query's behavior.
594
+ * @returns A promise that resolves with the fetched data, or rejects with the fetch error. If the
595
+ * fetch is cancelled with `revert` while the query has data, it resolves with the restored data
596
+ * instead.
450
597
  */
451
598
  fetch(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;
452
599
  }
600
+ /**
601
+ * Returns the state changes applied when a query starts fetching.
602
+ * @param data - The query's current data. If it is `undefined`, the query is also reset to
603
+ * `'pending'` with no error.
604
+ * @param options - The query options, whose `networkMode` decides whether the query is `'fetching'`
605
+ * or `'paused'`.
606
+ * @returns The partial query state for a starting fetch.
607
+ */
453
608
  declare function fetchState<TQueryFnData, TError, TData, TQueryKey extends QueryKey>(data: TData | undefined, options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>): {
454
609
  readonly error?: null | undefined;
455
610
  readonly status?: "pending" | undefined;
@@ -467,7 +622,6 @@ type MutationObserverListener<TData, TError, TVariables, TOnMutateResult> = (res
467
622
  * passed to the hook change, subscribes to it to re-render on updates, and
468
623
  * reads `getCurrentResult()` for the value to return. Calling `mutate()`
469
624
  * builds a new underlying `Mutation` in the `MutationCache` and executes it.
470
- *
471
625
  * @example
472
626
  * ```ts
473
627
  * const observer = new MutationObserver(queryClient, {
@@ -479,6 +633,10 @@ declare class MutationObserver<TData = unknown, TError = DefaultError, TVariable
479
633
  #private;
480
634
  options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;
481
635
  constructor(client: QueryClient, options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>);
636
+ /**
637
+ * Binds the methods of the result (`mutate` and `reset`) to the observer, so they keep working when
638
+ * destructured from it.
639
+ */
482
640
  protected bindMethods(): void;
483
641
  /**
484
642
  * Updates the observer's options.
@@ -487,7 +645,8 @@ declare class MutationObserver<TData = unknown, TError = DefaultError, TVariable
487
645
  * defined), the observer is reset, detaching it from the mutation it was
488
646
  * observing. Otherwise, if the currently observed mutation is still
489
647
  * `pending`, its options are updated in place as well.
490
- *
648
+ * @param options - The new mutation observer options. They are defaulted with {@link
649
+ * QueryClient#defaultMutationOptions} before being applied.
491
650
  * @example
492
651
  * ```ts
493
652
  * observer.setOptions({
@@ -499,12 +658,18 @@ declare class MutationObserver<TData = unknown, TError = DefaultError, TVariable
499
658
  setOptions(options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): void;
500
659
  protected onSubscribe(): void;
501
660
  protected onUnsubscribe(): void;
502
- /** @internal */
661
+ /**
662
+ * Updates the observer's result when the observed mutation changes, and notifies its listeners.
663
+ * @internal
664
+ * @param action - The action that updated the observed mutation, passed on to the observer's
665
+ * callbacks.
666
+ */
503
667
  onMutationUpdate(action: Action<TData, TError, TVariables, TOnMutateResult>): void;
504
668
  /**
505
669
  * Returns the observer's current result, derived from the observed
506
670
  * mutation's state (or the default, `idle` state if no mutation has been
507
671
  * built yet, e.g. before the first `mutate()` call or after `reset()`).
672
+ * @returns The observer's latest result.
508
673
  */
509
674
  getCurrentResult(): MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
510
675
  /**
@@ -515,13 +680,11 @@ declare class MutationObserver<TData = unknown, TError = DefaultError, TVariable
515
680
  * running to completion and its own callbacks still fire, but this
516
681
  * observer stops reflecting its state and a subsequent `mutate()` call
517
682
  * will build a brand new mutation.
518
- *
683
+ * @see {@link MutationObserver#mutate}
519
684
  * @example
520
685
  * ```ts
521
686
  * observer.reset()
522
687
  * ```
523
- *
524
- * @see {@link MutationObserver#mutate}
525
688
  */
526
689
  reset(): void;
527
690
  /**
@@ -533,7 +696,9 @@ declare class MutationObserver<TData = unknown, TError = DefaultError, TVariable
533
696
  * The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are
534
697
  * invoked once the mutation settles, in addition to any callbacks defined
535
698
  * on the observer's own options.
536
- *
699
+ * @param variables - The variables passed to the `mutationFn`.
700
+ * @param options - Per-call `onSuccess`, `onError`, and `onSettled` callbacks.
701
+ * @returns A promise that resolves with the mutation's data, or rejects with its error.
537
702
  * @example
538
703
  * ```ts
539
704
  * await observer.mutate(
@@ -605,7 +770,6 @@ type MutationCacheListener = (event: MutationCacheNotifyEvent) => void;
605
770
  * Normally, you will not interact with the `MutationCache` directly and instead use a
606
771
  * `QueryClient`. You can subscribe to it (inherited from `Subscribable`) to be informed of
607
772
  * safe/known updates to the cache, such as mutations being added, removed, or updated.
608
- *
609
773
  * @example
610
774
  * ```ts
611
775
  * const unsubscribe = mutationCache.subscribe((event) => {
@@ -617,19 +781,46 @@ declare class MutationCache extends Subscribable<MutationCacheListener> {
617
781
  #private;
618
782
  config: MutationCacheConfig;
619
783
  constructor(config?: MutationCacheConfig);
620
- /** @internal */
784
+ /**
785
+ * Creates a mutation and adds it to the cache.
786
+ * @internal
787
+ * @param client - The client the mutation belongs to, used to default its options.
788
+ * @param options - The mutation options. They are defaulted with {@link
789
+ * QueryClient#defaultMutationOptions}.
790
+ * @param state - The initial state of the mutation, e.g. when restoring a dehydrated mutation.
791
+ * @returns The new mutation, already added to the cache.
792
+ */
621
793
  build<TData, TError, TVariables, TOnMutateResult>(client: QueryClient, options: MutationOptions<TData, TError, TVariables, TOnMutateResult>, state?: MutationState<TData, TError, TVariables, TOnMutateResult>): Mutation<TData, TError, TVariables, TOnMutateResult>;
622
- /** @internal */
794
+ /**
795
+ * Adds a mutation to the cache.
796
+ * @internal
797
+ * @param mutation - The mutation to add. If it has a `scope`, it is queued in that scope.
798
+ */
623
799
  add(mutation: Mutation<any, any, any, any>): void;
624
- /** @internal */
800
+ /**
801
+ * Removes a mutation from the cache.
802
+ * @internal
803
+ * @param mutation - The mutation to remove, also from its scope's queue.
804
+ */
625
805
  remove(mutation: Mutation<any, any, any, any>): void;
626
- /** @internal */
806
+ /**
807
+ * Checks whether a mutation can run now, given the other mutations in its `scope`.
808
+ * @internal
809
+ * @param mutation - The mutation to check.
810
+ * @returns `true` if the mutation has no `scope`, or no other mutation in its scope is pending
811
+ * ahead of it.
812
+ */
627
813
  canRun(mutation: Mutation<any, any, any, any>): boolean;
628
- /** @internal */
814
+ /**
815
+ * Continues the next paused mutation in the same `scope` after a mutation finishes.
816
+ * @internal
817
+ * @param mutation - The mutation that finished.
818
+ * @returns A promise that resolves once the next paused mutation in the same scope has continued,
819
+ * or immediately if there is none.
820
+ */
629
821
  runNext(mutation: Mutation<any, any, any, any>): Promise<unknown>;
630
822
  /**
631
823
  * Removes all mutations from the cache.
632
- *
633
824
  * @example
634
825
  * ```ts
635
826
  * const mutationCache = queryClient.getMutationCache()
@@ -643,7 +834,7 @@ declare class MutationCache extends Subscribable<MutationCacheListener> {
643
834
  *
644
835
  * This is not typically needed for most applications, but can come in handy when needing more
645
836
  * information about a mutation in rare scenarios.
646
- *
837
+ * @returns Every mutation in the cache.
647
838
  * @example
648
839
  * ```ts
649
840
  * const mutationCache = queryClient.getMutationCache()
@@ -658,7 +849,8 @@ declare class MutationCache extends Subscribable<MutationCacheListener> {
658
849
  *
659
850
  * This is not typically needed for most applications, but can come in handy when needing more
660
851
  * information about a mutation in rare scenarios.
661
- *
852
+ * @param filters - The filters to match. `exact` defaults to `true`.
853
+ * @returns The first matching mutation, or `undefined`.
662
854
  * @see {@link MutationCache#findAll}
663
855
  * @example
664
856
  * ```ts
@@ -674,7 +866,8 @@ declare class MutationCache extends Subscribable<MutationCacheListener> {
674
866
  *
675
867
  * This is not typically needed for most applications, but can come in handy when needing more
676
868
  * information about mutations in rare scenarios.
677
- *
869
+ * @param filters - The filters to match. Without filters, every mutation is returned.
870
+ * @returns The matching mutations.
678
871
  * @see {@link MutationCache#find}
679
872
  * @example
680
873
  * ```ts
@@ -684,9 +877,17 @@ declare class MutationCache extends Subscribable<MutationCacheListener> {
684
877
  * ```
685
878
  */
686
879
  findAll(filters?: MutationFilters): Array<Mutation>;
687
- /** @internal */
880
+ /**
881
+ * Notifies every cache listener of an event, in one batch.
882
+ * @internal
883
+ * @param event - The event passed to every listener.
884
+ */
688
885
  notify(event: MutationCacheNotifyEvent): void;
689
- /** @internal */
886
+ /**
887
+ * Continues every paused mutation, e.g. when the app comes back online.
888
+ * @internal
889
+ * @returns A promise that resolves once every paused mutation has continued and settled.
890
+ */
690
891
  resumePausedMutations(): Promise<unknown>;
691
892
  }
692
893
  //#endregion
@@ -768,6 +969,10 @@ interface PauseAction {
768
969
  interface ContinueAction {
769
970
  type: 'continue';
770
971
  }
972
+ /**
973
+ * The actions a mutation dispatches to update its state, e.g. when it starts, fails, pauses, or
974
+ * succeeds.
975
+ */
771
976
  type Action<TData, TError, TVariables, TOnMutateResult> = ContinueAction | ErrorAction<TError> | FailedAction<TError> | PendingAction<TVariables, TOnMutateResult> | PauseAction | SuccessAction<TData>;
772
977
  /**
773
978
  * Represents a single mutation attempt. A `Mutation` holds the mutation's
@@ -778,7 +983,6 @@ type Action<TData, TError, TVariables, TOnMutateResult> = ContinueAction | Error
778
983
  * code typically interacts with mutations indirectly through `QueryClient` or
779
984
  * a framework hook like `useMutation`. Direct access to a `Mutation` instance
780
985
  * is possible via `mutationCache.find()`/`getAll()` for inspecting cache state.
781
- *
782
986
  * @example
783
987
  * ```ts
784
988
  * const mutationCache = queryClient.getMutationCache()
@@ -792,15 +996,29 @@ declare class Mutation<TData = unknown, TError = DefaultError, TVariables = unkn
792
996
  options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;
793
997
  readonly mutationId: number;
794
998
  constructor(config: MutationConfig<TData, TError, TVariables, TOnMutateResult>);
795
- /** @internal */
999
+ /**
1000
+ * Replaces the mutation's options and applies their `gcTime`.
1001
+ * @internal
1002
+ * @param options - The new mutation options.
1003
+ */
796
1004
  setOptions(options: MutationOptions<TData, TError, TVariables, TOnMutateResult>): void;
797
1005
  /**
798
1006
  * The `meta` object passed in the mutation's options, if any.
1007
+ * @returns The mutation's `meta`, or `undefined` if none was set.
799
1008
  */
800
1009
  get meta(): MutationMeta | undefined;
801
- /** @internal */
1010
+ /**
1011
+ * Subscribes an observer to the mutation and stops its garbage collection.
1012
+ * @internal
1013
+ * @param observer - The observer to add. Adding an observer that is already subscribed does
1014
+ * nothing.
1015
+ */
802
1016
  addObserver(observer: MutationObserver<any, any, any, any>): void;
803
- /** @internal */
1017
+ /**
1018
+ * Unsubscribes an observer from the mutation.
1019
+ * @internal
1020
+ * @param observer - The observer to remove. Garbage collection is scheduled afterwards.
1021
+ */
804
1022
  removeObserver(observer: MutationObserver<any, any, any, any>): void;
805
1023
  protected optionalRemove(): void;
806
1024
  /**
@@ -814,15 +1032,15 @@ declare class Mutation<TData = unknown, TError = DefaultError, TVariables = unkn
814
1032
  * this instance), `execute` is called again with the last known variables.
815
1033
  * - Otherwise the mutation has already settled and this resolves immediately
816
1034
  * without running anything again.
817
- *
1035
+ * @returns A promise that settles with the resumed mutation: it rejects if the mutation fails.
1036
+ * It resolves immediately if the mutation has already settled.
1037
+ * @see {@link Mutation#execute}
818
1038
  * @example
819
1039
  * ```ts
820
1040
  * // typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
821
1041
  * const mutation = mutationCache.find({ mutationKey: ['addPost'] })
822
1042
  * await mutation?.continue()
823
1043
  * ```
824
- *
825
- * @see {@link Mutation#execute}
826
1044
  */
827
1045
  continue(): Promise<unknown>;
828
1046
  /**
@@ -845,18 +1063,22 @@ declare class Mutation<TData = unknown, TError = DefaultError, TVariables = unkn
845
1063
  * those four callbacks is individually caught so that a throwing callback
846
1064
  * cannot mask the original error; an `error` action is then dispatched and
847
1065
  * the original error is re-thrown.
848
- *
1066
+ * @param variables - The variables passed to the `mutationFn`.
1067
+ * @returns A promise that resolves with the mutation's data, or rejects with its error.
1068
+ * @see {@link Mutation#continue}
849
1069
  * @example
850
1070
  * ```ts
851
1071
  * // Called internally by `MutationObserver.mutate` and `Mutation.continue` —
852
1072
  * // applications normally trigger mutations through those, not this method.
853
1073
  * const data = await mutation.execute(variables)
854
1074
  * ```
855
- *
856
- * @see {@link Mutation#continue}
857
1075
  */
858
1076
  execute(variables: TVariables): Promise<TData>;
859
1077
  }
1078
+ /**
1079
+ * Returns the initial state of a mutation: `'idle'`, with no data, error, or variables.
1080
+ * @returns The initial mutation state.
1081
+ */
860
1082
  declare function getDefaultState<TData, TError, TVariables, TOnMutateResult>(): MutationState<TData, TError, TVariables, TOnMutateResult>;
861
1083
  //#endregion
862
1084
  //#region src/utils.d.ts
@@ -869,7 +1091,6 @@ type TuplePrefixes<T extends ReadonlyArray<unknown>> = T extends readonly [] ? r
869
1091
  interface QueryFilters<TQueryKey extends QueryKey = QueryKey> {
870
1092
  /**
871
1093
  * Filter to active queries, inactive queries or all queries
872
- *
873
1094
  * @defaultValue 'all'
874
1095
  */
875
1096
  type?: QueryTypeFilter;
@@ -920,7 +1141,6 @@ interface MutationFilters<TData = unknown, TError = DefaultError, TVariables = u
920
1141
  * Either a plain value of type `TOutput`, or a function that receives `TInput` and returns `TOutput`.
921
1142
  * Used for example by `setQueryData`-style updaters, which accept either the new data directly or a
922
1143
  * function that computes it from the previous data. See {@link functionalUpdate}.
923
- *
924
1144
  * @example
925
1145
  * ```ts
926
1146
  * queryClient.setQueryData(['posts'], newPosts)
@@ -932,9 +1152,13 @@ interface MutationFilters<TData = unknown, TError = DefaultError, TVariables = u
932
1152
  * ```
933
1153
  */
934
1154
  type Updater<TInput, TOutput> = TOutput | ((input: TInput) => TOutput);
1155
+ /**
1156
+ * Which queries a filter matches: all of them, only active ones (with enabled observers), or only
1157
+ * inactive ones.
1158
+ */
935
1159
  type QueryTypeFilter = 'all' | 'active' | 'inactive';
936
- /** @deprecated
937
- * use `environmentManager.isServer()` instead.
1160
+ /**
1161
+ * @deprecated use `environmentManager.isServer()` instead.
938
1162
  */
939
1163
  declare const isServer: boolean;
940
1164
  /**
@@ -942,14 +1166,42 @@ declare const isServer: boolean;
942
1166
  */
943
1167
  declare function noop(): void;
944
1168
  declare function noop(): undefined;
1169
+ /**
1170
+ * Resolves an {@link Updater}: calls it with `input` if it is a function, otherwise returns it as
1171
+ * is.
1172
+ * @param updater - The new value, or a function that receives `input` and returns the new value.
1173
+ * @param input - The current value, passed to `updater` if it is a function.
1174
+ * @returns The new value.
1175
+ */
945
1176
  declare function functionalUpdate<TInput, TOutput>(updater: Updater<TInput, TOutput>, input: TInput): TOutput;
1177
+ /**
1178
+ * Checks whether a value can be used as a timeout: a non-negative, finite number.
1179
+ * @param value - The value to check.
1180
+ * @returns `true` if `value` is a number that is `>= 0` and not `Infinity`.
1181
+ */
946
1182
  declare function isValidTimeout(value: unknown): value is number;
1183
+ /**
1184
+ * Calculates how long until data updated at `updatedAt` becomes stale.
1185
+ * @param updatedAt - The timestamp, in milliseconds, at which the data was last updated.
1186
+ * @param staleTime - The time, in milliseconds, after which data is considered stale. Defaults to
1187
+ * `0`.
1188
+ * @returns The remaining time in milliseconds, or `0` if the data is already stale.
1189
+ */
947
1190
  declare function timeUntilStale(updatedAt: number, staleTime?: number): number;
1191
+ /**
1192
+ * Resolves an option that can be given either as a value or as a function of the query, such as
1193
+ * `staleTime`.
1194
+ * @param value - The option value, or a function that receives `query` and returns the value.
1195
+ * @param query - The query passed to `value` if it is a function.
1196
+ * @returns The resolved value, or `undefined` if `value` is `undefined`.
1197
+ */
948
1198
  declare function resolveQueryValue<TValue, TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(value: undefined | TValue | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => TValue), query: Query<TQueryFnData, TError, TData, TQueryKey>): TValue | undefined;
949
1199
  /**
950
1200
  * Checks whether a query matches the given {@link QueryFilters}.
951
1201
  * Every filter that is specified must match; filters that are left unspecified are ignored.
952
- *
1202
+ * @param filters - The filters to check the query against.
1203
+ * @param query - The query to check.
1204
+ * @returns `true` if the query matches every specified filter.
953
1205
  * @example
954
1206
  * ```ts
955
1207
  * const queryCache = queryClient.getQueryCache()
@@ -964,7 +1216,9 @@ declare function matchQuery(filters: QueryFilters, query: Query<any, any, any, a
964
1216
  * Checks whether a mutation matches the given {@link MutationFilters}.
965
1217
  * Every filter that is specified must match; filters that are left unspecified are ignored.
966
1218
  * If a `mutationKey` filter is provided but the mutation has no `mutationKey` of its own, it does not match.
967
- *
1219
+ * @param filters - The filters to check the mutation against.
1220
+ * @param mutation - The mutation to check.
1221
+ * @returns `true` if the mutation matches every specified filter.
968
1222
  * @example
969
1223
  * ```ts
970
1224
  * const mutationCache = queryClient.getMutationCache()
@@ -975,11 +1229,18 @@ declare function matchQuery(filters: QueryFilters, query: Query<any, any, any, a
975
1229
  * ```
976
1230
  */
977
1231
  declare function matchMutation(filters: MutationFilters, mutation: Mutation<any, any>): boolean;
1232
+ /**
1233
+ * Hashes a query key with the query's `queryKeyHashFn` option, falling back to {@link hashKey}.
1234
+ * @param queryKey - The query key to hash.
1235
+ * @param options - The query options that may provide a custom `queryKeyHashFn`.
1236
+ * @returns The query hash, a string that identifies the query in the cache.
1237
+ */
978
1238
  declare function hashQueryKeyByOptions<TQueryKey extends QueryKey = QueryKey>(queryKey: TQueryKey, options?: Pick<QueryOptions<any, any, any, any>, 'queryKeyHashFn'>): string;
979
1239
  /**
980
1240
  * Default query & mutation keys hash function.
981
1241
  * Hashes the value into a stable hash.
982
- *
1242
+ * @param queryKey - The query or mutation key to hash.
1243
+ * @returns The stable hash of the key, as a JSON string.
983
1244
  * @example
984
1245
  * ```ts
985
1246
  * // Object keys are sorted, so key order doesn't affect the hash:
@@ -989,27 +1250,66 @@ declare function hashQueryKeyByOptions<TQueryKey extends QueryKey = QueryKey>(qu
989
1250
  declare function hashKey(queryKey: QueryKey | MutationKey): string;
990
1251
  /**
991
1252
  * Checks if key `b` partially matches with key `a`.
1253
+ * @param a - The key to check, e.g. a query's own key.
1254
+ * @param b - The (partial) key to match against `a`.
1255
+ * @returns `true` if every array element or object property in `b` matches the one at the same
1256
+ * position in `a`.
992
1257
  */
993
1258
  declare function partialMatchKey(a: QueryKey, b: QueryKey): boolean;
994
1259
  /**
995
1260
  * This function returns `a` if `b` is deeply equal.
996
1261
  * If not, it will replace any deeply equal children of `b` with those of `a`.
997
1262
  * This can be used for structural sharing between JSON values for example.
1263
+ * @param a - The previous value, whose deeply equal parts are reused.
1264
+ * @param b - The new value.
1265
+ * @param depth - The current recursion depth. Past a depth of `500`, `b` is returned as is.
1266
+ * @returns `a` if `b` is deeply equal to it, otherwise `b` with its deeply equal parts replaced by
1267
+ * those of `a`.
998
1268
  */
999
1269
  declare function replaceEqualDeep<T>(a: unknown, b: T, depth?: number): T;
1000
1270
  /**
1001
1271
  * Shallow compare objects.
1272
+ * @param a - The first object.
1273
+ * @param b - The second object, or `undefined`.
1274
+ * @returns `true` if both objects have the same keys, with strictly equal values for each key.
1002
1275
  */
1003
1276
  declare function shallowEqualObjects<T extends Record<string, any>>(a: T, b: T | undefined): boolean;
1277
+ /**
1278
+ * Checks whether a value is an array with no holes and no extra properties.
1279
+ * @param value - The value to check.
1280
+ * @returns `true` if `value` is an array whose number of own keys equals its `length`.
1281
+ */
1004
1282
  declare function isPlainArray(value: unknown): value is Array<unknown>;
1283
+ /**
1284
+ * Checks whether a value is a plain object, e.g. created with an object literal or
1285
+ * `Object.create(null)`.
1286
+ * @param o - The value to check.
1287
+ * @returns `true` if `o` is a plain object.
1288
+ */
1005
1289
  declare function isPlainObject(o: any): o is Record<PropertyKey, unknown>;
1290
+ /**
1291
+ * Waits for the given time, using the configured {@link timeoutManager}.
1292
+ * @param timeout - The time to wait, in milliseconds.
1293
+ * @returns A promise that resolves after `timeout` milliseconds.
1294
+ */
1006
1295
  declare function sleep(timeout: number): Promise<void>;
1296
+ /**
1297
+ * Applies a query's `structuralSharing` option when writing new data.
1298
+ * @param prevData - The previously cached data.
1299
+ * @param data - The new data.
1300
+ * @param options - The query options, whose `structuralSharing` decides how the data is merged.
1301
+ * @returns The result of a custom `structuralSharing` function, `data` with its unchanged parts
1302
+ * replaced by those of `prevData` by default, or `data` as is if `structuralSharing` is `false`.
1303
+ * @throws {Error} The error from the default structural sharing, e.g. when the data is not JSON serializable.
1304
+ * Outside production, it is also logged to the console.
1305
+ */
1007
1306
  declare function replaceData<TData, TOptions extends QueryOptions<any, any, any, any>>(prevData: TData | undefined, data: TData, options: TOptions): TData;
1008
1307
  /**
1009
1308
  * Intended to be passed as a query's `placeholderData` option, for example
1010
1309
  * `placeholderData: keepPreviousData`. Instead of resetting the query's data to `undefined` while a new
1011
1310
  * query key is fetching, it keeps displaying the previously fetched data until the new data arrives.
1012
- *
1311
+ * @param previousData - The data of the previous query key, passed by the observer.
1312
+ * @returns The previous data, unchanged.
1013
1313
  * @example
1014
1314
  * ```ts
1015
1315
  * new QueryObserver(queryClient, {
@@ -1020,13 +1320,30 @@ declare function replaceData<TData, TOptions extends QueryOptions<any, any, any,
1020
1320
  * ```
1021
1321
  */
1022
1322
  declare function keepPreviousData<T>(previousData: T | undefined): T | undefined;
1323
+ /**
1324
+ * Returns a new array with `item` added at the end. If that makes the array longer than `max`,
1325
+ * the first item is dropped. Only one item is dropped, so the result can still exceed `max` if
1326
+ * `items` already did.
1327
+ * @param items - The current items.
1328
+ * @param item - The value to append.
1329
+ * @param max - The length above which an item is dropped. `0` (the default) means no limit.
1330
+ * @returns A new array with `item` added.
1331
+ */
1023
1332
  declare function addToEnd<T>(items: Array<T>, item: T, max?: number): Array<T>;
1333
+ /**
1334
+ * Returns a new array with `item` added at the start. If that makes the array longer than `max`,
1335
+ * the last item is dropped. Only one item is dropped, so the result can still exceed `max` if
1336
+ * `items` already did.
1337
+ * @param items - The current items.
1338
+ * @param item - The value to prepend.
1339
+ * @param max - The length above which an item is dropped. `0` (the default) means no limit.
1340
+ * @returns A new array with `item` added.
1341
+ */
1024
1342
  declare function addToStart<T>(items: Array<T>, item: T, max?: number): Array<T>;
1025
1343
  /**
1026
1344
  * Sentinel value that can be passed as a query's `queryFn` to conditionally disable the query (equivalent
1027
1345
  * to `enabled: false`) while preserving full type inference for the query's data. Unlike `enabled: false`,
1028
1346
  * a query disabled via `skipToken` cannot be triggered with `refetch`.
1029
- *
1030
1347
  * @example
1031
1348
  * ```ts
1032
1349
  * new QueryObserver(queryClient, {
@@ -1040,6 +1357,14 @@ declare const skipToken: unique symbol;
1040
1357
  * The type of the {@link skipToken} sentinel value.
1041
1358
  */
1042
1359
  type SkipToken = typeof skipToken;
1360
+ /**
1361
+ * Returns the function to call for a fetch. If there is no `queryFn` but the fetch was started from
1362
+ * an `initialPromise`, that promise is returned instead. If there is no usable `queryFn` (missing or
1363
+ * {@link skipToken}), the returned function rejects with a `Missing queryFn` error.
1364
+ * @param options - The query options with the `queryFn`, and the `queryHash` used in error messages.
1365
+ * @param fetchOptions - The fetch options, which may carry an `initialPromise`.
1366
+ * @returns The function to call for the fetch.
1367
+ */
1043
1368
  declare function ensureQueryFn<TQueryFnData = unknown, TQueryKey extends QueryKey = QueryKey>(options: {
1044
1369
  queryFn?: QueryFunction<TQueryFnData, TQueryKey> | SkipToken;
1045
1370
  queryHash?: string;
@@ -1050,7 +1375,10 @@ declare function ensureQueryFn<TQueryFnData = unknown, TQueryKey extends QueryKe
1050
1375
  * additional context such as the query or mutation) and its result is returned, allowing the throwing
1051
1376
  * behavior to be decided per error. Otherwise, `throwOnError` itself is coerced to a boolean (`undefined`
1052
1377
  * resolves to `false`).
1053
- *
1378
+ * @param throwOnError - The `throwOnError` option: a boolean, a function that decides per error, or
1379
+ * `undefined`.
1380
+ * @param params - The arguments passed to `throwOnError` if it is a function.
1381
+ * @returns Whether the error should be thrown.
1054
1382
  * @example
1055
1383
  * ```ts
1056
1384
  * const throwOnError =
@@ -1060,6 +1388,15 @@ declare function ensureQueryFn<TQueryFnData = unknown, TQueryKey extends QueryKe
1060
1388
  * ```
1061
1389
  */
1062
1390
  declare function shouldThrowError<T extends (...args: Array<any>) => boolean>(throwOnError: boolean | T | undefined, params: Parameters<T>): boolean;
1391
+ /**
1392
+ * Adds a lazy `signal` getter to an object, such as a query function context. The first time
1393
+ * `signal` is read, `onCancelled` is registered for the signal's `abort` event (or called right
1394
+ * away if it is already aborted), so cancellation is only tracked when the signal is actually used.
1395
+ * @param object - The object to add the `signal` property to.
1396
+ * @param getSignal - Returns the `AbortSignal`. Called once, when `signal` is first read.
1397
+ * @param onCancelled - Called when the signal is aborted, if `signal` was read.
1398
+ * @returns The same object, with the `signal` property added.
1399
+ */
1063
1400
  declare function addConsumeAwareSignal<T>(object: T, getSignal: () => AbortSignal, onCancelled: VoidFunction): T & {
1064
1401
  signal: AbortSignal;
1065
1402
  };
@@ -1118,11 +1455,29 @@ interface NotifyEventQueryObserverOptionsUpdated extends NotifyEvent {
1118
1455
  */
1119
1456
  type QueryCacheNotifyEvent = NotifyEventQueryAdded | NotifyEventQueryRemoved | NotifyEventQueryUpdated | NotifyEventQueryObserverAdded | NotifyEventQueryObserverRemoved | NotifyEventQueryObserverResultsUpdated | NotifyEventQueryObserverOptionsUpdated;
1120
1457
  type QueryCacheListener = (event: QueryCacheNotifyEvent) => void;
1458
+ /**
1459
+ * The store a `QueryCache` keeps its queries in, keyed by query hash.
1460
+ */
1121
1461
  interface QueryStore {
1462
+ /**
1463
+ * Returns whether a query with the given hash is stored.
1464
+ */
1122
1465
  has: (queryHash: string) => boolean;
1466
+ /**
1467
+ * Stores a query under its hash.
1468
+ */
1123
1469
  set: (queryHash: string, query: Query) => void;
1470
+ /**
1471
+ * Returns the query with the given hash, if any.
1472
+ */
1124
1473
  get: (queryHash: string) => Query | undefined;
1474
+ /**
1475
+ * Removes the query with the given hash.
1476
+ */
1125
1477
  delete: (queryHash: string) => void;
1478
+ /**
1479
+ * Returns an iterator over all stored queries.
1480
+ */
1126
1481
  values: () => IterableIterator<Query>;
1127
1482
  }
1128
1483
  /**
@@ -1134,7 +1489,6 @@ interface QueryStore {
1134
1489
  * safe/known updates to the cache, such as queries being added, removed, or updated — updates made
1135
1490
  * outside of the cache's own tracked mechanisms (e.g. mutating a query's state object directly) do
1136
1491
  * not notify subscribers.
1137
- *
1138
1492
  * @example
1139
1493
  * ```ts
1140
1494
  * const unsubscribe = queryCache.subscribe((event) => {
@@ -1151,7 +1505,12 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1151
1505
  * builds and adds a new one to the cache if none exists yet. Used by framework adapters and
1152
1506
  * plugins (e.g. broadcast/persistence) that need to get-or-create a `Query` directly, bypassing
1153
1507
  * the reactive `QueryObserver` machinery.
1154
- *
1508
+ * @param client - The client the query belongs to, used to default its options.
1509
+ * @param options - The query options, including the `queryKey`. A new query is created with the
1510
+ * options defaulted by {@link QueryClient#defaultQueryOptions}.
1511
+ * @param state - The initial state of a newly created query, e.g. when hydrating. Ignored if the
1512
+ * query already exists.
1513
+ * @returns The existing or newly created query.
1155
1514
  * @example
1156
1515
  * ```ts
1157
1516
  * const queryCache = queryClient.getQueryCache()
@@ -1163,14 +1522,19 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1163
1522
  * ```
1164
1523
  */
1165
1524
  build<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(client: QueryClient, options: WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryKey'>, state?: QueryState<TData, TError>): Query<TQueryFnData, TError, TData, TQueryKey>;
1166
- /** @internal */
1525
+ /**
1526
+ * Adds a query to the cache.
1527
+ * @internal
1528
+ * @param query - The query to add. If a query with the same hash is already cached, nothing
1529
+ * happens.
1530
+ */
1167
1531
  add(query: Query<any, any, any, any>): void;
1168
1532
  /**
1169
1533
  * Destroys the given `Query` and removes it from the cache, notifying subscribers with a
1170
1534
  * `'removed'` event. A no-op if the query is no longer the one currently stored under its hash
1171
1535
  * (e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror
1172
1536
  * removals across `QueryCache` instances.
1173
- *
1537
+ * @param query - The query to remove.
1174
1538
  * @example
1175
1539
  * ```ts
1176
1540
  * const queryCache = queryClient.getQueryCache()
@@ -1184,7 +1548,6 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1184
1548
  remove(query: Query<any, any, any, any>): void;
1185
1549
  /**
1186
1550
  * Removes all queries from the cache.
1187
- *
1188
1551
  * @example
1189
1552
  * ```ts
1190
1553
  * const queryCache = queryClient.getQueryCache()
@@ -1198,7 +1561,8 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1198
1561
  * exists. Unlike {@link QueryCache#find}, this looks up by the already-computed hash rather
1199
1562
  * than by `QueryFilters`. Used by plugins (e.g. broadcast/hydration) that already have a hash
1200
1563
  * to look up directly.
1201
- *
1564
+ * @param queryHash - The hash of the query to look up.
1565
+ * @returns The query stored under the hash, or `undefined`.
1202
1566
  * @example
1203
1567
  * ```ts
1204
1568
  * const queryCache = queryClient.getQueryCache()
@@ -1210,7 +1574,7 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1210
1574
  get<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(queryHash: string): Query<TQueryFnData, TError, TData, TQueryKey> | undefined;
1211
1575
  /**
1212
1576
  * Returns all queries within the cache.
1213
- *
1577
+ * @returns Every query in the cache.
1214
1578
  * @example
1215
1579
  * ```ts
1216
1580
  * const queryCache = queryClient.getQueryCache()
@@ -1228,7 +1592,9 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1228
1592
  * This is not typically needed for most applications, but can come in handy when needing more
1229
1593
  * information about a query in rare scenarios (e.g. looking at `query.state.dataUpdatedAt` to
1230
1594
  * decide whether a query is fresh enough to be used as an initial value).
1231
- *
1595
+ * @param filters - The filters to match, including the required `queryKey`. `exact` defaults to
1596
+ * `true`.
1597
+ * @returns The first matching query, or `undefined`.
1232
1598
  * @see {@link QueryCache#findAll}
1233
1599
  * @example
1234
1600
  * ```ts
@@ -1244,7 +1610,8 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1244
1610
  *
1245
1611
  * This is not typically needed for most applications, but can come in handy when needing more
1246
1612
  * information about queries in rare scenarios.
1247
- *
1613
+ * @param filters - The filters to match. Without filters, every query is returned.
1614
+ * @returns The matching queries.
1248
1615
  * @see {@link QueryCache#find}
1249
1616
  * @example
1250
1617
  * ```ts
@@ -1254,11 +1621,21 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1254
1621
  * ```
1255
1622
  */
1256
1623
  findAll(filters?: QueryFilters<any>): Array<Query>;
1257
- /** @internal */
1624
+ /**
1625
+ * Notifies every cache listener of an event, in one batch.
1626
+ * @internal
1627
+ * @param event - The event passed to every listener.
1628
+ */
1258
1629
  notify(event: QueryCacheNotifyEvent): void;
1259
- /** @internal */
1630
+ /**
1631
+ * Calls {@link Query#onFocus} on every cached query, in one batch.
1632
+ * @internal
1633
+ */
1260
1634
  onFocus(): void;
1261
- /** @internal */
1635
+ /**
1636
+ * Calls {@link Query#onOnline} on every cached query, in one batch.
1637
+ * @internal
1638
+ */
1262
1639
  onOnline(): void;
1263
1640
  }
1264
1641
  //#endregion
@@ -1267,7 +1644,6 @@ declare class QueryCache extends Subscribable<QueryCacheListener> {
1267
1644
  * `QueryClient` is used to interact with a cache of queries and mutations. It owns a
1268
1645
  * `QueryCache` and a `MutationCache` (creating default ones if none are passed in) and holds
1269
1646
  * the default options that are applied to queries and mutations created through it.
1270
- *
1271
1647
  * @example
1272
1648
  * ```ts
1273
1649
  * const queryClient = new QueryClient({
@@ -1301,7 +1677,9 @@ declare class QueryClient {
1301
1677
  * Returns the number of queries in the cache that are currently fetching, optionally
1302
1678
  * matching a set of filters. This includes background-fetching, loading new pages, and
1303
1679
  * loading more infinite query results.
1304
- *
1680
+ * @param filters - Narrows down which fetching queries are counted. Without filters, every
1681
+ * fetching query is counted.
1682
+ * @returns The number of matching queries whose `fetchStatus` is `'fetching'`.
1305
1683
  * @example
1306
1684
  * ```ts
1307
1685
  * if (queryClient.isFetching()) {
@@ -1313,7 +1691,9 @@ declare class QueryClient {
1313
1691
  /**
1314
1692
  * Returns the number of mutations in the cache that are currently pending, optionally
1315
1693
  * matching a set of filters.
1316
- *
1694
+ * @param filters - Narrows down which pending mutations are counted. Without filters, every
1695
+ * pending mutation is counted.
1696
+ * @returns The number of matching mutations whose `status` is `'pending'`.
1317
1697
  * @example
1318
1698
  * ```ts
1319
1699
  * if (queryClient.isMutating()) {
@@ -1328,12 +1708,18 @@ declare class QueryClient {
1328
1708
  *
1329
1709
  * Hint: Do not use this function inside a component, because it won't receive updates.
1330
1710
  * Use `useQuery` to create a `QueryObserver` that subscribes to changes.
1331
- *
1711
+ * @param queryKey - The query key of the query to read.
1332
1712
  * @returns The cached data for the query, or `undefined` if no query with this key has been observed yet.
1333
1713
  * @see {@link QueryClient#getQueriesData}
1334
1714
  */
1335
1715
  getQueryData<TQueryFnData = unknown, TTaggedQueryKey extends QueryKey = QueryKey, TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(queryKey: TTaggedQueryKey): TInferredQueryFnData | undefined;
1336
1716
  /**
1717
+ * Returns the cached data of a query, or fetches it if there is none. With `revalidateIfStale`,
1718
+ * stale cached data is also refetched in the background.
1719
+ * @param options - The query options. If the query has no cached data yet, it is fetched with
1720
+ * these options.
1721
+ * @returns A promise that resolves to the cached data, or to the fetched data if nothing was
1722
+ * cached yet.
1337
1723
  * @deprecated Use queryClient.query({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
1338
1724
  */
1339
1725
  ensureQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<TData>;
@@ -1347,7 +1733,7 @@ declare class QueryClient {
1347
1733
  * than being inferred. Passing a more specific type is a convenience for call sites that know
1348
1734
  * every matched query holds the same shape — it is not checked against the actual cache
1349
1735
  * contents.
1350
- *
1736
+ * @param filters - The filters that select which queries to read.
1351
1737
  * @returns An array of query key and data pairs. The data is `undefined` for a query with no cached data.
1352
1738
  * @see {@link QueryClient#getQueryData}
1353
1739
  * @example
@@ -1364,14 +1750,12 @@ declare class QueryClient {
1364
1750
  *
1365
1751
  * Updates must be performed immutably: do not mutate `oldData`, or data previously retrieved
1366
1752
  * via {@link QueryClient#getQueryData}, in place.
1367
- *
1368
1753
  * @param queryKey - The query key to set data for.
1369
1754
  * @param updater - Either the new data, or a function that receives the current data (which
1370
1755
  * may be `undefined`) and returns the new data.
1371
1756
  * @param options - Set `updatedAt` to override the timestamp the written data is recorded with.
1372
1757
  * @returns The data that was written, or `undefined` if the updater returned `undefined` — in that case
1373
1758
  * the write is skipped and the cache is left unchanged.
1374
- *
1375
1759
  * @example
1376
1760
  * ```ts
1377
1761
  * queryClient.setQueryData(['posts'], newPosts)
@@ -1380,13 +1764,16 @@ declare class QueryClient {
1380
1764
  * queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost])
1381
1765
  * ```
1382
1766
  */
1383
- setQueryData<TQueryFnData = unknown, TTaggedQueryKey extends QueryKey = QueryKey, TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(queryKey: TTaggedQueryKey, updater: Updater<NoInfer<TInferredQueryFnData> | undefined, NoInfer<TInferredQueryFnData> | undefined>, options?: SetDataOptions): NoInfer<TInferredQueryFnData> | undefined;
1767
+ setQueryData<TQueryFnData = unknown, TTaggedQueryKey extends QueryKey = QueryKey, TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(queryKey: TTaggedQueryKey, updater: Updater<InferDataFromTag<NoInfer<TQueryFnData>, TTaggedQueryKey> | undefined, NoInfer<TInferredQueryFnData> | undefined>, options?: SetDataOptions): NoInfer<TInferredQueryFnData> | undefined;
1384
1768
  /**
1385
1769
  * Synchronous way to immediately update the cached data of multiple queries at once, using
1386
1770
  * filters or partial query key matching. Only queries that already exist and match the given
1387
1771
  * filters are updated; no new cache entries are created. Internally this calls
1388
1772
  * {@link QueryClient#setQueryData} for each matching query.
1389
- *
1773
+ * @param filters - The filters that select which existing queries to update.
1774
+ * @param updater - Either the new data, or a function that receives each matched query's current
1775
+ * data (which may be `undefined`) and returns the new data.
1776
+ * @param options - Set `updatedAt` to override the timestamp the written data is recorded with.
1390
1777
  * @returns One `[queryKey, data]` tuple per matched query, in the same shape and with the same
1391
1778
  * `undefined` case as {@link QueryClient#setQueryData}.
1392
1779
  * @example
@@ -1400,7 +1787,8 @@ declare class QueryClient {
1400
1787
  /**
1401
1788
  * Imperative (non-reactive) way to retrieve an existing query's state. If the query does not
1402
1789
  * exist, `undefined` is returned.
1403
- *
1790
+ * @param queryKey - The query key of the query to read.
1791
+ * @returns The query's state, or `undefined` if no query with this key exists.
1404
1792
  * @example
1405
1793
  * ```ts
1406
1794
  * const state = queryClient.getQueryState(['posts'])
@@ -1413,7 +1801,8 @@ declare class QueryClient {
1413
1801
  * {@link QueryClient#invalidateQueries} or {@link QueryClient#refetchQueries}, this removes
1414
1802
  * matching queries from the cache instead of refetching them. Without filters, every query in
1415
1803
  * the cache is removed.
1416
- *
1804
+ * @param filters - The filters that select which queries to remove. Without filters, every query
1805
+ * is removed.
1417
1806
  * @example
1418
1807
  * ```ts
1419
1808
  * queryClient.removeQueries({ queryKey: ['posts'], exact: true })
@@ -1424,7 +1813,11 @@ declare class QueryClient {
1424
1813
  * Resets queries matching the given filters back to their initial state (e.g. any
1425
1814
  * `initialData`), notifying subscribers rather than removing them. Active queries among the
1426
1815
  * matched set are then refetched, and the returned promise resolves once that refetch settles.
1427
- *
1816
+ * @param filters - The filters that select which queries to reset. Without filters, every query
1817
+ * is reset.
1818
+ * @param options - Passed to the refetch of the active matched queries, e.g. `cancelRefetch` and
1819
+ * `throwOnError`.
1820
+ * @returns A promise that resolves once the refetch of the active matched queries settles.
1428
1821
  * @example
1429
1822
  * ```ts
1430
1823
  * await queryClient.resetQueries({ queryKey: ['posts'], exact: true })
@@ -1438,7 +1831,11 @@ declare class QueryClient {
1438
1831
  * reverted to its state before the outgoing fetch started.
1439
1832
  *
1440
1833
  * The returned promise never rejects, even if individual cancellations fail.
1441
- *
1834
+ * @param filters - The filters that select which queries to cancel. Without filters, every query
1835
+ * is cancelled.
1836
+ * @param cancelOptions - Passed to each matched query's cancellation. `revert` defaults to
1837
+ * `true`.
1838
+ * @returns A promise that resolves once every cancellation has settled.
1442
1839
  * @example
1443
1840
  * ```ts
1444
1841
  * await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })
@@ -1452,7 +1849,12 @@ declare class QueryClient {
1452
1849
  * Unless `filters.refetchType` is `'none'`, matching queries are then refetched via
1453
1850
  * {@link QueryClient#refetchQueries}, using `filters.refetchType` if set, otherwise
1454
1851
  * `filters.type`, otherwise `'active'`.
1455
- *
1852
+ * @param filters - The filters that select which queries to invalidate, plus `refetchType` to
1853
+ * control which of them to refetch afterwards. Without filters, every query is invalidated.
1854
+ * @param options - Passed to {@link QueryClient#refetchQueries}, e.g. `cancelRefetch` and
1855
+ * `throwOnError`.
1856
+ * @returns A promise that resolves once the refetch settles, or immediately if `refetchType` is
1857
+ * `'none'`.
1456
1858
  * @example
1457
1859
  * ```ts
1458
1860
  * await queryClient.invalidateQueries({ queryKey: ['posts'], refetchType: 'active' })
@@ -1467,7 +1869,11 @@ declare class QueryClient {
1467
1869
  * By default (`cancelRefetch: true`), a currently running fetch is cancelled before the new
1468
1870
  * one starts. The returned promise resolves once all matching queries have settled; it does
1469
1871
  * not reject on individual query failures unless `throwOnError` is set.
1470
- *
1872
+ * @param filters - The filters that select which queries to refetch. Without filters, every query
1873
+ * in the cache is included.
1874
+ * @param options - Set `cancelRefetch` to `false` to keep a running fetch instead of cancelling
1875
+ * it, and `throwOnError` to `true` to reject when a refetch fails.
1876
+ * @returns A promise that resolves once every matched query has settled.
1471
1877
  * @example
1472
1878
  * ```ts
1473
1879
  * // refetch all active queries partially matching a query key:
@@ -1496,7 +1902,10 @@ declare class QueryClient {
1496
1902
  *
1497
1903
  * This method replaces the deprecated `fetchQuery`, and — combined with
1498
1904
  * `{ staleTime: 'static' }` — the deprecated `ensureQueryData`.
1499
- *
1905
+ * @param options - The query options, including the `queryKey` and the `queryFn` used if the
1906
+ * query needs to fetch.
1907
+ * @returns A promise that resolves to the data, or to the result of `select` if provided. It
1908
+ * rejects with the error from the fetch or from `select`.
1500
1909
  * @example
1501
1910
  * ```ts
1502
1911
  * try {
@@ -1508,10 +1917,21 @@ declare class QueryClient {
1508
1917
  */
1509
1918
  query<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never>(options: QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>): Promise<TData>;
1510
1919
  /**
1920
+ * Fetches and caches a query, or returns its cached data if it isn't stale. Unlike in observers,
1921
+ * the fetch isn't retried unless `retry` is set.
1922
+ * @param options - The query options, including the `queryKey` and the `queryFn` used if the
1923
+ * query needs to fetch.
1924
+ * @returns A promise that resolves to the cached or fetched data, or rejects with the fetch
1925
+ * error.
1511
1926
  * @deprecated Use queryClient.query(options) instead. This method will be removed in the next major version.
1512
1927
  */
1513
1928
  fetchQuery<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData>;
1514
1929
  /**
1930
+ * Fetches and caches a query like {@link QueryClient#fetchQuery}, but ignores the result and any
1931
+ * error.
1932
+ * @param options - The query options, including the `queryKey` and the `queryFn` used if the
1933
+ * query needs to fetch.
1934
+ * @returns A promise that resolves once the fetch settles. It never rejects.
1515
1935
  * @deprecated Use queryClient.query(options) instead. You can swallow errors with `.catch(noop)`. This method will be removed in the next major version.
1516
1936
  */
1517
1937
  prefetchQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<void>;
@@ -1525,7 +1945,10 @@ declare class QueryClient {
1525
1945
  *
1526
1946
  * This method replaces the deprecated `fetchInfiniteQuery`, and — combined with
1527
1947
  * `{ staleTime: 'static' }` — the deprecated `ensureInfiniteQueryData`.
1528
- *
1948
+ * @param options - The infinite query options, including the `queryKey`, the `queryFn`, and the
1949
+ * `initialPageParam`.
1950
+ * @returns A promise that resolves to the {@link InfiniteData}, or to the result of `select` if
1951
+ * provided. It rejects with the error from the fetch or from `select`.
1529
1952
  * @example
1530
1953
  * ```ts
1531
1954
  * try {
@@ -1538,21 +1961,37 @@ declare class QueryClient {
1538
1961
  */
1539
1962
  infiniteQuery<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<Array<TData> extends Array<InfiniteData<TQueryFnData>> ? InfiniteData<TQueryFnData, TPageParam> : TData>;
1540
1963
  /**
1964
+ * Fetches and caches an infinite query, or returns its cached data if it isn't stale.
1965
+ * @param options - The infinite query options, including the `queryKey`, the `queryFn`, and the
1966
+ * `initialPageParam`.
1967
+ * @returns A promise that resolves to the cached or fetched {@link InfiniteData}, or rejects with
1968
+ * the fetch error.
1541
1969
  * @deprecated Use queryClient.infiniteQuery(options) instead. This method will be removed in the next major version.
1542
1970
  */
1543
1971
  fetchInfiniteQuery<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;
1544
1972
  /**
1973
+ * Fetches and caches an infinite query like {@link QueryClient#fetchInfiniteQuery}, but ignores
1974
+ * the result and any error.
1975
+ * @param options - The infinite query options, including the `queryKey`, the `queryFn`, and the
1976
+ * `initialPageParam`.
1977
+ * @returns A promise that resolves once the fetch settles. It never rejects.
1545
1978
  * @deprecated Use queryClient.infiniteQuery(options) instead. You can swallow errors with `.catch(noop)`. This method will be removed in the next major version.
1546
1979
  */
1547
1980
  prefetchInfiniteQuery<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<void>;
1548
1981
  /**
1982
+ * Returns the cached data of an infinite query, or fetches it if there is none. With
1983
+ * `revalidateIfStale`, stale cached data is also refetched in the background.
1984
+ * @param options - The infinite query options. If the query has no cached data yet, it is fetched
1985
+ * with these options.
1986
+ * @returns A promise that resolves to the cached {@link InfiniteData}, or to the fetched data if
1987
+ * nothing was cached yet.
1549
1988
  * @deprecated Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
1550
1989
  */
1551
1990
  ensureInfiniteQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown>(options: EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;
1552
1991
  /**
1553
1992
  * Resumes mutations that were paused because there was no network connection. Does nothing
1554
1993
  * (resolving immediately) if the client is currently offline.
1555
- *
1994
+ * @returns A promise that resolves once the resumed mutations have settled.
1556
1995
  * @example
1557
1996
  * ```ts
1558
1997
  * import { QueryClient } from '@tanstack/query-core'
@@ -1564,7 +2003,7 @@ declare class QueryClient {
1564
2003
  resumePausedMutations(): Promise<unknown>;
1565
2004
  /**
1566
2005
  * Returns the query cache this client is connected to.
1567
- *
2006
+ * @returns The {@link QueryCache} instance.
1568
2007
  * @example
1569
2008
  * ```ts
1570
2009
  * import { QueryClient } from '@tanstack/query-core'
@@ -1577,7 +2016,7 @@ declare class QueryClient {
1577
2016
  getQueryCache(): QueryCache;
1578
2017
  /**
1579
2018
  * Returns the mutation cache this client is connected to.
1580
- *
2019
+ * @returns The {@link MutationCache} instance.
1581
2020
  * @example
1582
2021
  * ```ts
1583
2022
  * import { QueryClient } from '@tanstack/query-core'
@@ -1591,7 +2030,7 @@ declare class QueryClient {
1591
2030
  /**
1592
2031
  * Returns the default options that were set when creating the client, or via
1593
2032
  * {@link QueryClient#setDefaultOptions}.
1594
- *
2033
+ * @returns The client's current default options.
1595
2034
  * @example
1596
2035
  * ```ts
1597
2036
  * import { QueryClient } from '@tanstack/query-core'
@@ -1604,7 +2043,7 @@ declare class QueryClient {
1604
2043
  /**
1605
2044
  * Dynamically sets the default options for this client, overwriting any previously defined
1606
2045
  * default options.
1607
- *
2046
+ * @param options - The new default options for queries and mutations.
1608
2047
  * @see {@link QueryClient#getDefaultOptions}
1609
2048
  * @example
1610
2049
  * ```ts
@@ -1626,7 +2065,8 @@ declare class QueryClient {
1626
2065
  * registration order by {@link QueryClient#getQueryDefaults}, so register defaults from the
1627
2066
  * most generic key to the least generic one — more specific defaults should be registered
1628
2067
  * after more generic ones so they take precedence.
1629
- *
2068
+ * @param queryKey - The query key that query keys are partially matched against.
2069
+ * @param options - The default options applied to matching queries.
1630
2070
  * @example
1631
2071
  * ```ts
1632
2072
  * queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })
@@ -1639,7 +2079,9 @@ declare class QueryClient {
1639
2079
  * Returns the default options registered for queries whose query key partially matches the
1640
2080
  * given `queryKey`, via {@link QueryClient#setQueryDefaults}. If multiple registered defaults
1641
2081
  * match, they are merged together in registration order.
1642
- *
2082
+ * @param queryKey - The query key to look up registered defaults for.
2083
+ * @returns The merged default options of every registration that matches, or an empty object if
2084
+ * none match.
1643
2085
  * @example
1644
2086
  * ```ts
1645
2087
  * const defaultOptions = queryClient.getQueryDefaults(['posts'])
@@ -1650,7 +2092,8 @@ declare class QueryClient {
1650
2092
  * Sets default options for mutations whose mutation key partially matches the given
1651
2093
  * `mutationKey`. As with {@link QueryClient#setQueryDefaults}, the order of registration
1652
2094
  * matters when several registered defaults match the same mutation key.
1653
- *
2095
+ * @param mutationKey - The mutation key that mutation keys are partially matched against.
2096
+ * @param options - The default options applied to matching mutations.
1654
2097
  * @see {@link QueryClient#getMutationDefaults}
1655
2098
  * @example
1656
2099
  * ```ts
@@ -1662,7 +2105,9 @@ declare class QueryClient {
1662
2105
  * Returns the default options registered for mutations whose mutation key partially matches
1663
2106
  * the given `mutationKey`, via {@link QueryClient#setMutationDefaults}. If multiple registered
1664
2107
  * defaults match, they are merged together in registration order.
1665
- *
2108
+ * @param mutationKey - The mutation key to look up registered defaults for.
2109
+ * @returns The merged default options of every registration that matches, or an empty object if
2110
+ * none match.
1666
2111
  * @example
1667
2112
  * ```ts
1668
2113
  * const defaultOptions = queryClient.getMutationDefaults(['addPost'])
@@ -1671,21 +2116,25 @@ declare class QueryClient {
1671
2116
  getMutationDefaults(mutationKey: MutationKey): OmitKeyof<MutationObserverOptions<any, any, any, any>, 'mutationKey'>;
1672
2117
  /**
1673
2118
  * Called by framework adapters (e.g. inside `useQuery`) to resolve the options passed by the
1674
- * caller into their final, defaulted form: merging `queryClient.setQueryDefaults` for the
1675
- * given `queryKey`, then the client's own `defaultOptions.queries`, then the caller's options
1676
- * on top. A no-op if the options are already defaulted (`_defaulted: true`).
2119
+ * caller into their final, defaulted form: merging the client's own `defaultOptions.queries`,
2120
+ * then `queryClient.setQueryDefaults` for the given `queryKey`, then the caller's options on
2121
+ * top. A no-op if the options are already defaulted (`_defaulted: true`).
2122
+ * @param options - The query options passed by the caller.
2123
+ * @returns The defaulted options, with `queryHash` and dependent defaults (e.g.
2124
+ * `refetchOnReconnect`) filled in.
1677
2125
  */
1678
2126
  defaultQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never>(options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam> | DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
1679
2127
  /**
1680
2128
  * The mutation counterpart of {@link QueryClient#defaultQueryOptions}. Called by framework
1681
- * adapters (e.g. inside `useMutation`) to merge `queryClient.setMutationDefaults` for the
1682
- * given `mutationKey`, then the client's `defaultOptions.mutations`, then the caller's options
1683
- * on top. A no-op if the options are already defaulted (`_defaulted: true`).
2129
+ * adapters (e.g. inside `useMutation`) to merge the client's `defaultOptions.mutations`, then
2130
+ * `queryClient.setMutationDefaults` for the given `mutationKey`, then the caller's options on
2131
+ * top. A no-op if the options are already defaulted (`_defaulted: true`).
2132
+ * @param options - The mutation options passed by the caller.
2133
+ * @returns The defaulted options.
1684
2134
  */
1685
2135
  defaultMutationOptions<T extends MutationOptions<any, any, any, any>>(options?: T): T;
1686
2136
  /**
1687
2137
  * Clears both the query cache and the mutation cache this client is connected to.
1688
- *
1689
2138
  * @example
1690
2139
  * ```ts
1691
2140
  * import { QueryClient } from '@tanstack/query-core'
@@ -1710,15 +2159,44 @@ interface RetryerConfig<TData = unknown, TError = DefaultError> {
1710
2159
  networkMode: NetworkMode | undefined;
1711
2160
  canRun: () => boolean;
1712
2161
  }
2162
+ /**
2163
+ * Runs a function with retries, and can pause, continue, or cancel it. Queries and mutations use
2164
+ * one for each fetch or execution.
2165
+ */
1713
2166
  interface Retryer<TData = unknown> {
2167
+ /**
2168
+ * The promise that resolves with the data, or rejects once retries are exhausted or it is
2169
+ * cancelled.
2170
+ */
1714
2171
  promise: Promise<TData>;
2172
+ /**
2173
+ * Cancels the run, rejecting `promise` with a `CancelledError`.
2174
+ */
1715
2175
  cancel: (cancelOptions?: CancelOptions) => void;
2176
+ /**
2177
+ * Resumes a paused run, and returns `promise`.
2178
+ */
1716
2179
  continue: () => Promise<unknown>;
2180
+ /**
2181
+ * Stops further retries. The current attempt still finishes.
2182
+ */
1717
2183
  cancelRetry: () => void;
2184
+ /**
2185
+ * Allows retries again after `cancelRetry`.
2186
+ */
1718
2187
  continueRetry: () => void;
2188
+ /**
2189
+ * Returns whether the run can start now, based on the network mode and `canRun`.
2190
+ */
1719
2191
  canStart: () => boolean;
2192
+ /**
2193
+ * Starts the run, or waits until it can start, and returns `promise`.
2194
+ */
1720
2195
  start: () => Promise<TData>;
1721
- status: () => 'pending' | 'resolved' | 'rejected';
2196
+ /**
2197
+ * Returns whether `promise` is still pending, resolved, or rejected.
2198
+ */
2199
+ status: () => 'pending' | 'resolved' | 'rejected';
1722
2200
  }
1723
2201
  /** @inline */
1724
2202
  type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>;
@@ -1728,6 +2206,11 @@ type ShouldRetryFunction<TError = DefaultError> = (failureCount: number, error:
1728
2206
  type RetryDelayValue<TError> = number | RetryDelayFunction<TError>;
1729
2207
  /** @inline */
1730
2208
  type RetryDelayFunction<TError = DefaultError> = (failureCount: number, error: TError) => number;
2209
+ /**
2210
+ * Checks whether a fetch can run for the given network mode.
2211
+ * @param networkMode - The `networkMode` option. Defaults to `'online'`.
2212
+ * @returns `true` if the network mode is not `'online'`, or if it is and the client is online.
2213
+ */
1731
2214
  declare function canFetch(networkMode: NetworkMode | undefined): boolean;
1732
2215
  /**
1733
2216
  * The error thrown by a `Retryer` (and surfaced to `query.promise`/`mutation`) when a fetch is cancelled, e.g. via
@@ -1753,15 +2236,42 @@ declare class CancelledError extends Error {
1753
2236
  constructor(options?: CancelOptions);
1754
2237
  }
1755
2238
  /**
2239
+ * Checks whether a value is a `CancelledError`.
2240
+ * @param value - The value to check.
2241
+ * @returns `true` if `value` is a `CancelledError`.
1756
2242
  * @deprecated Use instanceof `CancelledError` instead.
1757
2243
  */
1758
2244
  declare function isCancelledError(value: any): value is CancelledError;
2245
+ /**
2246
+ * Creates a retryer, which runs a function and retries it on failure according to the `retry` and
2247
+ * `retryDelay` options. It pauses while the network mode doesn't allow fetching or `canRun` returns
2248
+ * `false`, and can be cancelled. Queries and mutations use it to run their `queryFn` and
2249
+ * `mutationFn`.
2250
+ * @param config - The function to run, the retry options, and the callbacks for failures, pausing,
2251
+ * continuing, and cancellation.
2252
+ * @returns The retryer, whose `promise` settles with the result of the function.
2253
+ */
1759
2254
  declare function createRetryer<TData = unknown, TError = DefaultError>(config: RetryerConfig<TData, TError>): Retryer<TData>;
1760
2255
  //#endregion
1761
2256
  //#region src/types.d.ts
2257
+ /**
2258
+ * Excludes `undefined` from `T`. Used where a value must be defined, such as the data type that a
2259
+ * defined `initialData` resolves to.
2260
+ */
1762
2261
  type NonUndefinedGuard<T> = T extends undefined ? never : T;
2262
+ /**
2263
+ * Like `Omit`, but applied to each member of a union separately, so each member keeps its own keys.
2264
+ */
1763
2265
  type DistributiveOmit<TObject, TKey extends keyof TObject> = TObject extends any ? Omit<TObject, TKey> : never;
2266
+ /**
2267
+ * Like `Omit`, but by default (`'strictly'`) `TKey` must be a key of `TObject`, so omitting a key
2268
+ * that doesn't exist is a type error. Pass `'safely'` to allow other keys too.
2269
+ */
1764
2270
  type OmitKeyof<TObject, TKey extends (TStrictly extends 'safely' ? keyof TObject | (string & Record<never, never>) | (number & Record<never, never>) | (symbol & Record<never, never>) : keyof TObject), TStrictly extends 'strictly' | 'safely' = 'strictly'> = Omit<TObject, TKey>;
2271
+ /**
2272
+ * Replaces the types of the properties of `TTargetA` that also exist in `TTargetB` with their types
2273
+ * in `TTargetB`. Properties that only exist in `TTargetB` are not added.
2274
+ */
1765
2275
  type Override<TTargetA, TTargetB> = { [AKey in keyof TTargetA]: AKey extends keyof TTargetB ? TTargetB[AKey] : TTargetA[AKey]; };
1766
2276
  /**
1767
2277
  * The interface to augment via declaration merging to override Query's default types repository-wide.
@@ -1798,23 +2308,62 @@ type QueryKey = Register extends {
1798
2308
  queryKey: infer TQueryKey;
1799
2309
  } ? TQueryKey extends ReadonlyArray<unknown> ? TQueryKey : TQueryKey extends Array<unknown> ? TQueryKey : ReadonlyArray<unknown> : ReadonlyArray<unknown>;
1800
2310
  declare const dataTagSymbol: unique symbol;
2311
+ /**
2312
+ * The type of the `dataTagSymbol` key, under which a {@link DataTag} stores its data type.
2313
+ */
1801
2314
  type dataTagSymbol = typeof dataTagSymbol;
1802
2315
  declare const dataTagErrorSymbol: unique symbol;
2316
+ /**
2317
+ * The type of the `dataTagErrorSymbol` key, under which a {@link DataTag} stores its error type.
2318
+ */
1803
2319
  type dataTagErrorSymbol = typeof dataTagErrorSymbol;
1804
2320
  declare const unsetMarker: unique symbol;
2321
+ /**
2322
+ * The type of `unsetMarker`, the default error type of a {@link DataTag}. It marks that no error
2323
+ * type was tagged.
2324
+ */
1805
2325
  type UnsetMarker = typeof unsetMarker;
2326
+ /**
2327
+ * Matches any type that has been tagged with {@link DataTag}, whatever its data and error types.
2328
+ */
1806
2329
  type AnyDataTag = {
2330
+ /**
2331
+ * The data type the key was tagged with.
2332
+ */
1807
2333
  [dataTagSymbol]: any;
2334
+ /**
2335
+ * The error type the key was tagged with.
2336
+ */
1808
2337
  [dataTagErrorSymbol]: any;
1809
2338
  };
2339
+ /**
2340
+ * Tags `TType` (usually a query key) with a data type and an optional error type, so that APIs that
2341
+ * receive it, like `queryClient.getQueryData`, can infer them. A type that is already tagged is
2342
+ * returned as is.
2343
+ */
1810
2344
  type DataTag<TType, TValue, TError = UnsetMarker> = TType extends AnyDataTag ? TType : TType & {
1811
2345
  [dataTagSymbol]: TValue;
1812
2346
  [dataTagErrorSymbol]: TError;
1813
2347
  };
2348
+ /**
2349
+ * An object whose `queryKey` is tagged with {@link DataTag}, like the options returned by
2350
+ * `queryOptions`.
2351
+ */
1814
2352
  type QueryKeyWithDataTag<TQueryKey extends QueryKey = QueryKey, TQueryFnData = unknown, TError = DefaultError> = {
2353
+ /**
2354
+ * The query key, tagged with the query's data and error types.
2355
+ */
1815
2356
  queryKey: DataTag<TQueryKey, TQueryFnData, TError>;
1816
2357
  };
2358
+ /**
2359
+ * The data type tagged on a query key by {@link DataTag}, or `TQueryFnData` if the key is not
2360
+ * tagged.
2361
+ */
1817
2362
  type InferDataFromTag<TQueryFnData, TTaggedQueryKey extends QueryKey> = TTaggedQueryKey extends DataTag<unknown, infer TaggedValue, unknown> ? TaggedValue : TQueryFnData;
2363
+ /**
2364
+ * The error type tagged on a query key by {@link DataTag}, or `TError` if the key is not tagged or
2365
+ * was tagged without an error type.
2366
+ */
1818
2367
  type InferErrorFromTag<TError, TTaggedQueryKey extends QueryKey> = TTaggedQueryKey extends DataTag<unknown, unknown, infer TaggedError> ? TaggedError extends UnsetMarker ? TError : TaggedError : TError;
1819
2368
  /** @inline */
1820
2369
  type QueryFunction<T = unknown, TQueryKey extends QueryKey = QueryKey, TPageParam = never> = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>;
@@ -1826,6 +2375,11 @@ type StaleTimeFunction<TQueryFnData = unknown, TError = DefaultError, TData = TQ
1826
2375
  type QueryBooleanOption<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = boolean | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean);
1827
2376
  /** @inline */
1828
2377
  type QueryPersister<T = unknown, TQueryKey extends QueryKey = QueryKey, TPageParam = never> = [TPageParam] extends [never] ? (queryFn: QueryFunction<T, TQueryKey, never>, context: QueryFunctionContext<TQueryKey>, query: Query) => T | Promise<T> : (queryFn: QueryFunction<T, TQueryKey, TPageParam>, context: QueryFunctionContext<TQueryKey>, query: Query) => T | Promise<T>;
2378
+ /**
2379
+ * The object passed to `queryFn`: the `QueryClient`, the `queryKey`, an `AbortSignal` that aborts
2380
+ * when the query is cancelled, the query's `meta`, and for infinite queries the `pageParam` of the
2381
+ * page being fetched.
2382
+ */
1829
2383
  type QueryFunctionContext<TQueryKey extends QueryKey = QueryKey, TPageParam = never> = [TPageParam] extends [never] ? {
1830
2384
  client: QueryClient;
1831
2385
  queryKey: TQueryKey;
@@ -1854,6 +2408,11 @@ type InitialDataFunction<T> = () => T | undefined;
1854
2408
  type NonFunctionGuard<T> = T extends Function ? never : T;
1855
2409
  /** @inline */
1856
2410
  type PlaceholderDataFunction<TQueryFnData = unknown, TError = DefaultError, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = (previousData: TQueryData | undefined, previousQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined) => TQueryData | undefined;
2411
+ /**
2412
+ * The `placeholderData` function of a query in `useQueries` and its counterparts. Unlike
2413
+ * {@link PlaceholderDataFunction}, it receives no previous data or query, because the number of
2414
+ * queries can differ between renders.
2415
+ */
1857
2416
  type QueriesPlaceholderDataFunction<TQueryData> = (previousData: undefined, previousQuery: undefined) => TQueryData | undefined;
1858
2417
  /** @inline */
1859
2418
  type QueryKeyHashFunction<TQueryKey extends QueryKey> = (queryKey: TQueryKey) => string;
@@ -1866,7 +2425,13 @@ type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (lastPage: T
1866
2425
  * `pages` and `pageParams` are index-aligned — `pageParams[i]` is the param that produced `pages[i]`.
1867
2426
  */
1868
2427
  interface InfiniteData<TData, TPageParam = unknown> {
2428
+ /**
2429
+ * The data of every page fetched so far, in order.
2430
+ */
1869
2431
  pages: Array<TData>;
2432
+ /**
2433
+ * The page param each page was fetched with, aligned by index with `pages`.
2434
+ */
1870
2435
  pageParams: Array<TPageParam>;
1871
2436
  }
1872
2437
  /**
@@ -1880,6 +2445,10 @@ type QueryMeta = Register extends {
1880
2445
  type NetworkMode = 'online' | 'always' | 'offlineFirst';
1881
2446
  /** @inline */
1882
2447
  type NotifyOnChangeProps = Array<keyof InfiniteQueryObserverResult> | 'all' | undefined | (() => Array<keyof InfiniteQueryObserverResult> | 'all' | undefined);
2448
+ /**
2449
+ * The options of a query itself — its `queryKey`, `queryFn`, retries, `gcTime`, `initialData`,
2450
+ * `meta`, and so on — shared by observers and the `QueryClient` methods that fetch queries.
2451
+ */
1883
2452
  interface QueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> {
1884
2453
  /**
1885
2454
  * If `false`, failed queries will not retry by default.
@@ -1904,7 +2473,6 @@ interface QueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQ
1904
2473
  retryDelay?: RetryDelayValue<TError>;
1905
2474
  /**
1906
2475
  * Controls whether a query is allowed to run based on the current network connectivity.
1907
- *
1908
2476
  * @defaultValue 'online'
1909
2477
  * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
1910
2478
  */
@@ -1970,7 +2538,6 @@ interface QueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQ
1970
2538
  /**
1971
2539
  * Set this to `false` to disable structural sharing between query results.
1972
2540
  * Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic.
1973
- *
1974
2541
  * @defaultValue true
1975
2542
  */
1976
2543
  structuralSharing?: boolean | ((oldData: unknown | undefined, newData: unknown) => unknown);
@@ -1988,6 +2555,9 @@ interface QueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQ
1988
2555
  */
1989
2556
  maxPages?: number;
1990
2557
  }
2558
+ /**
2559
+ * Holds the `initialPageParam` option that every infinite query requires.
2560
+ */
1991
2561
  interface InitialPageParam<TPageParam = unknown> {
1992
2562
  /**
1993
2563
  * The page param to start from when an infinite query has no pages yet.
@@ -1998,6 +2568,10 @@ interface InitialPageParam<TPageParam = unknown> {
1998
2568
  */
1999
2569
  initialPageParam: TPageParam;
2000
2570
  }
2571
+ /**
2572
+ * The page param options of an infinite query: `initialPageParam`, and the `getNextPageParam` and
2573
+ * `getPreviousPageParam` functions that compute the params of the pages around it.
2574
+ */
2001
2575
  interface InfiniteQueryPageParamsOptions<TQueryFnData = unknown, TPageParam = unknown> extends InitialPageParam<TPageParam> {
2002
2576
  /**
2003
2577
  * This function can be set to automatically get the previous cursor for infinite queries.
@@ -2012,12 +2586,16 @@ interface InfiniteQueryPageParamsOptions<TQueryFnData = unknown, TPageParam = un
2012
2586
  }
2013
2587
  /** @inline */
2014
2588
  type ThrowOnError<TQueryFnData, TError, TQueryData, TQueryKey extends QueryKey> = boolean | ((error: TError, query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean);
2589
+ /**
2590
+ * The options of a `QueryObserver`, and of the hooks built on it like `useQuery`: the
2591
+ * {@link QueryOptions} of the query, plus options that control the observer, such as `enabled`,
2592
+ * `staleTime`, `refetchInterval`, `select`, and `placeholderData`.
2593
+ */
2015
2594
  interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> extends WithRequired<QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey, TPageParam>, 'queryKey'> {
2016
2595
  /**
2017
2596
  * Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys.
2018
2597
  * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
2019
2598
  * Accepts a boolean or function that returns a boolean.
2020
- *
2021
2599
  * @defaultValue true
2022
2600
  */
2023
2601
  enabled?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>;
@@ -2026,20 +2604,17 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2026
2604
  * If set to `Infinity`, the data will never be considered stale.
2027
2605
  * If set to `'static'`, the data will never be considered stale.
2028
2606
  * If set to a function, the function will be executed with the query to compute a `staleTime`.
2029
- *
2030
2607
  * @defaultValue 0
2031
2608
  */
2032
2609
  staleTime?: StaleTimeFunction<TQueryFnData, TError, TQueryData, TQueryKey>;
2033
2610
  /**
2034
2611
  * If set to a number, the query will continuously refetch at this frequency in milliseconds.
2035
2612
  * If set to a function, the function will be executed with the latest data and query to compute a frequency
2036
- *
2037
2613
  * @defaultValue false
2038
2614
  */
2039
2615
  refetchInterval?: number | false | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => number | false | undefined);
2040
2616
  /**
2041
2617
  * If set to `true`, the query will continue to refetch while their tab/window is in the background.
2042
- *
2043
2618
  * @defaultValue false
2044
2619
  */
2045
2620
  refetchIntervalInBackground?: boolean;
@@ -2048,7 +2623,6 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2048
2623
  * If set to `false`, the query will not refetch on window focus.
2049
2624
  * If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used).
2050
2625
  * If set to a function, the function will be executed with the latest data and query to compute the value.
2051
- *
2052
2626
  * @defaultValue true
2053
2627
  */
2054
2628
  refetchOnWindowFocus?: boolean | 'always' | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean | 'always');
@@ -2066,14 +2640,12 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2066
2640
  * If set to `false`, will disable additional instances of a query to trigger background refetch.
2067
2641
  * If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used).
2068
2642
  * If set to a function, the function will be executed with the latest data and query to compute the value
2069
- *
2070
2643
  * @defaultValue true
2071
2644
  */
2072
2645
  refetchOnMount?: boolean | 'always' | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean | 'always');
2073
2646
  /**
2074
2647
  * If set to `false`, the query will not be retried on mount if it contains an error.
2075
2648
  * If set to a function, the function will be executed with the query to compute the value.
2076
- *
2077
2649
  * @defaultValue true
2078
2650
  */
2079
2651
  retryOnMount?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>;
@@ -2092,7 +2664,6 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2092
2664
  * If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary.
2093
2665
  * If set to `false` and `suspense` is `false`, errors are returned as state.
2094
2666
  * If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`).
2095
- *
2096
2667
  * @defaultValue false
2097
2668
  */
2098
2669
  throwOnError?: ThrowOnError<TQueryFnData, TError, TQueryData, TQueryKey>;
@@ -2106,7 +2677,6 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2106
2677
  /**
2107
2678
  * If set to `true`, the query will suspend when `status === 'pending'`
2108
2679
  * and throw errors when `status === 'error'`.
2109
- *
2110
2680
  * @defaultValue false
2111
2681
  */
2112
2682
  suspense?: boolean;
@@ -2117,11 +2687,34 @@ interface QueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TD
2117
2687
  /** @internal */
2118
2688
  _optimisticResults?: 'optimistic' | 'isRestoring';
2119
2689
  }
2690
+ /**
2691
+ * Makes the `TKey` properties of `TTarget` required and non-nullable.
2692
+ */
2120
2693
  type WithRequired<TTarget, TKey extends keyof TTarget> = TTarget & { [_ in TKey]: {}; };
2694
+ /**
2695
+ * The {@link QueryObserverOptions} after `QueryClient#defaultQueryOptions` has applied the
2696
+ * defaults, so `throwOnError`, `refetchOnReconnect`, and `queryHash` are always set.
2697
+ */
2121
2698
  type DefaultedQueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = WithRequired<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'throwOnError' | 'refetchOnReconnect' | 'queryHash'>;
2699
+ /**
2700
+ * The options of an `InfiniteQueryObserver`: {@link QueryObserverOptions} whose query data is
2701
+ * {@link InfiniteData}, plus the page param options.
2702
+ */
2122
2703
  interface InfiniteQueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> extends QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey, TPageParam>, InfiniteQueryPageParamsOptions<TQueryFnData, TPageParam> {}
2704
+ /**
2705
+ * The {@link InfiniteQueryObserverOptions} after `QueryClient#defaultQueryOptions` has applied the
2706
+ * defaults, so `throwOnError`, `refetchOnReconnect`, and `queryHash` are always set.
2707
+ */
2123
2708
  type DefaultedInfiniteQueryObserverOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = WithRequired<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'throwOnError' | 'refetchOnReconnect' | 'queryHash'>;
2709
+ /**
2710
+ * The options of `queryClient.query`: the {@link QueryOptions} of the query, plus a `staleTime`
2711
+ * that decides whether cached data is returned instead of fetching, and a `select` that only
2712
+ * transforms the value the call resolves with.
2713
+ */
2124
2714
  interface QueryExecuteOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> extends WithRequired<QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey, TPageParam>, 'queryKey'> {
2715
+ /**
2716
+ * Not allowed here, since `initialPageParam` only applies to infinite queries.
2717
+ */
2125
2718
  initialPageParam?: never;
2126
2719
  /**
2127
2720
  * This option can be used to transform or select a part of the data returned by the query function. It affects
@@ -2136,6 +2729,9 @@ interface QueryExecuteOptions<TQueryFnData = unknown, TError = DefaultError, TDa
2136
2729
  }
2137
2730
  /** @deprecated */
2138
2731
  interface FetchQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> extends WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'queryKey'> {
2732
+ /**
2733
+ * Not allowed here, since `initialPageParam` only applies to infinite queries.
2734
+ */
2139
2735
  initialPageParam?: never;
2140
2736
  /**
2141
2737
  * The time in milliseconds after data is considered stale.
@@ -2145,6 +2741,9 @@ interface FetchQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData
2145
2741
  }
2146
2742
  /** @deprecated */
2147
2743
  interface EnsureQueryDataOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = never> extends FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> {
2744
+ /**
2745
+ * If `true`, stale cached data is returned and also refetched in the background.
2746
+ */
2148
2747
  revalidateIfStale?: boolean;
2149
2748
  }
2150
2749
  /** @deprecated */
@@ -2157,28 +2756,42 @@ type InfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> = {
2157
2756
  pages: number;
2158
2757
  getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>;
2159
2758
  };
2759
+ /**
2760
+ * The options of `queryClient.infiniteQuery`: like {@link QueryExecuteOptions}, with the
2761
+ * `initialPageParam`, and optionally `pages` together with `getNextPageParam` to fetch that many
2762
+ * pages at once.
2763
+ */
2160
2764
  type InfiniteQueryExecuteOptions<TQueryFnData = unknown, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = Omit<QueryExecuteOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey, TPageParam>, 'initialPageParam'> & InitialPageParam<TPageParam> & InfiniteQueryPages<TQueryFnData, TPageParam>;
2161
2765
  /** @deprecated */
2162
2766
  type FetchInfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = Omit<FetchQueryOptions<TQueryFnData, TError, InfiniteData<TData, TPageParam>, TQueryKey, TPageParam>, 'initialPageParam'> & InitialPageParam<TPageParam> & InfiniteQueryPages<TQueryFnData, TPageParam>;
2767
+ /**
2768
+ * Options shared by the `QueryClient` and observer methods that refetch queries, controlling
2769
+ * whether a failed refetch makes the returned promise reject.
2770
+ */
2163
2771
  interface ResultOptions {
2164
2772
  /**
2165
2773
  * If set to `true`, the method throws if any of the underlying query refetch tasks fail.
2166
2774
  * If set to `false`, failed refetches are swallowed and not surfaced to the caller.
2167
- *
2168
2775
  * @defaultValue false
2169
2776
  */
2170
2777
  throwOnError?: boolean;
2171
2778
  }
2779
+ /**
2780
+ * Options of the methods that refetch queries, like `refetch` and `queryClient.refetchQueries`.
2781
+ */
2172
2782
  interface RefetchOptions extends ResultOptions {
2173
2783
  /**
2174
2784
  * If set to `true`, a currently running request will be cancelled before a new request is made
2175
2785
  *
2176
2786
  * If set to `false`, no refetch will be made if there is already a request running.
2177
- *
2178
2787
  * @defaultValue true
2179
2788
  */
2180
2789
  cancelRefetch?: boolean;
2181
2790
  }
2791
+ /**
2792
+ * The filters of `queryClient.invalidateQueries`: the {@link QueryFilters} that select the queries
2793
+ * to invalidate, plus `refetchType` to choose which of them are refetched.
2794
+ */
2182
2795
  interface InvalidateQueryFilters<TQueryKey extends QueryKey = QueryKey> extends QueryFilters<TQueryKey> {
2183
2796
  /**
2184
2797
  * Controls which of the matched (now-invalidated) queries are refetched in the background.
@@ -2187,32 +2800,45 @@ interface InvalidateQueryFilters<TQueryKey extends QueryKey = QueryKey> extends
2187
2800
  * - `'inactive'`: only queries with no active observer are refetched.
2188
2801
  * - `'all'`: every matched query is refetched, active or not.
2189
2802
  * - `'none'`: no query is refetched; matched queries are only marked as invalidated.
2190
- *
2191
2803
  * @defaultValue 'active'
2192
2804
  */
2193
2805
  refetchType?: QueryTypeFilter | 'none';
2194
2806
  }
2807
+ /**
2808
+ * The filters of `queryClient.refetchQueries`, which select the queries to refetch.
2809
+ */
2195
2810
  interface RefetchQueryFilters<TQueryKey extends QueryKey = QueryKey> extends QueryFilters<TQueryKey> {}
2811
+ /**
2812
+ * Options of `queryClient.invalidateQueries`, applied to the refetch that follows the invalidation.
2813
+ */
2196
2814
  interface InvalidateOptions extends RefetchOptions {}
2815
+ /**
2816
+ * Options of `queryClient.resetQueries`, applied to the refetch of the active queries after the
2817
+ * reset.
2818
+ */
2197
2819
  interface ResetOptions extends RefetchOptions {}
2820
+ /**
2821
+ * Options of `fetchNextPage` on an infinite query result.
2822
+ */
2198
2823
  interface FetchNextPageOptions extends ResultOptions {
2199
2824
  /**
2200
2825
  * If set to `true`, calling `fetchNextPage` repeatedly will invoke `queryFn` every time,
2201
2826
  * whether the previous invocation has resolved or not. Also, the result from previous invocations will be ignored.
2202
2827
  *
2203
2828
  * If set to `false`, calling `fetchNextPage` repeatedly won't have any effect until the first invocation has resolved.
2204
- *
2205
2829
  * @defaultValue true
2206
2830
  */
2207
2831
  cancelRefetch?: boolean;
2208
2832
  }
2833
+ /**
2834
+ * Options of `fetchPreviousPage` on an infinite query result.
2835
+ */
2209
2836
  interface FetchPreviousPageOptions extends ResultOptions {
2210
2837
  /**
2211
2838
  * If set to `true`, calling `fetchPreviousPage` repeatedly will invoke `queryFn` every time,
2212
2839
  * whether the previous invocation has resolved or not. Also, the result from previous invocations will be ignored.
2213
2840
  *
2214
2841
  * If set to `false`, calling `fetchPreviousPage` repeatedly won't have any effect until the first invocation has resolved.
2215
- *
2216
2842
  * @defaultValue true
2217
2843
  */
2218
2844
  cancelRefetch?: boolean;
@@ -2221,6 +2847,10 @@ interface FetchPreviousPageOptions extends ResultOptions {
2221
2847
  type QueryStatus = 'pending' | 'error' | 'success';
2222
2848
  /** @inline */
2223
2849
  type FetchStatus = 'fetching' | 'paused' | 'idle';
2850
+ /**
2851
+ * The properties shared by every state of a query result, like `data`, `error`, `status`, the
2852
+ * `is*` flags, and `refetch`. Each `QueryObserver*Result` narrows them for one state.
2853
+ */
2224
2854
  interface QueryObserverBaseResult<TData = unknown, TError = DefaultError> {
2225
2855
  /**
2226
2856
  * The last successfully resolved data for the query.
@@ -2343,79 +2973,290 @@ interface QueryObserverBaseResult<TData = unknown, TError = DefaultError> {
2343
2973
  */
2344
2974
  fetchStatus: FetchStatus;
2345
2975
  }
2976
+ /**
2977
+ * A query result in the `pending` state: the query has no data yet.
2978
+ */
2346
2979
  interface QueryObserverPendingResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
2980
+ /**
2981
+ * `undefined`, since the query has no data yet.
2982
+ */
2347
2983
  data: undefined;
2984
+ /**
2985
+ * `null`, since the query isn't in the `error` state.
2986
+ */
2348
2987
  error: null;
2988
+ /**
2989
+ * `false`, since the query isn't in the `error` state.
2990
+ */
2349
2991
  isError: false;
2992
+ /**
2993
+ * `true`, since there's no cached data and no query attempt has finished yet.
2994
+ */
2350
2995
  isPending: true;
2996
+ /**
2997
+ * `false`, since the query didn't fail while fetching for the first time.
2998
+ */
2351
2999
  isLoadingError: false;
3000
+ /**
3001
+ * `false`, since the query didn't fail while refetching.
3002
+ */
2352
3003
  isRefetchError: false;
3004
+ /**
3005
+ * `false`, since the query isn't in the `success` state.
3006
+ */
2353
3007
  isSuccess: false;
3008
+ /**
3009
+ * `false`, since the data shown isn't the `placeholderData`.
3010
+ */
2354
3011
  isPlaceholderData: false;
3012
+ /**
3013
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
3014
+ */
2355
3015
  status: 'pending';
2356
3016
  }
3017
+ /**
3018
+ * A query result in the `pending` state while the first fetch is in flight, so `isLoading` is
3019
+ * `true`.
3020
+ */
2357
3021
  interface QueryObserverLoadingResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
3022
+ /**
3023
+ * `undefined`, since the query has no data yet.
3024
+ */
2358
3025
  data: undefined;
3026
+ /**
3027
+ * `null`, since the query isn't in the `error` state.
3028
+ */
2359
3029
  error: null;
3030
+ /**
3031
+ * `false`, since the query isn't in the `error` state.
3032
+ */
2360
3033
  isError: false;
3034
+ /**
3035
+ * `true`, since there's no cached data and no query attempt has finished yet.
3036
+ */
2361
3037
  isPending: true;
3038
+ /**
3039
+ * `true`, since the first fetch is in flight.
3040
+ */
2362
3041
  isLoading: true;
3042
+ /**
3043
+ * `false`, since the query didn't fail while fetching for the first time.
3044
+ */
2363
3045
  isLoadingError: false;
3046
+ /**
3047
+ * `false`, since the query didn't fail while refetching.
3048
+ */
2364
3049
  isRefetchError: false;
3050
+ /**
3051
+ * `false`, since the query isn't in the `success` state.
3052
+ */
2365
3053
  isSuccess: false;
3054
+ /**
3055
+ * `false`, since the data shown isn't the `placeholderData`.
3056
+ */
2366
3057
  isPlaceholderData: false;
3058
+ /**
3059
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
3060
+ */
2367
3061
  status: 'pending';
2368
3062
  }
3063
+ /**
3064
+ * A query result in the `error` state when the first fetch failed, so there is no data.
3065
+ */
2369
3066
  interface QueryObserverLoadingErrorResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
3067
+ /**
3068
+ * `undefined`, since the first fetch failed before any data was cached.
3069
+ */
2370
3070
  data: undefined;
3071
+ /**
3072
+ * The error the first fetch failed with.
3073
+ */
2371
3074
  error: TError;
3075
+ /**
3076
+ * `true`, since the query is in the `error` state.
3077
+ */
2372
3078
  isError: true;
3079
+ /**
3080
+ * `false`, since the query has data or a query attempt has finished.
3081
+ */
2373
3082
  isPending: false;
3083
+ /**
3084
+ * `false`, since the first fetch isn't in flight.
3085
+ */
2374
3086
  isLoading: false;
3087
+ /**
3088
+ * `true`, since the query failed while fetching for the first time.
3089
+ */
2375
3090
  isLoadingError: true;
3091
+ /**
3092
+ * `false`, since the query didn't fail while refetching.
3093
+ */
2376
3094
  isRefetchError: false;
3095
+ /**
3096
+ * `false`, since the query isn't in the `success` state.
3097
+ */
2377
3098
  isSuccess: false;
3099
+ /**
3100
+ * `false`, since the data shown isn't the `placeholderData`.
3101
+ */
2378
3102
  isPlaceholderData: false;
3103
+ /**
3104
+ * `'error'`, since the query attempt resulted in an error.
3105
+ */
2379
3106
  status: 'error';
2380
3107
  }
3108
+ /**
3109
+ * A query result in the `error` state when a refetch failed, so the data from before is kept.
3110
+ */
2381
3111
  interface QueryObserverRefetchErrorResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
3112
+ /**
3113
+ * The data from before the failed refetch, which is kept.
3114
+ */
2382
3115
  data: TData;
3116
+ /**
3117
+ * The error the refetch failed with.
3118
+ */
2383
3119
  error: TError;
3120
+ /**
3121
+ * `true`, since the query is in the `error` state.
3122
+ */
2384
3123
  isError: true;
3124
+ /**
3125
+ * `false`, since the query has data or a query attempt has finished.
3126
+ */
2385
3127
  isPending: false;
3128
+ /**
3129
+ * `false`, since the first fetch isn't in flight.
3130
+ */
2386
3131
  isLoading: false;
3132
+ /**
3133
+ * `false`, since the query didn't fail while fetching for the first time.
3134
+ */
2387
3135
  isLoadingError: false;
3136
+ /**
3137
+ * `true`, since the query failed while refetching.
3138
+ */
2388
3139
  isRefetchError: true;
3140
+ /**
3141
+ * `false`, since the query isn't in the `success` state.
3142
+ */
2389
3143
  isSuccess: false;
3144
+ /**
3145
+ * `false`, since the data shown isn't the `placeholderData`.
3146
+ */
2390
3147
  isPlaceholderData: false;
3148
+ /**
3149
+ * `'error'`, since the query attempt resulted in an error.
3150
+ */
2391
3151
  status: 'error';
2392
3152
  }
3153
+ /**
3154
+ * A query result in the `success` state with data from the cache.
3155
+ */
2393
3156
  interface QueryObserverSuccessResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
3157
+ /**
3158
+ * The last successfully resolved data for the query.
3159
+ */
2394
3160
  data: TData;
3161
+ /**
3162
+ * `null`, since the query isn't in the `error` state.
3163
+ */
2395
3164
  error: null;
3165
+ /**
3166
+ * `false`, since the query isn't in the `error` state.
3167
+ */
2396
3168
  isError: false;
3169
+ /**
3170
+ * `false`, since the query has data or a query attempt has finished.
3171
+ */
2397
3172
  isPending: false;
3173
+ /**
3174
+ * `false`, since the first fetch isn't in flight.
3175
+ */
2398
3176
  isLoading: false;
3177
+ /**
3178
+ * `false`, since the query didn't fail while fetching for the first time.
3179
+ */
2399
3180
  isLoadingError: false;
3181
+ /**
3182
+ * `false`, since the query didn't fail while refetching.
3183
+ */
2400
3184
  isRefetchError: false;
3185
+ /**
3186
+ * `true`, since the query is in the `success` state.
3187
+ */
2401
3188
  isSuccess: true;
3189
+ /**
3190
+ * `false`, since the data shown isn't the `placeholderData`.
3191
+ */
2402
3192
  isPlaceholderData: false;
3193
+ /**
3194
+ * `'success'`, since the query has received a response with no errors and is ready to display its
3195
+ * data.
3196
+ */
2403
3197
  status: 'success';
2404
3198
  }
3199
+ /**
3200
+ * A query result in the `success` state that shows `placeholderData` while the query has no data
3201
+ * yet.
3202
+ */
2405
3203
  interface QueryObserverPlaceholderResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
3204
+ /**
3205
+ * The `placeholderData` shown while the query has no data yet.
3206
+ */
2406
3207
  data: TData;
3208
+ /**
3209
+ * `false`, since the query isn't in the `error` state.
3210
+ */
2407
3211
  isError: false;
3212
+ /**
3213
+ * `null`, since the query isn't in the `error` state.
3214
+ */
2408
3215
  error: null;
3216
+ /**
3217
+ * `false`, since the query has data or a query attempt has finished.
3218
+ */
2409
3219
  isPending: false;
3220
+ /**
3221
+ * `false`, since the first fetch isn't in flight.
3222
+ */
2410
3223
  isLoading: false;
3224
+ /**
3225
+ * `false`, since the query didn't fail while fetching for the first time.
3226
+ */
2411
3227
  isLoadingError: false;
3228
+ /**
3229
+ * `false`, since the query didn't fail while refetching.
3230
+ */
2412
3231
  isRefetchError: false;
3232
+ /**
3233
+ * `true`, since the query is in the `success` state.
3234
+ */
2413
3235
  isSuccess: true;
3236
+ /**
3237
+ * `true`, since the data shown is the `placeholderData`.
3238
+ */
2414
3239
  isPlaceholderData: true;
3240
+ /**
3241
+ * `'success'`, since the query has received a response with no errors and is ready to display its
3242
+ * data.
3243
+ */
2415
3244
  status: 'success';
2416
3245
  }
3246
+ /**
3247
+ * A query result that always has `data`: the success and refetch error states.
3248
+ */
2417
3249
  type DefinedQueryObserverResult<TData = unknown, TError = DefaultError> = QueryObserverRefetchErrorResult<TData, TError> | QueryObserverSuccessResult<TData, TError>;
3250
+ /**
3251
+ * The result of a `QueryObserver`, and of the hooks built on it like `useQuery`. Narrow it by
3252
+ * `status` or the `is*` flags to get the type of each state.
3253
+ */
2418
3254
  type QueryObserverResult<TData = unknown, TError = DefaultError> = DefinedQueryObserverResult<TData, TError> | QueryObserverLoadingErrorResult<TData, TError> | QueryObserverLoadingResult<TData, TError> | QueryObserverPendingResult<TData, TError> | QueryObserverPlaceholderResult<TData, TError>;
3255
+ /**
3256
+ * The properties shared by every state of an infinite query result: those of
3257
+ * {@link QueryObserverBaseResult}, plus `fetchNextPage`, `fetchPreviousPage`, and the flags about
3258
+ * them, like `hasNextPage` and `isFetchingNextPage`.
3259
+ */
2419
3260
  interface InfiniteQueryObserverBaseResult<TData = unknown, TError = DefaultError> extends QueryObserverBaseResult<TData, TError> {
2420
3261
  /**
2421
3262
  * This function allows you to fetch the next "page" of results.
@@ -2450,88 +3291,325 @@ interface InfiniteQueryObserverBaseResult<TData = unknown, TError = DefaultError
2450
3291
  */
2451
3292
  isFetchingPreviousPage: boolean;
2452
3293
  }
3294
+ /**
3295
+ * An infinite query result in the `pending` state: the query has no data yet.
3296
+ */
2453
3297
  interface InfiniteQueryObserverPendingResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3298
+ /**
3299
+ * `undefined`, since the query has no data yet.
3300
+ */
2454
3301
  data: undefined;
3302
+ /**
3303
+ * `null`, since the query isn't in the `error` state.
3304
+ */
2455
3305
  error: null;
3306
+ /**
3307
+ * `false`, since the query isn't in the `error` state.
3308
+ */
2456
3309
  isError: false;
3310
+ /**
3311
+ * `true`, since there's no cached data and no query attempt has finished yet.
3312
+ */
2457
3313
  isPending: true;
3314
+ /**
3315
+ * `false`, since the query didn't fail while fetching for the first time.
3316
+ */
2458
3317
  isLoadingError: false;
3318
+ /**
3319
+ * `false`, since the query didn't fail while refetching.
3320
+ */
2459
3321
  isRefetchError: false;
3322
+ /**
3323
+ * `false`, since fetching the next page didn't fail.
3324
+ */
2460
3325
  isFetchNextPageError: false;
3326
+ /**
3327
+ * `false`, since fetching the previous page didn't fail.
3328
+ */
2461
3329
  isFetchPreviousPageError: false;
3330
+ /**
3331
+ * `false`, since the query isn't in the `success` state.
3332
+ */
2462
3333
  isSuccess: false;
3334
+ /**
3335
+ * `false`, since the data shown isn't the `placeholderData`.
3336
+ */
2463
3337
  isPlaceholderData: false;
3338
+ /**
3339
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
3340
+ */
2464
3341
  status: 'pending';
2465
3342
  }
3343
+ /**
3344
+ * An infinite query result in the `pending` state while the first fetch is in flight, so
3345
+ * `isLoading` is `true`.
3346
+ */
2466
3347
  interface InfiniteQueryObserverLoadingResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3348
+ /**
3349
+ * `undefined`, since the query has no data yet.
3350
+ */
2467
3351
  data: undefined;
3352
+ /**
3353
+ * `null`, since the query isn't in the `error` state.
3354
+ */
2468
3355
  error: null;
3356
+ /**
3357
+ * `false`, since the query isn't in the `error` state.
3358
+ */
2469
3359
  isError: false;
3360
+ /**
3361
+ * `true`, since there's no cached data and no query attempt has finished yet.
3362
+ */
2470
3363
  isPending: true;
3364
+ /**
3365
+ * `true`, since the first fetch is in flight.
3366
+ */
2471
3367
  isLoading: true;
3368
+ /**
3369
+ * `false`, since the query didn't fail while fetching for the first time.
3370
+ */
2472
3371
  isLoadingError: false;
3372
+ /**
3373
+ * `false`, since the query didn't fail while refetching.
3374
+ */
2473
3375
  isRefetchError: false;
3376
+ /**
3377
+ * `false`, since fetching the next page didn't fail.
3378
+ */
2474
3379
  isFetchNextPageError: false;
3380
+ /**
3381
+ * `false`, since fetching the previous page didn't fail.
3382
+ */
2475
3383
  isFetchPreviousPageError: false;
3384
+ /**
3385
+ * `false`, since the query isn't in the `success` state.
3386
+ */
2476
3387
  isSuccess: false;
3388
+ /**
3389
+ * `false`, since the data shown isn't the `placeholderData`.
3390
+ */
2477
3391
  isPlaceholderData: false;
3392
+ /**
3393
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
3394
+ */
2478
3395
  status: 'pending';
2479
3396
  }
3397
+ /**
3398
+ * An infinite query result in the `error` state when the first fetch failed, so there is no data.
3399
+ */
2480
3400
  interface InfiniteQueryObserverLoadingErrorResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3401
+ /**
3402
+ * `undefined`, since the first fetch failed before any data was cached.
3403
+ */
2481
3404
  data: undefined;
3405
+ /**
3406
+ * The error the first fetch failed with.
3407
+ */
2482
3408
  error: TError;
3409
+ /**
3410
+ * `true`, since the query is in the `error` state.
3411
+ */
2483
3412
  isError: true;
3413
+ /**
3414
+ * `false`, since the query has data or a query attempt has finished.
3415
+ */
2484
3416
  isPending: false;
3417
+ /**
3418
+ * `false`, since the first fetch isn't in flight.
3419
+ */
2485
3420
  isLoading: false;
3421
+ /**
3422
+ * `true`, since the query failed while fetching for the first time.
3423
+ */
2486
3424
  isLoadingError: true;
3425
+ /**
3426
+ * `false`, since the query didn't fail while refetching.
3427
+ */
2487
3428
  isRefetchError: false;
3429
+ /**
3430
+ * `false`, since fetching the next page didn't fail.
3431
+ */
2488
3432
  isFetchNextPageError: false;
3433
+ /**
3434
+ * `false`, since fetching the previous page didn't fail.
3435
+ */
2489
3436
  isFetchPreviousPageError: false;
3437
+ /**
3438
+ * `false`, since the query isn't in the `success` state.
3439
+ */
2490
3440
  isSuccess: false;
3441
+ /**
3442
+ * `false`, since the data shown isn't the `placeholderData`.
3443
+ */
2491
3444
  isPlaceholderData: false;
3445
+ /**
3446
+ * `'error'`, since the query attempt resulted in an error.
3447
+ */
2492
3448
  status: 'error';
2493
3449
  }
3450
+ /**
3451
+ * An infinite query result in the `error` state when a refetch failed, so the data from before is
3452
+ * kept.
3453
+ */
2494
3454
  interface InfiniteQueryObserverRefetchErrorResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3455
+ /**
3456
+ * The data from before the failed refetch, which is kept.
3457
+ */
2495
3458
  data: TData;
3459
+ /**
3460
+ * The error the refetch failed with.
3461
+ */
2496
3462
  error: TError;
3463
+ /**
3464
+ * `true`, since the query is in the `error` state.
3465
+ */
2497
3466
  isError: true;
3467
+ /**
3468
+ * `false`, since the query has data or a query attempt has finished.
3469
+ */
2498
3470
  isPending: false;
3471
+ /**
3472
+ * `false`, since the first fetch isn't in flight.
3473
+ */
2499
3474
  isLoading: false;
3475
+ /**
3476
+ * `false`, since the query didn't fail while fetching for the first time.
3477
+ */
2500
3478
  isLoadingError: false;
3479
+ /**
3480
+ * `true`, since the query failed while refetching.
3481
+ */
2501
3482
  isRefetchError: true;
3483
+ /**
3484
+ * `false`, since the query isn't in the `success` state.
3485
+ */
2502
3486
  isSuccess: false;
3487
+ /**
3488
+ * `false`, since the data shown isn't the `placeholderData`.
3489
+ */
2503
3490
  isPlaceholderData: false;
3491
+ /**
3492
+ * `'error'`, since the query attempt resulted in an error.
3493
+ */
2504
3494
  status: 'error';
2505
3495
  }
3496
+ /**
3497
+ * An infinite query result in the `success` state with data from the cache.
3498
+ */
2506
3499
  interface InfiniteQueryObserverSuccessResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3500
+ /**
3501
+ * The last successfully resolved data for the query.
3502
+ */
2507
3503
  data: TData;
3504
+ /**
3505
+ * `null`, since the query isn't in the `error` state.
3506
+ */
2508
3507
  error: null;
3508
+ /**
3509
+ * `false`, since the query isn't in the `error` state.
3510
+ */
2509
3511
  isError: false;
3512
+ /**
3513
+ * `false`, since the query has data or a query attempt has finished.
3514
+ */
2510
3515
  isPending: false;
3516
+ /**
3517
+ * `false`, since the first fetch isn't in flight.
3518
+ */
2511
3519
  isLoading: false;
3520
+ /**
3521
+ * `false`, since the query didn't fail while fetching for the first time.
3522
+ */
2512
3523
  isLoadingError: false;
3524
+ /**
3525
+ * `false`, since the query didn't fail while refetching.
3526
+ */
2513
3527
  isRefetchError: false;
3528
+ /**
3529
+ * `false`, since fetching the next page didn't fail.
3530
+ */
2514
3531
  isFetchNextPageError: false;
3532
+ /**
3533
+ * `false`, since fetching the previous page didn't fail.
3534
+ */
2515
3535
  isFetchPreviousPageError: false;
3536
+ /**
3537
+ * `true`, since the query is in the `success` state.
3538
+ */
2516
3539
  isSuccess: true;
3540
+ /**
3541
+ * `false`, since the data shown isn't the `placeholderData`.
3542
+ */
2517
3543
  isPlaceholderData: false;
3544
+ /**
3545
+ * `'success'`, since the query has received a response with no errors and is ready to display its
3546
+ * data.
3547
+ */
2518
3548
  status: 'success';
2519
3549
  }
3550
+ /**
3551
+ * An infinite query result in the `success` state that shows `placeholderData` while the query has
3552
+ * no data yet.
3553
+ */
2520
3554
  interface InfiniteQueryObserverPlaceholderResult<TData = unknown, TError = DefaultError> extends InfiniteQueryObserverBaseResult<TData, TError> {
3555
+ /**
3556
+ * The `placeholderData` shown while the query has no data yet.
3557
+ */
2521
3558
  data: TData;
3559
+ /**
3560
+ * `false`, since the query isn't in the `error` state.
3561
+ */
2522
3562
  isError: false;
3563
+ /**
3564
+ * `null`, since the query isn't in the `error` state.
3565
+ */
2523
3566
  error: null;
3567
+ /**
3568
+ * `false`, since the query has data or a query attempt has finished.
3569
+ */
2524
3570
  isPending: false;
3571
+ /**
3572
+ * `false`, since the first fetch isn't in flight.
3573
+ */
2525
3574
  isLoading: false;
3575
+ /**
3576
+ * `false`, since the query didn't fail while fetching for the first time.
3577
+ */
2526
3578
  isLoadingError: false;
3579
+ /**
3580
+ * `false`, since the query didn't fail while refetching.
3581
+ */
2527
3582
  isRefetchError: false;
3583
+ /**
3584
+ * `true`, since the query is in the `success` state.
3585
+ */
2528
3586
  isSuccess: true;
3587
+ /**
3588
+ * `true`, since the data shown is the `placeholderData`.
3589
+ */
2529
3590
  isPlaceholderData: true;
3591
+ /**
3592
+ * `false`, since fetching the next page didn't fail.
3593
+ */
2530
3594
  isFetchNextPageError: false;
3595
+ /**
3596
+ * `false`, since fetching the previous page didn't fail.
3597
+ */
2531
3598
  isFetchPreviousPageError: false;
3599
+ /**
3600
+ * `'success'`, since the query has received a response with no errors and is ready to display its
3601
+ * data.
3602
+ */
2532
3603
  status: 'success';
2533
3604
  }
3605
+ /**
3606
+ * An infinite query result that always has `data`: the success and refetch error states.
3607
+ */
2534
3608
  type DefinedInfiniteQueryObserverResult<TData = unknown, TError = DefaultError> = InfiniteQueryObserverRefetchErrorResult<TData, TError> | InfiniteQueryObserverSuccessResult<TData, TError>;
3609
+ /**
3610
+ * The result of an `InfiniteQueryObserver`, and of the hooks built on it like `useInfiniteQuery`.
3611
+ * Narrow it by `status` or the `is*` flags to get the type of each state.
3612
+ */
2535
3613
  type InfiniteQueryObserverResult<TData = unknown, TError = DefaultError> = DefinedInfiniteQueryObserverResult<TData, TError> | InfiniteQueryObserverLoadingErrorResult<TData, TError> | InfiniteQueryObserverLoadingResult<TData, TError> | InfiniteQueryObserverPendingResult<TData, TError> | InfiniteQueryObserverPlaceholderResult<TData, TError>;
2536
3614
  /**
2537
3615
  * The type of a mutation key — the serializable array used to identify and filter mutations.
@@ -2548,6 +3626,9 @@ type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
2548
3626
  * state and resume automatically when their turn comes. Mutations with no scope always run in parallel.
2549
3627
  */
2550
3628
  type MutationScope = {
3629
+ /**
3630
+ * The scope's identifier. Mutations with the same `id` run one after another.
3631
+ */
2551
3632
  id: string;
2552
3633
  };
2553
3634
  /**
@@ -2557,13 +3638,30 @@ type MutationScope = {
2557
3638
  type MutationMeta = Register extends {
2558
3639
  mutationMeta: infer TMutationMeta;
2559
3640
  } ? TMutationMeta extends Record<string, unknown> ? TMutationMeta : Record<string, unknown> : Record<string, unknown>;
3641
+ /**
3642
+ * The object passed to `mutationFn` and the mutation callbacks: the `QueryClient`, the mutation's
3643
+ * `meta`, and its `mutationKey`.
3644
+ */
2560
3645
  type MutationFunctionContext = {
3646
+ /**
3647
+ * The `QueryClient` the mutation runs in.
3648
+ */
2561
3649
  client: QueryClient;
3650
+ /**
3651
+ * The `meta` of the mutation options.
3652
+ */
2562
3653
  meta: MutationMeta | undefined;
3654
+ /**
3655
+ * The `mutationKey` of the mutation options, if set.
3656
+ */
2563
3657
  mutationKey?: MutationKey;
2564
3658
  };
2565
3659
  /** @inline */
2566
3660
  type MutationFunction<TData = unknown, TVariables = unknown> = (variables: TVariables, context: MutationFunctionContext) => Promise<TData>;
3661
+ /**
3662
+ * The options of a mutation: its `mutationFn`, `mutationKey`, callbacks, retries, `scope`, and so
3663
+ * on.
3664
+ */
2567
3665
  interface MutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> {
2568
3666
  /**
2569
3667
  * The function that performs the asynchronous task this mutation runs.
@@ -2609,7 +3707,6 @@ interface MutationOptions<TData = unknown, TError = DefaultError, TVariables = v
2609
3707
  * If `true`, failed mutations will retry infinitely.
2610
3708
  * If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number.
2611
3709
  * If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false.
2612
- *
2613
3710
  * @defaultValue 0
2614
3711
  */
2615
3712
  retry?: RetryValue<TError>;
@@ -2622,7 +3719,6 @@ interface MutationOptions<TData = unknown, TError = DefaultError, TVariables = v
2622
3719
  retryDelay?: RetryDelayValue<TError>;
2623
3720
  /**
2624
3721
  * Controls whether a mutation is allowed to run based on the current network connectivity.
2625
- *
2626
3722
  * @defaultValue 'online'
2627
3723
  * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
2628
3724
  */
@@ -2649,24 +3745,53 @@ interface MutationOptions<TData = unknown, TError = DefaultError, TVariables = v
2649
3745
  */
2650
3746
  scope?: MutationScope;
2651
3747
  }
3748
+ /**
3749
+ * The options of a `MutationObserver`, and of the hooks built on it like `useMutation`: the
3750
+ * {@link MutationOptions}, plus `throwOnError`.
3751
+ */
2652
3752
  interface MutationObserverOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationOptions<TData, TError, TVariables, TOnMutateResult> {
2653
3753
  /**
2654
3754
  * Whether errors should be thrown instead of setting the `error` property.
2655
3755
  * If set to `true`, all errors will be thrown to the nearest error boundary.
2656
3756
  * If set to a function, it will be passed the error and should return a boolean indicating whether to throw the
2657
3757
  * error (`true`) or return it as state (`false`).
2658
- *
2659
3758
  * @defaultValue false
2660
3759
  */
2661
3760
  throwOnError?: boolean | ((error: TError) => boolean);
2662
3761
  }
3762
+ /**
3763
+ * The callbacks that can be passed to `mutate` for a single call. They run after the callbacks of
3764
+ * the mutation options.
3765
+ */
2663
3766
  interface MutateOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> {
3767
+ /**
3768
+ * Called when the mutation of this call succeeds, after the `onSuccess` of the mutation options.
3769
+ */
2664
3770
  onSuccess?: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void;
3771
+ /**
3772
+ * Called when the mutation of this call fails, after the `onError` of the mutation options.
3773
+ */
2665
3774
  onError?: (error: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void;
3775
+ /**
3776
+ * Called when the mutation of this call succeeds or fails, after the `onSettled` of the mutation
3777
+ * options.
3778
+ */
2666
3779
  onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void;
2667
3780
  }
3781
+ /**
3782
+ * The parameters of {@link MutateFunction}: `variables`, optional when `TVariables` accepts
3783
+ * `undefined`, and the {@link MutateOptions} for that call.
3784
+ */
2668
3785
  type MutateFunctionRest<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = undefined extends TVariables ? [variables?: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>] : [variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>];
3786
+ /**
3787
+ * The `mutate` function of a `MutationObserver`: runs the mutation with the given variables and
3788
+ * resolves with its data.
3789
+ */
2669
3790
  type MutateFunction<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = (...rest: MutateFunctionRest<TData, TError, TVariables, TOnMutateResult>) => Promise<TData>;
3791
+ /**
3792
+ * The properties shared by every state of a mutation result, like `data`, `error`, `variables`,
3793
+ * `status`, the `is*` flags, `mutate`, and `reset`.
3794
+ */
2670
3795
  interface MutationObserverBaseResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationState<TData, TError, TVariables, TOnMutateResult> {
2671
3796
  /**
2672
3797
  * The last successfully resolved data for the mutation.
@@ -2726,47 +3851,163 @@ interface MutationObserverBaseResult<TData = unknown, TError = DefaultError, TVa
2726
3851
  */
2727
3852
  reset: () => void;
2728
3853
  }
3854
+ /**
3855
+ * A mutation result in the `idle` state: the mutation hasn't run yet, or was reset.
3856
+ */
2729
3857
  interface MutationObserverIdleResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationObserverBaseResult<TData, TError, TVariables, TOnMutateResult> {
3858
+ /**
3859
+ * `undefined`, since the mutation hasn't run.
3860
+ */
2730
3861
  data: undefined;
3862
+ /**
3863
+ * `undefined`, since the mutation hasn't run.
3864
+ */
2731
3865
  variables: undefined;
3866
+ /**
3867
+ * `null`, since the mutation hasn't failed.
3868
+ */
2732
3869
  error: null;
3870
+ /**
3871
+ * `false`, since the mutation hasn't failed.
3872
+ */
2733
3873
  isError: false;
3874
+ /**
3875
+ * `true`, since the mutation hasn't run yet or was reset.
3876
+ */
2734
3877
  isIdle: true;
3878
+ /**
3879
+ * `false`, since the mutation isn't running.
3880
+ */
2735
3881
  isPending: false;
3882
+ /**
3883
+ * `false`, since the mutation hasn't succeeded.
3884
+ */
2736
3885
  isSuccess: false;
3886
+ /**
3887
+ * `'idle'`, since the mutation hasn't run yet or was reset.
3888
+ */
2737
3889
  status: 'idle';
2738
3890
  }
3891
+ /**
3892
+ * A mutation result in the `pending` state while the mutation runs.
3893
+ */
2739
3894
  interface MutationObserverLoadingResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationObserverBaseResult<TData, TError, TVariables, TOnMutateResult> {
3895
+ /**
3896
+ * `undefined`, since the mutation hasn't succeeded.
3897
+ */
2740
3898
  data: undefined;
3899
+ /**
3900
+ * The variables passed to `mutate` for this mutation.
3901
+ */
2741
3902
  variables: TVariables;
3903
+ /**
3904
+ * `null`, since the mutation hasn't failed.
3905
+ */
2742
3906
  error: null;
3907
+ /**
3908
+ * `false`, since the mutation hasn't failed.
3909
+ */
2743
3910
  isError: false;
3911
+ /**
3912
+ * `false`, since the mutation has run.
3913
+ */
2744
3914
  isIdle: false;
3915
+ /**
3916
+ * `true`, since the mutation is running.
3917
+ */
2745
3918
  isPending: true;
3919
+ /**
3920
+ * `false`, since the mutation hasn't succeeded.
3921
+ */
2746
3922
  isSuccess: false;
3923
+ /**
3924
+ * `'pending'`, since the mutation is running.
3925
+ */
2747
3926
  status: 'pending';
2748
3927
  }
3928
+ /**
3929
+ * A mutation result in the `error` state after the mutation failed.
3930
+ */
2749
3931
  interface MutationObserverErrorResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationObserverBaseResult<TData, TError, TVariables, TOnMutateResult> {
3932
+ /**
3933
+ * `undefined`, since the mutation hasn't succeeded.
3934
+ */
2750
3935
  data: undefined;
3936
+ /**
3937
+ * The error the mutation failed with.
3938
+ */
2751
3939
  error: TError;
3940
+ /**
3941
+ * The variables passed to `mutate` for this mutation.
3942
+ */
2752
3943
  variables: TVariables;
3944
+ /**
3945
+ * `true`, since the mutation failed.
3946
+ */
2753
3947
  isError: true;
3948
+ /**
3949
+ * `false`, since the mutation has run.
3950
+ */
2754
3951
  isIdle: false;
3952
+ /**
3953
+ * `false`, since the mutation isn't running.
3954
+ */
2755
3955
  isPending: false;
3956
+ /**
3957
+ * `false`, since the mutation hasn't succeeded.
3958
+ */
2756
3959
  isSuccess: false;
3960
+ /**
3961
+ * `'error'`, since the mutation failed.
3962
+ */
2757
3963
  status: 'error';
2758
3964
  }
3965
+ /**
3966
+ * A mutation result in the `success` state after the mutation succeeded.
3967
+ */
2759
3968
  interface MutationObserverSuccessResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends MutationObserverBaseResult<TData, TError, TVariables, TOnMutateResult> {
3969
+ /**
3970
+ * The data the mutation resolved with.
3971
+ */
2760
3972
  data: TData;
3973
+ /**
3974
+ * `null`, since the mutation hasn't failed.
3975
+ */
2761
3976
  error: null;
3977
+ /**
3978
+ * The variables passed to `mutate` for this mutation.
3979
+ */
2762
3980
  variables: TVariables;
3981
+ /**
3982
+ * `false`, since the mutation hasn't failed.
3983
+ */
2763
3984
  isError: false;
3985
+ /**
3986
+ * `false`, since the mutation has run.
3987
+ */
2764
3988
  isIdle: false;
3989
+ /**
3990
+ * `false`, since the mutation isn't running.
3991
+ */
2765
3992
  isPending: false;
3993
+ /**
3994
+ * `true`, since the mutation succeeded.
3995
+ */
2766
3996
  isSuccess: true;
3997
+ /**
3998
+ * `'success'`, since the mutation succeeded.
3999
+ */
2767
4000
  status: 'success';
2768
4001
  }
4002
+ /**
4003
+ * The result of a `MutationObserver`, and of the hooks built on it like `useMutation`. Narrow it by
4004
+ * `status` or the `is*` flags to get the type of each state.
4005
+ */
2769
4006
  type MutationObserverResult<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = MutationObserverIdleResult<TData, TError, TVariables, TOnMutateResult> | MutationObserverLoadingResult<TData, TError, TVariables, TOnMutateResult> | MutationObserverErrorResult<TData, TError, TVariables, TOnMutateResult> | MutationObserverSuccessResult<TData, TError, TVariables, TOnMutateResult>;
4007
+ /**
4008
+ * The options of `new QueryClient()`: the `queryCache` and `mutationCache` to use, and the
4009
+ * `defaultOptions` for its queries and mutations.
4010
+ */
2770
4011
  interface QueryClientConfig {
2771
4012
  /** The query cache this client is connected to. A new `QueryCache` is created if not provided. */
2772
4013
  queryCache?: QueryCache;
@@ -2778,12 +4019,16 @@ interface QueryClientConfig {
2778
4019
  /** Default options for all queries and mutations created through this client. */
2779
4020
  defaultOptions?: DefaultOptions;
2780
4021
  }
4022
+ /**
4023
+ * The default options of a `QueryClient`, applied to every query (`queries`), mutation
4024
+ * (`mutations`), `hydrate`, and `dehydrate` call unless overridden.
4025
+ */
2781
4026
  interface DefaultOptions<TError = DefaultError> {
2782
4027
  /** Default options applied to every query, unless overridden per-query. */
2783
4028
  queries?: OmitKeyof<QueryObserverOptions<unknown, TError>, 'suspense' | 'queryKey'>;
2784
4029
  /** Default options applied to every mutation, unless overridden per-mutation. */
2785
4030
  mutations?: MutationObserverOptions<unknown, TError, unknown, unknown>;
2786
- /** Default options used when hydrating queries; see {@link HydrateOptions}. */
4031
+ /** Default options used when hydrating queries and mutations; see {@link HydrateOptions}. */
2787
4032
  hydrate?: HydrateOptions['defaultOptions'];
2788
4033
  /** Default options used when dehydrating the client's caches; see {@link DehydrateOptions}. */
2789
4034
  dehydrate?: DehydrateOptions;
@@ -2793,7 +4038,15 @@ interface DefaultOptions<TError = DefaultError> {
2793
4038
  * They are carried on the {@link CancelledError} that the cancelled fetch rejects with.
2794
4039
  */
2795
4040
  interface CancelOptions {
4041
+ /**
4042
+ * If `true`, the query goes back to the state it had before the fetch started, instead of getting
4043
+ * the cancellation error.
4044
+ */
2796
4045
  revert?: boolean;
4046
+ /**
4047
+ * If `true`, the cancellation error isn't surfaced, e.g. because another fetch replaces the
4048
+ * cancelled one.
4049
+ */
2797
4050
  silent?: boolean;
2798
4051
  }
2799
4052
  /**
@@ -2802,11 +4055,21 @@ interface CancelOptions {
2802
4055
  * omit it to use the current time.
2803
4056
  */
2804
4057
  interface SetDataOptions {
4058
+ /**
4059
+ * The timestamp to record the data with, instead of the current time. Staleness is measured from
4060
+ * it.
4061
+ */
2805
4062
  updatedAt?: number;
2806
4063
  }
2807
4064
  /** @inline */
2808
4065
  type NotifyEventType = 'added' | 'removed' | 'updated' | 'observerAdded' | 'observerRemoved' | 'observerResultsUpdated' | 'observerOptionsUpdated';
4066
+ /**
4067
+ * The base shape of the events that the query and mutation caches send to their listeners.
4068
+ */
2809
4069
  interface NotifyEvent {
4070
+ /**
4071
+ * The kind of event, e.g. `'added'`, `'removed'`, or `'updated'`.
4072
+ */
2810
4073
  type: NotifyEventType;
2811
4074
  }
2812
4075
  //#endregion
@@ -2866,7 +4129,13 @@ interface DehydratedQuery {
2866
4129
  * that has already been fetched, avoiding a redundant fetch on the client.
2867
4130
  */
2868
4131
  interface DehydratedState {
4132
+ /**
4133
+ * The dehydrated mutations, by default only the paused ones.
4134
+ */
2869
4135
  mutations: Array<DehydratedMutation>;
4136
+ /**
4137
+ * The dehydrated queries, by default only the successful ones.
4138
+ */
2870
4139
  queries: Array<DehydratedQuery>;
2871
4140
  }
2872
4141
  /**
@@ -2878,16 +4147,21 @@ interface DehydratedState {
2878
4147
  * @param serializeData - Optional transform applied to `query.state.data` before it is included in the snapshot.
2879
4148
  * @param shouldRedactErrors - Optional predicate; if it returns `false` for the promise's rejection error, that
2880
4149
  * error is kept as-is instead of being redacted.
4150
+ * @returns The dehydrated query.
2881
4151
  */
2882
4152
  declare function dehydrateQuery(query: Query, serializeData?: TransformerFn, shouldRedactErrors?: (error: unknown) => boolean): DehydratedQuery;
2883
4153
  /**
2884
4154
  * The default `shouldDehydrateMutation` predicate used by `dehydrate`. Only dehydrates mutations that are
2885
4155
  * currently paused (e.g. paused by `networkMode` while offline).
4156
+ * @param mutation - The mutation to check.
4157
+ * @returns `true` if the mutation is paused.
2886
4158
  */
2887
4159
  declare function defaultShouldDehydrateMutation(mutation: Mutation): boolean;
2888
4160
  /**
2889
4161
  * The default `shouldDehydrateQuery` predicate used by `dehydrate`. Only dehydrates queries whose status is
2890
4162
  * `'success'`.
4163
+ * @param query - The query to check.
4164
+ * @returns `true` if the query's status is `'success'`.
2891
4165
  */
2892
4166
  declare function defaultShouldDehydrateQuery(query: Query): boolean;
2893
4167
  /**
@@ -2896,6 +4170,10 @@ declare function defaultShouldDehydrateQuery(query: Query): boolean;
2896
4170
  * Which queries/mutations are included, and how their data/errors are transformed, is controlled by `options`,
2897
4171
  * falling back to the client's `dehydrate` default options, and finally to `defaultShouldDehydrateQuery` /
2898
4172
  * `defaultShouldDehydrateMutation`.
4173
+ * @param client - The client whose cache is dehydrated.
4174
+ * @param options - Controls which queries and mutations are included and how their data and errors
4175
+ * are transformed. Each option falls back to the client's `defaultOptions.dehydrate`.
4176
+ * @returns The dehydrated state, with the included `queries` and `mutations`.
2899
4177
  * @example
2900
4178
  * ```ts
2901
4179
  * const queryClient = new QueryClient()
@@ -2917,6 +4195,10 @@ declare function dehydrate(client: QueryClient, options?: DehydrateOptions): Deh
2917
4195
  * to `'idle'` so they don't hydrate stuck in a fetching state. If a dehydrated query still had an in-flight
2918
4196
  * promise, it is resumed via `query.fetch()` (reusing that promise as `initialPromise`) rather than re-invoking
2919
4197
  * `queryFn`.
4198
+ * @param client - The client whose cache is restored into.
4199
+ * @param dehydratedState - The dehydrated state, e.g. produced by `dehydrate` on the server.
4200
+ * @param options - `defaultOptions` merged into every restored query and mutation (on top of the
4201
+ * client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`.
2920
4202
  * @example
2921
4203
  * ```ts
2922
4204
  * // dehydratedState was produced by `dehydrate` on the server
@@ -2929,4 +4211,4 @@ declare function dehydrate(client: QueryClient, options?: DehydrateOptions): Deh
2929
4211
  declare function hydrate(client: QueryClient, dehydratedState: Partial<DehydratedState>, options?: HydrateOptions): void;
2930
4212
  //#endregion
2931
4213
  export { MutationObserverBaseResult as $, Query as $n, CancelledError as $t, InfiniteData as A, noop as An, QueryObserverOptions as At, InfiniteQueryObserverSuccessResult as B, Action as Bn, RefetchQueryFilters as Bt, FetchPreviousPageOptions as C, isPlainArray as Cn, QueryKey as Ct, GetPreviousPageParamFunction as D, keepPreviousData as Dn, QueryObserverBaseResult as Dt, GetNextPageParamFunction as E, isValidTimeout as En, QueryMeta as Et, InfiniteQueryObserverOptions as F, shallowEqualObjects as Fn, QueryObserverSuccessResult as Ft, InvalidateQueryFilters as G, MutationCacheConfig as Gn, StaleTime as Gt, InitialDataFunction as H, MutationState as Hn, ResetOptions as Ht, InfiniteQueryObserverPendingResult as I, shouldThrowError as In, QueryOptions as It, MutateOptions as J, Action$1 as Jn, UnsetMarker as Jt, MutateFunction as K, MutationCacheNotifyEvent as Kn, StaleTimeFunction as Kt, InfiniteQueryObserverPlaceholderResult as L, skipToken as Ln, QueryPersister as Lt, InfiniteQueryObserverBaseResult as M, replaceData as Mn, QueryObserverPlaceholderResult as Mt, InfiniteQueryObserverLoadingErrorResult as N, replaceEqualDeep as Nn, QueryObserverRefetchErrorResult as Nt, InferDataFromTag as O, matchMutation as On, QueryObserverLoadingErrorResult as Ot, InfiniteQueryObserverLoadingResult as P, resolveQueryValue as Pn, QueryObserverResult as Pt, MutationMeta as Q, FetchOptions as Qn, unsetMarker as Qt, InfiniteQueryObserverRefetchErrorResult as R, sleep as Rn, QueryStatus as Rt, FetchNextPageOptions as S, hashQueryKeyByOptions as Sn, QueryFunctionContext as St, FetchStatus as T, isServer as Tn, QueryKeyWithDataTag as Tt, InitialPageParam as U, getDefaultState as Un, ResultOptions as Ut, InfiniteQueryPageParamsOptions as V, Mutation as Vn, Register as Vt, InvalidateOptions as W, MutationCache as Wn, SetDataOptions as Wt, MutationFunctionContext as X, FetchDirection as Xn, dataTagErrorSymbol as Xt, MutationFunction as Y, FetchContext as Yn, WithRequired as Yt, MutationKey as Z, FetchMeta as Zn, dataTagSymbol as Zt, DefinedQueryObserverResult as _, addToEnd as _n, QueriesPlaceholderDataFunction as _t, defaultShouldDehydrateQuery as a, isCancelledError as an, MutationObserverSuccessResult as at, EnsureQueryDataOptions as b, functionalUpdate as bn, QueryExecuteOptions as bt, hydrate as c, QueryCacheConfig as cn, MutationStatus as ct, DataTag as d, MutationFilters as dn, NotifyEvent as dt, RetryDelayValue as en, QueryBehavior as er, MutationObserverErrorResult as et, DefaultError as f, QueryFilters as fn, NotifyEventType as ft, DefinedInfiniteQueryObserverResult as g, addConsumeAwareSignal as gn, PlaceholderDataFunction as gt, DefaultedQueryObserverOptions as h, Updater as hn, Override as ht, defaultShouldDehydrateMutation as i, createRetryer as in, MutationObserverResult as it, InfiniteQueryExecuteOptions as j, partialMatchKey as jn, QueryObserverPendingResult as jt, InferErrorFromTag as k, matchQuery as kn, QueryObserverLoadingResult as kt, AnyDataTag as l, QueryCacheNotifyEvent as ln, NetworkMode as lt, DefaultedInfiniteQueryObserverOptions as m, SkipToken as mn, OmitKeyof as mt, DehydratedState as n, Retryer as nn, fetchState as nr, MutationObserverLoadingResult as nt, dehydrate as o, QueryClient as on, MutationOptions as ot, DefaultOptions as p, QueryTypeFilter as pn, NotifyOnChangeProps as pt, MutateFunctionRest as q, MutationObserver as qn, ThrowOnError as qt, HydrateOptions as r, canFetch as rn, QueryObserver as rr, MutationObserverOptions as rt, dehydrateQuery as s, QueryCache as sn, MutationScope as st, DehydrateOptions as t, RetryValue as tn, QueryState as tr, MutationObserverIdleResult as tt, CancelOptions as u, QueryStore as un, NonUndefinedGuard as ut, DistributiveOmit as v, addToStart as vn, QueryBooleanOption as vt, FetchQueryOptions as w, isPlainObject as wn, QueryKeyHashFunction as wt, FetchInfiniteQueryOptions as x, hashKey as xn, QueryFunction as xt, EnsureInfiniteQueryDataOptions as y, ensureQueryFn as yn, QueryClientConfig as yt, InfiniteQueryObserverResult as z, timeUntilStale as zn, RefetchOptions as zt };
2932
- //# sourceMappingURL=hydration-Br9VIGXa.d.cts.map
4214
+ //# sourceMappingURL=hydration-C6zghADG.d.cts.map