@tanstack/query-core 5.104.1 → 5.104.2

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-Dfuxd5FW.d.cts} +1410 -128
  18. package/build/legacy/hydration-Dfuxd5FW.d.cts.map +1 -0
  19. package/build/legacy/{hydration-Br9VIGXa.d.cts → hydration-UAqdtMIf.d.ts} +1410 -128
  20. package/build/legacy/hydration-UAqdtMIf.d.ts.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-Dfuxd5FW.d.cts} +1410 -128
  180. package/build/modern/hydration-Dfuxd5FW.d.cts.map +1 -0
  181. package/build/modern/{hydration-Br9VIGXa.d.cts → hydration-UAqdtMIf.d.ts} +1410 -128
  182. package/build/modern/hydration-UAqdtMIf.d.ts.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 +110 -38
  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
package/src/types.ts CHANGED
@@ -9,24 +9,40 @@ import type { QueryFilters, QueryTypeFilter, SkipToken } from './utils'
9
9
  import type { QueryCache } from './queryCache'
10
10
  import type { MutationCache } from './mutationCache'
11
11
 
12
+ /**
13
+ * Excludes `undefined` from `T`. Used where a value must be defined, such as the data type that a
14
+ * defined `initialData` resolves to.
15
+ */
12
16
  export type NonUndefinedGuard<T> = T extends undefined ? never : T
13
17
 
18
+ /**
19
+ * Like `Omit`, but applied to each member of a union separately, so each member keeps its own keys.
20
+ */
14
21
  export type DistributiveOmit<
15
22
  TObject,
16
23
  TKey extends keyof TObject,
17
24
  > = TObject extends any ? Omit<TObject, TKey> : never
18
25
 
26
+ /**
27
+ * Like `Omit`, but by default (`'strictly'`) `TKey` must be a key of `TObject`, so omitting a key
28
+ * that doesn't exist is a type error. Pass `'safely'` to allow other keys too.
29
+ */
19
30
  export type OmitKeyof<
20
31
  TObject,
21
32
  TKey extends (TStrictly extends 'safely'
22
- ? | keyof TObject
23
- | (string & Record<never, never>)
24
- | (number & Record<never, never>)
25
- | (symbol & Record<never, never>)
33
+ ?
34
+ | keyof TObject
35
+ | (string & Record<never, never>)
36
+ | (number & Record<never, never>)
37
+ | (symbol & Record<never, never>)
26
38
  : keyof TObject),
27
39
  TStrictly extends 'strictly' | 'safely' = 'strictly',
28
40
  > = Omit<TObject, TKey>
29
41
 
42
+ /**
43
+ * Replaces the types of the properties of `TTargetA` that also exist in `TTargetB` with their types
44
+ * in `TTargetB`. Properties that only exist in `TTargetB` are not added.
45
+ */
30
46
  export type Override<TTargetA, TTargetB> = {
31
47
  [AKey in keyof TTargetA]: AKey extends keyof TTargetB
32
48
  ? TTargetB[AKey]
@@ -85,15 +101,39 @@ export type QueryKey = Register extends {
85
101
  : ReadonlyArray<unknown>
86
102
 
87
103
  export const dataTagSymbol = Symbol()
104
+ /**
105
+ * The type of the `dataTagSymbol` key, under which a {@link DataTag} stores its data type.
106
+ */
88
107
  export type dataTagSymbol = typeof dataTagSymbol
89
108
  export const dataTagErrorSymbol = Symbol()
109
+ /**
110
+ * The type of the `dataTagErrorSymbol` key, under which a {@link DataTag} stores its error type.
111
+ */
90
112
  export type dataTagErrorSymbol = typeof dataTagErrorSymbol
91
113
  export const unsetMarker = Symbol()
114
+ /**
115
+ * The type of `unsetMarker`, the default error type of a {@link DataTag}. It marks that no error
116
+ * type was tagged.
117
+ */
92
118
  export type UnsetMarker = typeof unsetMarker
119
+ /**
120
+ * Matches any type that has been tagged with {@link DataTag}, whatever its data and error types.
121
+ */
93
122
  export type AnyDataTag = {
123
+ /**
124
+ * The data type the key was tagged with.
125
+ */
94
126
  [dataTagSymbol]: any
127
+ /**
128
+ * The error type the key was tagged with.
129
+ */
95
130
  [dataTagErrorSymbol]: any
96
131
  }
132
+ /**
133
+ * Tags `TType` (usually a query key) with a data type and an optional error type, so that APIs that
134
+ * receive it, like `queryClient.getQueryData`, can infer them. A type that is already tagged is
135
+ * returned as is.
136
+ */
97
137
  export type DataTag<
98
138
  TType,
99
139
  TValue,
@@ -105,19 +145,34 @@ export type DataTag<
105
145
  [dataTagErrorSymbol]: TError
106
146
  }
107
147
 
148
+ /**
149
+ * An object whose `queryKey` is tagged with {@link DataTag}, like the options returned by
150
+ * `queryOptions`.
151
+ */
108
152
  export type QueryKeyWithDataTag<
109
153
  TQueryKey extends QueryKey = QueryKey,
110
154
  TQueryFnData = unknown,
111
155
  TError = DefaultError,
112
156
  > = {
157
+ /**
158
+ * The query key, tagged with the query's data and error types.
159
+ */
113
160
  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
114
161
  }
115
162
 
163
+ /**
164
+ * The data type tagged on a query key by {@link DataTag}, or `TQueryFnData` if the key is not
165
+ * tagged.
166
+ */
116
167
  export type InferDataFromTag<TQueryFnData, TTaggedQueryKey extends QueryKey> =
117
168
  TTaggedQueryKey extends DataTag<unknown, infer TaggedValue, unknown>
118
169
  ? TaggedValue
119
170
  : TQueryFnData
120
171
 
172
+ /**
173
+ * The error type tagged on a query key by {@link DataTag}, or `TError` if the key is not tagged or
174
+ * was tagged without an error type.
175
+ */
121
176
  export type InferErrorFromTag<TError, TTaggedQueryKey extends QueryKey> =
122
177
  TTaggedQueryKey extends DataTag<unknown, unknown, infer TaggedError>
123
178
  ? TaggedError extends UnsetMarker
@@ -152,7 +207,8 @@ export type QueryBooleanOption<
152
207
  TData = TQueryFnData,
153
208
  TQueryKey extends QueryKey = QueryKey,
154
209
  > =
155
- boolean | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
210
+ | boolean
211
+ | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
156
212
 
157
213
  /** @inline */
158
214
  export type QueryPersister<
@@ -171,6 +227,11 @@ export type QueryPersister<
171
227
  query: Query,
172
228
  ) => T | Promise<T>
173
229
 
230
+ /**
231
+ * The object passed to `queryFn`: the `QueryClient`, the `queryKey`, an `AbortSignal` that aborts
232
+ * when the query is cancelled, the query's `meta`, and for infinite queries the `pageParam` of the
233
+ * page being fetched.
234
+ */
174
235
  export type QueryFunctionContext<
175
236
  TQueryKey extends QueryKey = QueryKey,
176
237
  TPageParam = never,
@@ -216,6 +277,11 @@ export type PlaceholderDataFunction<
216
277
  previousQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined,
217
278
  ) => TQueryData | undefined
218
279
 
280
+ /**
281
+ * The `placeholderData` function of a query in `useQueries` and its counterparts. Unlike
282
+ * {@link PlaceholderDataFunction}, it receives no previous data or query, because the number of
283
+ * queries can differ between renders.
284
+ */
219
285
  export type QueriesPlaceholderDataFunction<TQueryData> = (
220
286
  previousData: undefined,
221
287
  previousQuery: undefined,
@@ -247,7 +313,13 @@ export type GetNextPageParamFunction<TPageParam, TQueryFnData = unknown> = (
247
313
  * `pages` and `pageParams` are index-aligned — `pageParams[i]` is the param that produced `pages[i]`.
248
314
  */
249
315
  export interface InfiniteData<TData, TPageParam = unknown> {
316
+ /**
317
+ * The data of every page fetched so far, in order.
318
+ */
250
319
  pages: Array<TData>
320
+ /**
321
+ * The page param each page was fetched with, aligned by index with `pages`.
322
+ */
251
323
  pageParams: Array<TPageParam>
252
324
  }
253
325
 
@@ -273,6 +345,10 @@ export type NotifyOnChangeProps =
273
345
  | undefined
274
346
  | (() => Array<keyof InfiniteQueryObserverResult> | 'all' | undefined)
275
347
 
348
+ /**
349
+ * The options of a query itself — its `queryKey`, `queryFn`, retries, `gcTime`, `initialData`,
350
+ * `meta`, and so on — shared by observers and the `QueryClient` methods that fetch queries.
351
+ */
276
352
  export interface QueryOptions<
277
353
  TQueryFnData = unknown,
278
354
  TError = DefaultError,
@@ -303,7 +379,6 @@ export interface QueryOptions<
303
379
  retryDelay?: RetryDelayValue<TError>
304
380
  /**
305
381
  * Controls whether a query is allowed to run based on the current network connectivity.
306
- *
307
382
  * @defaultValue 'online'
308
383
  * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
309
384
  */
@@ -369,11 +444,11 @@ export interface QueryOptions<
369
444
  /**
370
445
  * Set this to `false` to disable structural sharing between query results.
371
446
  * 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.
372
- *
373
447
  * @defaultValue true
374
448
  */
375
449
  structuralSharing?:
376
- boolean | ((oldData: unknown | undefined, newData: unknown) => unknown)
450
+ | boolean
451
+ | ((oldData: unknown | undefined, newData: unknown) => unknown)
377
452
  /** @internal */
378
453
  _defaulted?: boolean
379
454
  /** @internal */
@@ -389,6 +464,9 @@ export interface QueryOptions<
389
464
  maxPages?: number
390
465
  }
391
466
 
467
+ /**
468
+ * Holds the `initialPageParam` option that every infinite query requires.
469
+ */
392
470
  export interface InitialPageParam<TPageParam = unknown> {
393
471
  /**
394
472
  * The page param to start from when an infinite query has no pages yet.
@@ -400,6 +478,10 @@ export interface InitialPageParam<TPageParam = unknown> {
400
478
  initialPageParam: TPageParam
401
479
  }
402
480
 
481
+ /**
482
+ * The page param options of an infinite query: `initialPageParam`, and the `getNextPageParam` and
483
+ * `getPreviousPageParam` functions that compute the params of the pages around it.
484
+ */
403
485
  export interface InfiniteQueryPageParamsOptions<
404
486
  TQueryFnData = unknown,
405
487
  TPageParam = unknown,
@@ -429,6 +511,11 @@ export type ThrowOnError<
429
511
  query: Query<TQueryFnData, TError, TQueryData, TQueryKey>,
430
512
  ) => boolean)
431
513
 
514
+ /**
515
+ * The options of a `QueryObserver`, and of the hooks built on it like `useQuery`: the
516
+ * {@link QueryOptions} of the query, plus options that control the observer, such as `enabled`,
517
+ * `staleTime`, `refetchInterval`, `select`, and `placeholderData`.
518
+ */
432
519
  export interface QueryObserverOptions<
433
520
  TQueryFnData = unknown,
434
521
  TError = DefaultError,
@@ -444,7 +531,6 @@ export interface QueryObserverOptions<
444
531
  * Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys.
445
532
  * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
446
533
  * Accepts a boolean or function that returns a boolean.
447
- *
448
534
  * @defaultValue true
449
535
  */
450
536
  enabled?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>
@@ -453,14 +539,12 @@ export interface QueryObserverOptions<
453
539
  * If set to `Infinity`, the data will never be considered stale.
454
540
  * If set to `'static'`, the data will never be considered stale.
455
541
  * If set to a function, the function will be executed with the query to compute a `staleTime`.
456
- *
457
542
  * @defaultValue 0
458
543
  */
459
544
  staleTime?: StaleTimeFunction<TQueryFnData, TError, TQueryData, TQueryKey>
460
545
  /**
461
546
  * If set to a number, the query will continuously refetch at this frequency in milliseconds.
462
547
  * If set to a function, the function will be executed with the latest data and query to compute a frequency
463
- *
464
548
  * @defaultValue false
465
549
  */
466
550
  refetchInterval?:
@@ -471,7 +555,6 @@ export interface QueryObserverOptions<
471
555
  ) => number | false | undefined)
472
556
  /**
473
557
  * If set to `true`, the query will continue to refetch while their tab/window is in the background.
474
- *
475
558
  * @defaultValue false
476
559
  */
477
560
  refetchIntervalInBackground?: boolean
@@ -480,7 +563,6 @@ export interface QueryObserverOptions<
480
563
  * If set to `false`, the query will not refetch on window focus.
481
564
  * If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used).
482
565
  * If set to a function, the function will be executed with the latest data and query to compute the value.
483
- *
484
566
  * @defaultValue true
485
567
  */
486
568
  refetchOnWindowFocus?:
@@ -508,7 +590,6 @@ export interface QueryObserverOptions<
508
590
  * If set to `false`, will disable additional instances of a query to trigger background refetch.
509
591
  * If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used).
510
592
  * If set to a function, the function will be executed with the latest data and query to compute the value
511
- *
512
593
  * @defaultValue true
513
594
  */
514
595
  refetchOnMount?:
@@ -520,7 +601,6 @@ export interface QueryObserverOptions<
520
601
  /**
521
602
  * If set to `false`, the query will not be retried on mount if it contains an error.
522
603
  * If set to a function, the function will be executed with the query to compute the value.
523
- *
524
604
  * @defaultValue true
525
605
  */
526
606
  retryOnMount?: QueryBooleanOption<TQueryFnData, TError, TQueryData, TQueryKey>
@@ -539,7 +619,6 @@ export interface QueryObserverOptions<
539
619
  * If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary.
540
620
  * If set to `false` and `suspense` is `false`, errors are returned as state.
541
621
  * 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`).
542
- *
543
622
  * @defaultValue false
544
623
  */
545
624
  throwOnError?: ThrowOnError<TQueryFnData, TError, TQueryData, TQueryKey>
@@ -553,7 +632,6 @@ export interface QueryObserverOptions<
553
632
  /**
554
633
  * If set to `true`, the query will suspend when `status === 'pending'`
555
634
  * and throw errors when `status === 'error'`.
556
- *
557
635
  * @defaultValue false
558
636
  */
559
637
  suspense?: boolean
@@ -573,10 +651,17 @@ export interface QueryObserverOptions<
573
651
  _optimisticResults?: 'optimistic' | 'isRestoring'
574
652
  }
575
653
 
654
+ /**
655
+ * Makes the `TKey` properties of `TTarget` required and non-nullable.
656
+ */
576
657
  export type WithRequired<TTarget, TKey extends keyof TTarget> = TTarget & {
577
658
  [_ in TKey]: {}
578
659
  }
579
660
 
661
+ /**
662
+ * The {@link QueryObserverOptions} after `QueryClient#defaultQueryOptions` has applied the
663
+ * defaults, so `throwOnError`, `refetchOnReconnect`, and `queryHash` are always set.
664
+ */
580
665
  export type DefaultedQueryObserverOptions<
581
666
  TQueryFnData = unknown,
582
667
  TError = DefaultError,
@@ -588,6 +673,10 @@ export type DefaultedQueryObserverOptions<
588
673
  'throwOnError' | 'refetchOnReconnect' | 'queryHash'
589
674
  >
590
675
 
676
+ /**
677
+ * The options of an `InfiniteQueryObserver`: {@link QueryObserverOptions} whose query data is
678
+ * {@link InfiniteData}, plus the page param options.
679
+ */
591
680
  export interface InfiniteQueryObserverOptions<
592
681
  TQueryFnData = unknown,
593
682
  TError = DefaultError,
@@ -606,6 +695,10 @@ export interface InfiniteQueryObserverOptions<
606
695
  >,
607
696
  InfiniteQueryPageParamsOptions<TQueryFnData, TPageParam> {}
608
697
 
698
+ /**
699
+ * The {@link InfiniteQueryObserverOptions} after `QueryClient#defaultQueryOptions` has applied the
700
+ * defaults, so `throwOnError`, `refetchOnReconnect`, and `queryHash` are always set.
701
+ */
609
702
  export type DefaultedInfiniteQueryObserverOptions<
610
703
  TQueryFnData = unknown,
611
704
  TError = DefaultError,
@@ -623,6 +716,11 @@ export type DefaultedInfiniteQueryObserverOptions<
623
716
  'throwOnError' | 'refetchOnReconnect' | 'queryHash'
624
717
  >
625
718
 
719
+ /**
720
+ * The options of `queryClient.query`: the {@link QueryOptions} of the query, plus a `staleTime`
721
+ * that decides whether cached data is returned instead of fetching, and a `select` that only
722
+ * transforms the value the call resolves with.
723
+ */
626
724
  export interface QueryExecuteOptions<
627
725
  TQueryFnData = unknown,
628
726
  TError = DefaultError,
@@ -634,6 +732,9 @@ export interface QueryExecuteOptions<
634
732
  QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey, TPageParam>,
635
733
  'queryKey'
636
734
  > {
735
+ /**
736
+ * Not allowed here, since `initialPageParam` only applies to infinite queries.
737
+ */
637
738
  initialPageParam?: never
638
739
  /**
639
740
  * This option can be used to transform or select a part of the data returned by the query function. It affects
@@ -658,6 +759,9 @@ export interface FetchQueryOptions<
658
759
  QueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
659
760
  'queryKey'
660
761
  > {
762
+ /**
763
+ * Not allowed here, since `initialPageParam` only applies to infinite queries.
764
+ */
661
765
  initialPageParam?: never
662
766
  /**
663
767
  * The time in milliseconds after data is considered stale.
@@ -680,6 +784,9 @@ export interface EnsureQueryDataOptions<
680
784
  TQueryKey,
681
785
  TPageParam
682
786
  > {
787
+ /**
788
+ * If `true`, stale cached data is returned and also refetched in the background.
789
+ */
683
790
  revalidateIfStale?: boolean
684
791
  }
685
792
 
@@ -707,6 +814,11 @@ type InfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> =
707
814
  getNextPageParam: GetNextPageParamFunction<TPageParam, TQueryFnData>
708
815
  }
709
816
 
817
+ /**
818
+ * The options of `queryClient.infiniteQuery`: like {@link QueryExecuteOptions}, with the
819
+ * `initialPageParam`, and optionally `pages` together with `getNextPageParam` to fetch that many
820
+ * pages at once.
821
+ */
710
822
  export type InfiniteQueryExecuteOptions<
711
823
  TQueryFnData = unknown,
712
824
  TError = DefaultError,
@@ -747,27 +859,36 @@ export type FetchInfiniteQueryOptions<
747
859
  InitialPageParam<TPageParam> &
748
860
  InfiniteQueryPages<TQueryFnData, TPageParam>
749
861
 
862
+ /**
863
+ * Options shared by the `QueryClient` and observer methods that refetch queries, controlling
864
+ * whether a failed refetch makes the returned promise reject.
865
+ */
750
866
  export interface ResultOptions {
751
867
  /**
752
868
  * If set to `true`, the method throws if any of the underlying query refetch tasks fail.
753
869
  * If set to `false`, failed refetches are swallowed and not surfaced to the caller.
754
- *
755
870
  * @defaultValue false
756
871
  */
757
872
  throwOnError?: boolean
758
873
  }
759
874
 
875
+ /**
876
+ * Options of the methods that refetch queries, like `refetch` and `queryClient.refetchQueries`.
877
+ */
760
878
  export interface RefetchOptions extends ResultOptions {
761
879
  /**
762
880
  * If set to `true`, a currently running request will be cancelled before a new request is made
763
881
  *
764
882
  * If set to `false`, no refetch will be made if there is already a request running.
765
- *
766
883
  * @defaultValue true
767
884
  */
768
885
  cancelRefetch?: boolean
769
886
  }
770
887
 
888
+ /**
889
+ * The filters of `queryClient.invalidateQueries`: the {@link QueryFilters} that select the queries
890
+ * to invalidate, plus `refetchType` to choose which of them are refetched.
891
+ */
771
892
  export interface InvalidateQueryFilters<
772
893
  TQueryKey extends QueryKey = QueryKey,
773
894
  > extends QueryFilters<TQueryKey> {
@@ -778,38 +899,51 @@ export interface InvalidateQueryFilters<
778
899
  * - `'inactive'`: only queries with no active observer are refetched.
779
900
  * - `'all'`: every matched query is refetched, active or not.
780
901
  * - `'none'`: no query is refetched; matched queries are only marked as invalidated.
781
- *
782
902
  * @defaultValue 'active'
783
903
  */
784
904
  refetchType?: QueryTypeFilter | 'none'
785
905
  }
786
906
 
907
+ /**
908
+ * The filters of `queryClient.refetchQueries`, which select the queries to refetch.
909
+ */
787
910
  export interface RefetchQueryFilters<
788
911
  TQueryKey extends QueryKey = QueryKey,
789
912
  > extends QueryFilters<TQueryKey> {}
790
913
 
914
+ /**
915
+ * Options of `queryClient.invalidateQueries`, applied to the refetch that follows the invalidation.
916
+ */
791
917
  export interface InvalidateOptions extends RefetchOptions {}
918
+ /**
919
+ * Options of `queryClient.resetQueries`, applied to the refetch of the active queries after the
920
+ * reset.
921
+ */
792
922
  export interface ResetOptions extends RefetchOptions {}
793
923
 
924
+ /**
925
+ * Options of `fetchNextPage` on an infinite query result.
926
+ */
794
927
  export interface FetchNextPageOptions extends ResultOptions {
795
928
  /**
796
929
  * If set to `true`, calling `fetchNextPage` repeatedly will invoke `queryFn` every time,
797
930
  * whether the previous invocation has resolved or not. Also, the result from previous invocations will be ignored.
798
931
  *
799
932
  * If set to `false`, calling `fetchNextPage` repeatedly won't have any effect until the first invocation has resolved.
800
- *
801
933
  * @defaultValue true
802
934
  */
803
935
  cancelRefetch?: boolean
804
936
  }
805
937
 
938
+ /**
939
+ * Options of `fetchPreviousPage` on an infinite query result.
940
+ */
806
941
  export interface FetchPreviousPageOptions extends ResultOptions {
807
942
  /**
808
943
  * If set to `true`, calling `fetchPreviousPage` repeatedly will invoke `queryFn` every time,
809
944
  * whether the previous invocation has resolved or not. Also, the result from previous invocations will be ignored.
810
945
  *
811
946
  * If set to `false`, calling `fetchPreviousPage` repeatedly won't have any effect until the first invocation has resolved.
812
- *
813
947
  * @defaultValue true
814
948
  */
815
949
  cancelRefetch?: boolean
@@ -820,6 +954,10 @@ export type QueryStatus = 'pending' | 'error' | 'success'
820
954
  /** @inline */
821
955
  export type FetchStatus = 'fetching' | 'paused' | 'idle'
822
956
 
957
+ /**
958
+ * The properties shared by every state of a query result, like `data`, `error`, `status`, the
959
+ * `is*` flags, and `refetch`. Each `QueryObserver*Result` narrows them for one state.
960
+ */
823
961
  export interface QueryObserverBaseResult<
824
962
  TData = unknown,
825
963
  TError = DefaultError,
@@ -948,105 +1086,314 @@ export interface QueryObserverBaseResult<
948
1086
  fetchStatus: FetchStatus
949
1087
  }
950
1088
 
1089
+ /**
1090
+ * A query result in the `pending` state: the query has no data yet.
1091
+ */
951
1092
  export interface QueryObserverPendingResult<
952
1093
  TData = unknown,
953
1094
  TError = DefaultError,
954
1095
  > extends QueryObserverBaseResult<TData, TError> {
1096
+ /**
1097
+ * `undefined`, since the query has no data yet.
1098
+ */
955
1099
  data: undefined
1100
+ /**
1101
+ * `null`, since the query isn't in the `error` state.
1102
+ */
956
1103
  error: null
1104
+ /**
1105
+ * `false`, since the query isn't in the `error` state.
1106
+ */
957
1107
  isError: false
1108
+ /**
1109
+ * `true`, since there's no cached data and no query attempt has finished yet.
1110
+ */
958
1111
  isPending: true
1112
+ /**
1113
+ * `false`, since the query didn't fail while fetching for the first time.
1114
+ */
959
1115
  isLoadingError: false
1116
+ /**
1117
+ * `false`, since the query didn't fail while refetching.
1118
+ */
960
1119
  isRefetchError: false
1120
+ /**
1121
+ * `false`, since the query isn't in the `success` state.
1122
+ */
961
1123
  isSuccess: false
1124
+ /**
1125
+ * `false`, since the data shown isn't the `placeholderData`.
1126
+ */
962
1127
  isPlaceholderData: false
1128
+ /**
1129
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
1130
+ */
963
1131
  status: 'pending'
964
1132
  }
965
1133
 
1134
+ /**
1135
+ * A query result in the `pending` state while the first fetch is in flight, so `isLoading` is
1136
+ * `true`.
1137
+ */
966
1138
  export interface QueryObserverLoadingResult<
967
1139
  TData = unknown,
968
1140
  TError = DefaultError,
969
1141
  > extends QueryObserverBaseResult<TData, TError> {
1142
+ /**
1143
+ * `undefined`, since the query has no data yet.
1144
+ */
970
1145
  data: undefined
1146
+ /**
1147
+ * `null`, since the query isn't in the `error` state.
1148
+ */
971
1149
  error: null
1150
+ /**
1151
+ * `false`, since the query isn't in the `error` state.
1152
+ */
972
1153
  isError: false
1154
+ /**
1155
+ * `true`, since there's no cached data and no query attempt has finished yet.
1156
+ */
973
1157
  isPending: true
1158
+ /**
1159
+ * `true`, since the first fetch is in flight.
1160
+ */
974
1161
  isLoading: true
1162
+ /**
1163
+ * `false`, since the query didn't fail while fetching for the first time.
1164
+ */
975
1165
  isLoadingError: false
1166
+ /**
1167
+ * `false`, since the query didn't fail while refetching.
1168
+ */
976
1169
  isRefetchError: false
1170
+ /**
1171
+ * `false`, since the query isn't in the `success` state.
1172
+ */
977
1173
  isSuccess: false
1174
+ /**
1175
+ * `false`, since the data shown isn't the `placeholderData`.
1176
+ */
978
1177
  isPlaceholderData: false
1178
+ /**
1179
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
1180
+ */
979
1181
  status: 'pending'
980
1182
  }
981
1183
 
1184
+ /**
1185
+ * A query result in the `error` state when the first fetch failed, so there is no data.
1186
+ */
982
1187
  export interface QueryObserverLoadingErrorResult<
983
1188
  TData = unknown,
984
1189
  TError = DefaultError,
985
1190
  > extends QueryObserverBaseResult<TData, TError> {
1191
+ /**
1192
+ * `undefined`, since the first fetch failed before any data was cached.
1193
+ */
986
1194
  data: undefined
1195
+ /**
1196
+ * The error the first fetch failed with.
1197
+ */
987
1198
  error: TError
1199
+ /**
1200
+ * `true`, since the query is in the `error` state.
1201
+ */
988
1202
  isError: true
1203
+ /**
1204
+ * `false`, since the query has data or a query attempt has finished.
1205
+ */
989
1206
  isPending: false
1207
+ /**
1208
+ * `false`, since the first fetch isn't in flight.
1209
+ */
990
1210
  isLoading: false
1211
+ /**
1212
+ * `true`, since the query failed while fetching for the first time.
1213
+ */
991
1214
  isLoadingError: true
1215
+ /**
1216
+ * `false`, since the query didn't fail while refetching.
1217
+ */
992
1218
  isRefetchError: false
1219
+ /**
1220
+ * `false`, since the query isn't in the `success` state.
1221
+ */
993
1222
  isSuccess: false
1223
+ /**
1224
+ * `false`, since the data shown isn't the `placeholderData`.
1225
+ */
994
1226
  isPlaceholderData: false
1227
+ /**
1228
+ * `'error'`, since the query attempt resulted in an error.
1229
+ */
995
1230
  status: 'error'
996
1231
  }
997
1232
 
1233
+ /**
1234
+ * A query result in the `error` state when a refetch failed, so the data from before is kept.
1235
+ */
998
1236
  export interface QueryObserverRefetchErrorResult<
999
1237
  TData = unknown,
1000
1238
  TError = DefaultError,
1001
1239
  > extends QueryObserverBaseResult<TData, TError> {
1240
+ /**
1241
+ * The data from before the failed refetch, which is kept.
1242
+ */
1002
1243
  data: TData
1244
+ /**
1245
+ * The error the refetch failed with.
1246
+ */
1003
1247
  error: TError
1248
+ /**
1249
+ * `true`, since the query is in the `error` state.
1250
+ */
1004
1251
  isError: true
1252
+ /**
1253
+ * `false`, since the query has data or a query attempt has finished.
1254
+ */
1005
1255
  isPending: false
1256
+ /**
1257
+ * `false`, since the first fetch isn't in flight.
1258
+ */
1006
1259
  isLoading: false
1260
+ /**
1261
+ * `false`, since the query didn't fail while fetching for the first time.
1262
+ */
1007
1263
  isLoadingError: false
1264
+ /**
1265
+ * `true`, since the query failed while refetching.
1266
+ */
1008
1267
  isRefetchError: true
1268
+ /**
1269
+ * `false`, since the query isn't in the `success` state.
1270
+ */
1009
1271
  isSuccess: false
1272
+ /**
1273
+ * `false`, since the data shown isn't the `placeholderData`.
1274
+ */
1010
1275
  isPlaceholderData: false
1276
+ /**
1277
+ * `'error'`, since the query attempt resulted in an error.
1278
+ */
1011
1279
  status: 'error'
1012
1280
  }
1013
1281
 
1282
+ /**
1283
+ * A query result in the `success` state with data from the cache.
1284
+ */
1014
1285
  export interface QueryObserverSuccessResult<
1015
1286
  TData = unknown,
1016
1287
  TError = DefaultError,
1017
1288
  > extends QueryObserverBaseResult<TData, TError> {
1289
+ /**
1290
+ * The last successfully resolved data for the query.
1291
+ */
1018
1292
  data: TData
1293
+ /**
1294
+ * `null`, since the query isn't in the `error` state.
1295
+ */
1019
1296
  error: null
1297
+ /**
1298
+ * `false`, since the query isn't in the `error` state.
1299
+ */
1020
1300
  isError: false
1301
+ /**
1302
+ * `false`, since the query has data or a query attempt has finished.
1303
+ */
1021
1304
  isPending: false
1305
+ /**
1306
+ * `false`, since the first fetch isn't in flight.
1307
+ */
1022
1308
  isLoading: false
1309
+ /**
1310
+ * `false`, since the query didn't fail while fetching for the first time.
1311
+ */
1023
1312
  isLoadingError: false
1313
+ /**
1314
+ * `false`, since the query didn't fail while refetching.
1315
+ */
1024
1316
  isRefetchError: false
1317
+ /**
1318
+ * `true`, since the query is in the `success` state.
1319
+ */
1025
1320
  isSuccess: true
1321
+ /**
1322
+ * `false`, since the data shown isn't the `placeholderData`.
1323
+ */
1026
1324
  isPlaceholderData: false
1325
+ /**
1326
+ * `'success'`, since the query has received a response with no errors and is ready to display its
1327
+ * data.
1328
+ */
1027
1329
  status: 'success'
1028
1330
  }
1029
1331
 
1332
+ /**
1333
+ * A query result in the `success` state that shows `placeholderData` while the query has no data
1334
+ * yet.
1335
+ */
1030
1336
  export interface QueryObserverPlaceholderResult<
1031
1337
  TData = unknown,
1032
1338
  TError = DefaultError,
1033
1339
  > extends QueryObserverBaseResult<TData, TError> {
1340
+ /**
1341
+ * The `placeholderData` shown while the query has no data yet.
1342
+ */
1034
1343
  data: TData
1344
+ /**
1345
+ * `false`, since the query isn't in the `error` state.
1346
+ */
1035
1347
  isError: false
1348
+ /**
1349
+ * `null`, since the query isn't in the `error` state.
1350
+ */
1036
1351
  error: null
1352
+ /**
1353
+ * `false`, since the query has data or a query attempt has finished.
1354
+ */
1037
1355
  isPending: false
1356
+ /**
1357
+ * `false`, since the first fetch isn't in flight.
1358
+ */
1038
1359
  isLoading: false
1360
+ /**
1361
+ * `false`, since the query didn't fail while fetching for the first time.
1362
+ */
1039
1363
  isLoadingError: false
1364
+ /**
1365
+ * `false`, since the query didn't fail while refetching.
1366
+ */
1040
1367
  isRefetchError: false
1368
+ /**
1369
+ * `true`, since the query is in the `success` state.
1370
+ */
1041
1371
  isSuccess: true
1372
+ /**
1373
+ * `true`, since the data shown is the `placeholderData`.
1374
+ */
1042
1375
  isPlaceholderData: true
1376
+ /**
1377
+ * `'success'`, since the query has received a response with no errors and is ready to display its
1378
+ * data.
1379
+ */
1043
1380
  status: 'success'
1044
1381
  }
1045
1382
 
1046
- export type DefinedQueryObserverResult<TData = unknown, TError = DefaultError> =
1383
+ /**
1384
+ * A query result that always has `data`: the success and refetch error states.
1385
+ */
1386
+ export type DefinedQueryObserverResult<
1387
+ TData = unknown,
1388
+ TError = DefaultError,
1389
+ > =
1047
1390
  | QueryObserverRefetchErrorResult<TData, TError>
1048
1391
  | QueryObserverSuccessResult<TData, TError>
1049
1392
 
1393
+ /**
1394
+ * The result of a `QueryObserver`, and of the hooks built on it like `useQuery`. Narrow it by
1395
+ * `status` or the `is*` flags to get the type of each state.
1396
+ */
1050
1397
  export type QueryObserverResult<TData = unknown, TError = DefaultError> =
1051
1398
  | DefinedQueryObserverResult<TData, TError>
1052
1399
  | QueryObserverLoadingErrorResult<TData, TError>
@@ -1054,6 +1401,11 @@ export type QueryObserverResult<TData = unknown, TError = DefaultError> =
1054
1401
  | QueryObserverPendingResult<TData, TError>
1055
1402
  | QueryObserverPlaceholderResult<TData, TError>
1056
1403
 
1404
+ /**
1405
+ * The properties shared by every state of an infinite query result: those of
1406
+ * {@link QueryObserverBaseResult}, plus `fetchNextPage`, `fetchPreviousPage`, and the flags about
1407
+ * them, like `hasNextPage` and `isFetchingNextPage`.
1408
+ */
1057
1409
  export interface InfiniteQueryObserverBaseResult<
1058
1410
  TData = unknown,
1059
1411
  TError = DefaultError,
@@ -1096,111 +1448,344 @@ export interface InfiniteQueryObserverBaseResult<
1096
1448
  isFetchingPreviousPage: boolean
1097
1449
  }
1098
1450
 
1451
+ /**
1452
+ * An infinite query result in the `pending` state: the query has no data yet.
1453
+ */
1099
1454
  export interface InfiniteQueryObserverPendingResult<
1100
1455
  TData = unknown,
1101
1456
  TError = DefaultError,
1102
1457
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1458
+ /**
1459
+ * `undefined`, since the query has no data yet.
1460
+ */
1103
1461
  data: undefined
1462
+ /**
1463
+ * `null`, since the query isn't in the `error` state.
1464
+ */
1104
1465
  error: null
1466
+ /**
1467
+ * `false`, since the query isn't in the `error` state.
1468
+ */
1105
1469
  isError: false
1470
+ /**
1471
+ * `true`, since there's no cached data and no query attempt has finished yet.
1472
+ */
1106
1473
  isPending: true
1474
+ /**
1475
+ * `false`, since the query didn't fail while fetching for the first time.
1476
+ */
1107
1477
  isLoadingError: false
1478
+ /**
1479
+ * `false`, since the query didn't fail while refetching.
1480
+ */
1108
1481
  isRefetchError: false
1482
+ /**
1483
+ * `false`, since fetching the next page didn't fail.
1484
+ */
1109
1485
  isFetchNextPageError: false
1486
+ /**
1487
+ * `false`, since fetching the previous page didn't fail.
1488
+ */
1110
1489
  isFetchPreviousPageError: false
1490
+ /**
1491
+ * `false`, since the query isn't in the `success` state.
1492
+ */
1111
1493
  isSuccess: false
1494
+ /**
1495
+ * `false`, since the data shown isn't the `placeholderData`.
1496
+ */
1112
1497
  isPlaceholderData: false
1498
+ /**
1499
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
1500
+ */
1113
1501
  status: 'pending'
1114
1502
  }
1115
1503
 
1504
+ /**
1505
+ * An infinite query result in the `pending` state while the first fetch is in flight, so
1506
+ * `isLoading` is `true`.
1507
+ */
1116
1508
  export interface InfiniteQueryObserverLoadingResult<
1117
1509
  TData = unknown,
1118
1510
  TError = DefaultError,
1119
1511
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1512
+ /**
1513
+ * `undefined`, since the query has no data yet.
1514
+ */
1120
1515
  data: undefined
1516
+ /**
1517
+ * `null`, since the query isn't in the `error` state.
1518
+ */
1121
1519
  error: null
1520
+ /**
1521
+ * `false`, since the query isn't in the `error` state.
1522
+ */
1122
1523
  isError: false
1524
+ /**
1525
+ * `true`, since there's no cached data and no query attempt has finished yet.
1526
+ */
1123
1527
  isPending: true
1528
+ /**
1529
+ * `true`, since the first fetch is in flight.
1530
+ */
1124
1531
  isLoading: true
1532
+ /**
1533
+ * `false`, since the query didn't fail while fetching for the first time.
1534
+ */
1125
1535
  isLoadingError: false
1536
+ /**
1537
+ * `false`, since the query didn't fail while refetching.
1538
+ */
1126
1539
  isRefetchError: false
1540
+ /**
1541
+ * `false`, since fetching the next page didn't fail.
1542
+ */
1127
1543
  isFetchNextPageError: false
1544
+ /**
1545
+ * `false`, since fetching the previous page didn't fail.
1546
+ */
1128
1547
  isFetchPreviousPageError: false
1548
+ /**
1549
+ * `false`, since the query isn't in the `success` state.
1550
+ */
1129
1551
  isSuccess: false
1552
+ /**
1553
+ * `false`, since the data shown isn't the `placeholderData`.
1554
+ */
1130
1555
  isPlaceholderData: false
1556
+ /**
1557
+ * `'pending'`, since there's no cached data and no query attempt has finished yet.
1558
+ */
1131
1559
  status: 'pending'
1132
1560
  }
1133
1561
 
1562
+ /**
1563
+ * An infinite query result in the `error` state when the first fetch failed, so there is no data.
1564
+ */
1134
1565
  export interface InfiniteQueryObserverLoadingErrorResult<
1135
1566
  TData = unknown,
1136
1567
  TError = DefaultError,
1137
1568
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1569
+ /**
1570
+ * `undefined`, since the first fetch failed before any data was cached.
1571
+ */
1138
1572
  data: undefined
1573
+ /**
1574
+ * The error the first fetch failed with.
1575
+ */
1139
1576
  error: TError
1577
+ /**
1578
+ * `true`, since the query is in the `error` state.
1579
+ */
1140
1580
  isError: true
1581
+ /**
1582
+ * `false`, since the query has data or a query attempt has finished.
1583
+ */
1141
1584
  isPending: false
1585
+ /**
1586
+ * `false`, since the first fetch isn't in flight.
1587
+ */
1142
1588
  isLoading: false
1589
+ /**
1590
+ * `true`, since the query failed while fetching for the first time.
1591
+ */
1143
1592
  isLoadingError: true
1593
+ /**
1594
+ * `false`, since the query didn't fail while refetching.
1595
+ */
1144
1596
  isRefetchError: false
1597
+ /**
1598
+ * `false`, since fetching the next page didn't fail.
1599
+ */
1145
1600
  isFetchNextPageError: false
1601
+ /**
1602
+ * `false`, since fetching the previous page didn't fail.
1603
+ */
1146
1604
  isFetchPreviousPageError: false
1605
+ /**
1606
+ * `false`, since the query isn't in the `success` state.
1607
+ */
1147
1608
  isSuccess: false
1609
+ /**
1610
+ * `false`, since the data shown isn't the `placeholderData`.
1611
+ */
1148
1612
  isPlaceholderData: false
1613
+ /**
1614
+ * `'error'`, since the query attempt resulted in an error.
1615
+ */
1149
1616
  status: 'error'
1150
1617
  }
1151
1618
 
1619
+ /**
1620
+ * An infinite query result in the `error` state when a refetch failed, so the data from before is
1621
+ * kept.
1622
+ */
1152
1623
  export interface InfiniteQueryObserverRefetchErrorResult<
1153
1624
  TData = unknown,
1154
1625
  TError = DefaultError,
1155
1626
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1627
+ /**
1628
+ * The data from before the failed refetch, which is kept.
1629
+ */
1156
1630
  data: TData
1631
+ /**
1632
+ * The error the refetch failed with.
1633
+ */
1157
1634
  error: TError
1635
+ /**
1636
+ * `true`, since the query is in the `error` state.
1637
+ */
1158
1638
  isError: true
1639
+ /**
1640
+ * `false`, since the query has data or a query attempt has finished.
1641
+ */
1159
1642
  isPending: false
1643
+ /**
1644
+ * `false`, since the first fetch isn't in flight.
1645
+ */
1160
1646
  isLoading: false
1647
+ /**
1648
+ * `false`, since the query didn't fail while fetching for the first time.
1649
+ */
1161
1650
  isLoadingError: false
1651
+ /**
1652
+ * `true`, since the query failed while refetching.
1653
+ */
1162
1654
  isRefetchError: true
1655
+ /**
1656
+ * `false`, since the query isn't in the `success` state.
1657
+ */
1163
1658
  isSuccess: false
1659
+ /**
1660
+ * `false`, since the data shown isn't the `placeholderData`.
1661
+ */
1164
1662
  isPlaceholderData: false
1663
+ /**
1664
+ * `'error'`, since the query attempt resulted in an error.
1665
+ */
1165
1666
  status: 'error'
1166
1667
  }
1167
1668
 
1669
+ /**
1670
+ * An infinite query result in the `success` state with data from the cache.
1671
+ */
1168
1672
  export interface InfiniteQueryObserverSuccessResult<
1169
1673
  TData = unknown,
1170
1674
  TError = DefaultError,
1171
1675
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1676
+ /**
1677
+ * The last successfully resolved data for the query.
1678
+ */
1172
1679
  data: TData
1680
+ /**
1681
+ * `null`, since the query isn't in the `error` state.
1682
+ */
1173
1683
  error: null
1684
+ /**
1685
+ * `false`, since the query isn't in the `error` state.
1686
+ */
1174
1687
  isError: false
1688
+ /**
1689
+ * `false`, since the query has data or a query attempt has finished.
1690
+ */
1175
1691
  isPending: false
1692
+ /**
1693
+ * `false`, since the first fetch isn't in flight.
1694
+ */
1176
1695
  isLoading: false
1696
+ /**
1697
+ * `false`, since the query didn't fail while fetching for the first time.
1698
+ */
1177
1699
  isLoadingError: false
1700
+ /**
1701
+ * `false`, since the query didn't fail while refetching.
1702
+ */
1178
1703
  isRefetchError: false
1704
+ /**
1705
+ * `false`, since fetching the next page didn't fail.
1706
+ */
1179
1707
  isFetchNextPageError: false
1708
+ /**
1709
+ * `false`, since fetching the previous page didn't fail.
1710
+ */
1180
1711
  isFetchPreviousPageError: false
1712
+ /**
1713
+ * `true`, since the query is in the `success` state.
1714
+ */
1181
1715
  isSuccess: true
1716
+ /**
1717
+ * `false`, since the data shown isn't the `placeholderData`.
1718
+ */
1182
1719
  isPlaceholderData: false
1720
+ /**
1721
+ * `'success'`, since the query has received a response with no errors and is ready to display its
1722
+ * data.
1723
+ */
1183
1724
  status: 'success'
1184
1725
  }
1185
1726
 
1727
+ /**
1728
+ * An infinite query result in the `success` state that shows `placeholderData` while the query has
1729
+ * no data yet.
1730
+ */
1186
1731
  export interface InfiniteQueryObserverPlaceholderResult<
1187
1732
  TData = unknown,
1188
1733
  TError = DefaultError,
1189
1734
  > extends InfiniteQueryObserverBaseResult<TData, TError> {
1735
+ /**
1736
+ * The `placeholderData` shown while the query has no data yet.
1737
+ */
1190
1738
  data: TData
1739
+ /**
1740
+ * `false`, since the query isn't in the `error` state.
1741
+ */
1191
1742
  isError: false
1743
+ /**
1744
+ * `null`, since the query isn't in the `error` state.
1745
+ */
1192
1746
  error: null
1747
+ /**
1748
+ * `false`, since the query has data or a query attempt has finished.
1749
+ */
1193
1750
  isPending: false
1751
+ /**
1752
+ * `false`, since the first fetch isn't in flight.
1753
+ */
1194
1754
  isLoading: false
1755
+ /**
1756
+ * `false`, since the query didn't fail while fetching for the first time.
1757
+ */
1195
1758
  isLoadingError: false
1759
+ /**
1760
+ * `false`, since the query didn't fail while refetching.
1761
+ */
1196
1762
  isRefetchError: false
1763
+ /**
1764
+ * `true`, since the query is in the `success` state.
1765
+ */
1197
1766
  isSuccess: true
1767
+ /**
1768
+ * `true`, since the data shown is the `placeholderData`.
1769
+ */
1198
1770
  isPlaceholderData: true
1771
+ /**
1772
+ * `false`, since fetching the next page didn't fail.
1773
+ */
1199
1774
  isFetchNextPageError: false
1775
+ /**
1776
+ * `false`, since fetching the previous page didn't fail.
1777
+ */
1200
1778
  isFetchPreviousPageError: false
1779
+ /**
1780
+ * `'success'`, since the query has received a response with no errors and is ready to display its
1781
+ * data.
1782
+ */
1201
1783
  status: 'success'
1202
1784
  }
1203
1785
 
1786
+ /**
1787
+ * An infinite query result that always has `data`: the success and refetch error states.
1788
+ */
1204
1789
  export type DefinedInfiniteQueryObserverResult<
1205
1790
  TData = unknown,
1206
1791
  TError = DefaultError,
@@ -1208,6 +1793,10 @@ export type DefinedInfiniteQueryObserverResult<
1208
1793
  | InfiniteQueryObserverRefetchErrorResult<TData, TError>
1209
1794
  | InfiniteQueryObserverSuccessResult<TData, TError>
1210
1795
 
1796
+ /**
1797
+ * The result of an `InfiniteQueryObserver`, and of the hooks built on it like `useInfiniteQuery`.
1798
+ * Narrow it by `status` or the `is*` flags to get the type of each state.
1799
+ */
1211
1800
  export type InfiniteQueryObserverResult<
1212
1801
  TData = unknown,
1213
1802
  TError = DefaultError,
@@ -1241,6 +1830,9 @@ export type MutationStatus = 'idle' | 'pending' | 'success' | 'error'
1241
1830
  * state and resume automatically when their turn comes. Mutations with no scope always run in parallel.
1242
1831
  */
1243
1832
  export type MutationScope = {
1833
+ /**
1834
+ * The scope's identifier. Mutations with the same `id` run one after another.
1835
+ */
1244
1836
  id: string
1245
1837
  }
1246
1838
 
@@ -1256,9 +1848,22 @@ export type MutationMeta = Register extends {
1256
1848
  : Record<string, unknown>
1257
1849
  : Record<string, unknown>
1258
1850
 
1851
+ /**
1852
+ * The object passed to `mutationFn` and the mutation callbacks: the `QueryClient`, the mutation's
1853
+ * `meta`, and its `mutationKey`.
1854
+ */
1259
1855
  export type MutationFunctionContext = {
1856
+ /**
1857
+ * The `QueryClient` the mutation runs in.
1858
+ */
1260
1859
  client: QueryClient
1860
+ /**
1861
+ * The `meta` of the mutation options.
1862
+ */
1261
1863
  meta: MutationMeta | undefined
1864
+ /**
1865
+ * The `mutationKey` of the mutation options, if set.
1866
+ */
1262
1867
  mutationKey?: MutationKey
1263
1868
  }
1264
1869
 
@@ -1268,6 +1873,10 @@ export type MutationFunction<TData = unknown, TVariables = unknown> = (
1268
1873
  context: MutationFunctionContext,
1269
1874
  ) => Promise<TData>
1270
1875
 
1876
+ /**
1877
+ * The options of a mutation: its `mutationFn`, `mutationKey`, callbacks, retries, `scope`, and so
1878
+ * on.
1879
+ */
1271
1880
  export interface MutationOptions<
1272
1881
  TData = unknown,
1273
1882
  TError = DefaultError,
@@ -1337,7 +1946,6 @@ export interface MutationOptions<
1337
1946
  * If `true`, failed mutations will retry infinitely.
1338
1947
  * If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number.
1339
1948
  * If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false.
1340
- *
1341
1949
  * @defaultValue 0
1342
1950
  */
1343
1951
  retry?: RetryValue<TError>
@@ -1350,7 +1958,6 @@ export interface MutationOptions<
1350
1958
  retryDelay?: RetryDelayValue<TError>
1351
1959
  /**
1352
1960
  * Controls whether a mutation is allowed to run based on the current network connectivity.
1353
- *
1354
1961
  * @defaultValue 'online'
1355
1962
  * @see [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
1356
1963
  */
@@ -1378,6 +1985,10 @@ export interface MutationOptions<
1378
1985
  scope?: MutationScope
1379
1986
  }
1380
1987
 
1988
+ /**
1989
+ * The options of a `MutationObserver`, and of the hooks built on it like `useMutation`: the
1990
+ * {@link MutationOptions}, plus `throwOnError`.
1991
+ */
1381
1992
  export interface MutationObserverOptions<
1382
1993
  TData = unknown,
1383
1994
  TError = DefaultError,
@@ -1389,30 +2000,43 @@ export interface MutationObserverOptions<
1389
2000
  * If set to `true`, all errors will be thrown to the nearest error boundary.
1390
2001
  * If set to a function, it will be passed the error and should return a boolean indicating whether to throw the
1391
2002
  * error (`true`) or return it as state (`false`).
1392
- *
1393
2003
  * @defaultValue false
1394
2004
  */
1395
2005
  throwOnError?: boolean | ((error: TError) => boolean)
1396
2006
  }
1397
2007
 
2008
+ /**
2009
+ * The callbacks that can be passed to `mutate` for a single call. They run after the callbacks of
2010
+ * the mutation options.
2011
+ */
1398
2012
  export interface MutateOptions<
1399
2013
  TData = unknown,
1400
2014
  TError = DefaultError,
1401
2015
  TVariables = void,
1402
2016
  TOnMutateResult = unknown,
1403
2017
  > {
2018
+ /**
2019
+ * Called when the mutation of this call succeeds, after the `onSuccess` of the mutation options.
2020
+ */
1404
2021
  onSuccess?: (
1405
2022
  data: TData,
1406
2023
  variables: TVariables,
1407
2024
  onMutateResult: TOnMutateResult | undefined,
1408
2025
  context: MutationFunctionContext,
1409
2026
  ) => void
2027
+ /**
2028
+ * Called when the mutation of this call fails, after the `onError` of the mutation options.
2029
+ */
1410
2030
  onError?: (
1411
2031
  error: TError,
1412
2032
  variables: TVariables,
1413
2033
  onMutateResult: TOnMutateResult | undefined,
1414
2034
  context: MutationFunctionContext,
1415
2035
  ) => void
2036
+ /**
2037
+ * Called when the mutation of this call succeeds or fails, after the `onSettled` of the mutation
2038
+ * options.
2039
+ */
1416
2040
  onSettled?: (
1417
2041
  data: TData | undefined,
1418
2042
  error: TError | null,
@@ -1422,6 +2046,10 @@ export interface MutateOptions<
1422
2046
  ) => void
1423
2047
  }
1424
2048
 
2049
+ /**
2050
+ * The parameters of {@link MutateFunction}: `variables`, optional when `TVariables` accepts
2051
+ * `undefined`, and the {@link MutateOptions} for that call.
2052
+ */
1425
2053
  export type MutateFunctionRest<
1426
2054
  TData = unknown,
1427
2055
  TError = DefaultError,
@@ -1437,6 +2065,10 @@ export type MutateFunctionRest<
1437
2065
  options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
1438
2066
  ]
1439
2067
 
2068
+ /**
2069
+ * The `mutate` function of a `MutationObserver`: runs the mutation with the given variables and
2070
+ * resolves with its data.
2071
+ */
1440
2072
  export type MutateFunction<
1441
2073
  TData = unknown,
1442
2074
  TError = DefaultError,
@@ -1446,6 +2078,10 @@ export type MutateFunction<
1446
2078
  ...rest: MutateFunctionRest<TData, TError, TVariables, TOnMutateResult>
1447
2079
  ) => Promise<TData>
1448
2080
 
2081
+ /**
2082
+ * The properties shared by every state of a mutation result, like `data`, `error`, `variables`,
2083
+ * `status`, the `is*` flags, `mutate`, and `reset`.
2084
+ */
1449
2085
  export interface MutationObserverBaseResult<
1450
2086
  TData = unknown,
1451
2087
  TError = DefaultError,
@@ -1511,6 +2147,9 @@ export interface MutationObserverBaseResult<
1511
2147
  reset: () => void
1512
2148
  }
1513
2149
 
2150
+ /**
2151
+ * A mutation result in the `idle` state: the mutation hasn't run yet, or was reset.
2152
+ */
1514
2153
  export interface MutationObserverIdleResult<
1515
2154
  TData = unknown,
1516
2155
  TError = DefaultError,
@@ -1522,16 +2161,43 @@ export interface MutationObserverIdleResult<
1522
2161
  TVariables,
1523
2162
  TOnMutateResult
1524
2163
  > {
2164
+ /**
2165
+ * `undefined`, since the mutation hasn't run.
2166
+ */
1525
2167
  data: undefined
2168
+ /**
2169
+ * `undefined`, since the mutation hasn't run.
2170
+ */
1526
2171
  variables: undefined
2172
+ /**
2173
+ * `null`, since the mutation hasn't failed.
2174
+ */
1527
2175
  error: null
2176
+ /**
2177
+ * `false`, since the mutation hasn't failed.
2178
+ */
1528
2179
  isError: false
2180
+ /**
2181
+ * `true`, since the mutation hasn't run yet or was reset.
2182
+ */
1529
2183
  isIdle: true
2184
+ /**
2185
+ * `false`, since the mutation isn't running.
2186
+ */
1530
2187
  isPending: false
2188
+ /**
2189
+ * `false`, since the mutation hasn't succeeded.
2190
+ */
1531
2191
  isSuccess: false
2192
+ /**
2193
+ * `'idle'`, since the mutation hasn't run yet or was reset.
2194
+ */
1532
2195
  status: 'idle'
1533
2196
  }
1534
2197
 
2198
+ /**
2199
+ * A mutation result in the `pending` state while the mutation runs.
2200
+ */
1535
2201
  export interface MutationObserverLoadingResult<
1536
2202
  TData = unknown,
1537
2203
  TError = DefaultError,
@@ -1543,16 +2209,43 @@ export interface MutationObserverLoadingResult<
1543
2209
  TVariables,
1544
2210
  TOnMutateResult
1545
2211
  > {
2212
+ /**
2213
+ * `undefined`, since the mutation hasn't succeeded.
2214
+ */
1546
2215
  data: undefined
2216
+ /**
2217
+ * The variables passed to `mutate` for this mutation.
2218
+ */
1547
2219
  variables: TVariables
2220
+ /**
2221
+ * `null`, since the mutation hasn't failed.
2222
+ */
1548
2223
  error: null
2224
+ /**
2225
+ * `false`, since the mutation hasn't failed.
2226
+ */
1549
2227
  isError: false
2228
+ /**
2229
+ * `false`, since the mutation has run.
2230
+ */
1550
2231
  isIdle: false
2232
+ /**
2233
+ * `true`, since the mutation is running.
2234
+ */
1551
2235
  isPending: true
2236
+ /**
2237
+ * `false`, since the mutation hasn't succeeded.
2238
+ */
1552
2239
  isSuccess: false
2240
+ /**
2241
+ * `'pending'`, since the mutation is running.
2242
+ */
1553
2243
  status: 'pending'
1554
2244
  }
1555
2245
 
2246
+ /**
2247
+ * A mutation result in the `error` state after the mutation failed.
2248
+ */
1556
2249
  export interface MutationObserverErrorResult<
1557
2250
  TData = unknown,
1558
2251
  TError = DefaultError,
@@ -1564,16 +2257,43 @@ export interface MutationObserverErrorResult<
1564
2257
  TVariables,
1565
2258
  TOnMutateResult
1566
2259
  > {
2260
+ /**
2261
+ * `undefined`, since the mutation hasn't succeeded.
2262
+ */
1567
2263
  data: undefined
2264
+ /**
2265
+ * The error the mutation failed with.
2266
+ */
1568
2267
  error: TError
2268
+ /**
2269
+ * The variables passed to `mutate` for this mutation.
2270
+ */
1569
2271
  variables: TVariables
2272
+ /**
2273
+ * `true`, since the mutation failed.
2274
+ */
1570
2275
  isError: true
2276
+ /**
2277
+ * `false`, since the mutation has run.
2278
+ */
1571
2279
  isIdle: false
2280
+ /**
2281
+ * `false`, since the mutation isn't running.
2282
+ */
1572
2283
  isPending: false
2284
+ /**
2285
+ * `false`, since the mutation hasn't succeeded.
2286
+ */
1573
2287
  isSuccess: false
2288
+ /**
2289
+ * `'error'`, since the mutation failed.
2290
+ */
1574
2291
  status: 'error'
1575
2292
  }
1576
2293
 
2294
+ /**
2295
+ * A mutation result in the `success` state after the mutation succeeded.
2296
+ */
1577
2297
  export interface MutationObserverSuccessResult<
1578
2298
  TData = unknown,
1579
2299
  TError = DefaultError,
@@ -1585,16 +2305,44 @@ export interface MutationObserverSuccessResult<
1585
2305
  TVariables,
1586
2306
  TOnMutateResult
1587
2307
  > {
2308
+ /**
2309
+ * The data the mutation resolved with.
2310
+ */
1588
2311
  data: TData
2312
+ /**
2313
+ * `null`, since the mutation hasn't failed.
2314
+ */
1589
2315
  error: null
2316
+ /**
2317
+ * The variables passed to `mutate` for this mutation.
2318
+ */
1590
2319
  variables: TVariables
2320
+ /**
2321
+ * `false`, since the mutation hasn't failed.
2322
+ */
1591
2323
  isError: false
2324
+ /**
2325
+ * `false`, since the mutation has run.
2326
+ */
1592
2327
  isIdle: false
2328
+ /**
2329
+ * `false`, since the mutation isn't running.
2330
+ */
1593
2331
  isPending: false
2332
+ /**
2333
+ * `true`, since the mutation succeeded.
2334
+ */
1594
2335
  isSuccess: true
2336
+ /**
2337
+ * `'success'`, since the mutation succeeded.
2338
+ */
1595
2339
  status: 'success'
1596
2340
  }
1597
2341
 
2342
+ /**
2343
+ * The result of a `MutationObserver`, and of the hooks built on it like `useMutation`. Narrow it by
2344
+ * `status` or the `is*` flags to get the type of each state.
2345
+ */
1598
2346
  export type MutationObserverResult<
1599
2347
  TData = unknown,
1600
2348
  TError = DefaultError,
@@ -1606,6 +2354,10 @@ export type MutationObserverResult<
1606
2354
  | MutationObserverErrorResult<TData, TError, TVariables, TOnMutateResult>
1607
2355
  | MutationObserverSuccessResult<TData, TError, TVariables, TOnMutateResult>
1608
2356
 
2357
+ /**
2358
+ * The options of `new QueryClient()`: the `queryCache` and `mutationCache` to use, and the
2359
+ * `defaultOptions` for its queries and mutations.
2360
+ */
1609
2361
  export interface QueryClientConfig {
1610
2362
  /** The query cache this client is connected to. A new `QueryCache` is created if not provided. */
1611
2363
  queryCache?: QueryCache
@@ -1618,6 +2370,10 @@ export interface QueryClientConfig {
1618
2370
  defaultOptions?: DefaultOptions
1619
2371
  }
1620
2372
 
2373
+ /**
2374
+ * The default options of a `QueryClient`, applied to every query (`queries`), mutation
2375
+ * (`mutations`), `hydrate`, and `dehydrate` call unless overridden.
2376
+ */
1621
2377
  export interface DefaultOptions<TError = DefaultError> {
1622
2378
  /** Default options applied to every query, unless overridden per-query. */
1623
2379
  queries?: OmitKeyof<
@@ -1626,7 +2382,7 @@ export interface DefaultOptions<TError = DefaultError> {
1626
2382
  >
1627
2383
  /** Default options applied to every mutation, unless overridden per-mutation. */
1628
2384
  mutations?: MutationObserverOptions<unknown, TError, unknown, unknown>
1629
- /** Default options used when hydrating queries; see {@link HydrateOptions}. */
2385
+ /** Default options used when hydrating queries and mutations; see {@link HydrateOptions}. */
1630
2386
  hydrate?: HydrateOptions['defaultOptions']
1631
2387
  /** Default options used when dehydrating the client's caches; see {@link DehydrateOptions}. */
1632
2388
  dehydrate?: DehydrateOptions
@@ -1637,7 +2393,15 @@ export interface DefaultOptions<TError = DefaultError> {
1637
2393
  * They are carried on the {@link CancelledError} that the cancelled fetch rejects with.
1638
2394
  */
1639
2395
  export interface CancelOptions {
2396
+ /**
2397
+ * If `true`, the query goes back to the state it had before the fetch started, instead of getting
2398
+ * the cancellation error.
2399
+ */
1640
2400
  revert?: boolean
2401
+ /**
2402
+ * If `true`, the cancellation error isn't surfaced, e.g. because another fetch replaces the
2403
+ * cancelled one.
2404
+ */
1641
2405
  silent?: boolean
1642
2406
  }
1643
2407
 
@@ -1647,6 +2411,10 @@ export interface CancelOptions {
1647
2411
  * omit it to use the current time.
1648
2412
  */
1649
2413
  export interface SetDataOptions {
2414
+ /**
2415
+ * The timestamp to record the data with, instead of the current time. Staleness is measured from
2416
+ * it.
2417
+ */
1650
2418
  updatedAt?: number
1651
2419
  }
1652
2420
 
@@ -1660,6 +2428,12 @@ export type NotifyEventType =
1660
2428
  | 'observerResultsUpdated'
1661
2429
  | 'observerOptionsUpdated'
1662
2430
 
2431
+ /**
2432
+ * The base shape of the events that the query and mutation caches send to their listeners.
2433
+ */
1663
2434
  export interface NotifyEvent {
2435
+ /**
2436
+ * The kind of event, e.g. `'added'`, `'removed'`, or `'updated'`.
2437
+ */
1664
2438
  type: NotifyEventType
1665
2439
  }