@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
package/src/query.ts CHANGED
@@ -112,42 +112,97 @@ export interface QueryState<TData = unknown, TError = DefaultError> {
112
112
  fetchStatus: FetchStatus
113
113
  }
114
114
 
115
+ /**
116
+ * The context passed to a {@link QueryBehavior}'s `onFetch`, which can replace `fetchFn` to change
117
+ * how the query fetches (e.g. to fetch pages for an infinite query).
118
+ */
115
119
  export interface FetchContext<
116
120
  TQueryFnData,
117
121
  TError,
118
122
  TData,
119
123
  TQueryKey extends QueryKey = QueryKey,
120
124
  > {
125
+ /**
126
+ * The function that runs the fetch. By default it calls `queryFn`; `onFetch` can replace it.
127
+ */
121
128
  fetchFn: () => unknown | Promise<unknown>
129
+ /**
130
+ * The options of this fetch.
131
+ */
122
132
  fetchOptions?: FetchOptions
133
+ /**
134
+ * The `AbortSignal` that aborts when the fetch is cancelled.
135
+ */
123
136
  signal: AbortSignal
137
+ /**
138
+ * The options of the query.
139
+ */
124
140
  options: QueryOptions<TQueryFnData, TError, TData, any>
141
+ /**
142
+ * The `QueryClient` the query belongs to.
143
+ */
125
144
  client: QueryClient
145
+ /**
146
+ * The key of the query.
147
+ */
126
148
  queryKey: TQueryKey
149
+ /**
150
+ * The state of the query when the fetch starts.
151
+ */
127
152
  state: QueryState<TData, TError>
128
153
  }
129
154
 
155
+ /**
156
+ * Customizes how a query fetches, e.g. the behavior that fetches the pages of an infinite query.
157
+ */
130
158
  export interface QueryBehavior<
131
159
  TQueryFnData = unknown,
132
160
  TError = DefaultError,
133
161
  TData = TQueryFnData,
134
162
  TQueryKey extends QueryKey = QueryKey,
135
163
  > {
164
+ /**
165
+ * Called before each fetch of the query, e.g. to replace `fetchFn` in the context.
166
+ */
136
167
  onFetch: (
137
168
  context: FetchContext<TQueryFnData, TError, TData, TQueryKey>,
138
169
  query: Query,
139
170
  ) => void
140
171
  }
141
172
 
173
+ /**
174
+ * The direction an infinite query fetches in: `'forward'` for the next page, `'backward'` for the
175
+ * previous one.
176
+ */
142
177
  export type FetchDirection = 'forward' | 'backward'
143
178
 
179
+ /**
180
+ * Metadata for a fetch, e.g. the direction when an infinite query fetches more pages.
181
+ */
144
182
  export interface FetchMeta {
183
+ /**
184
+ * Set when an infinite query fetches another page, with the direction to fetch in.
185
+ */
145
186
  fetchMore?: { direction: FetchDirection }
146
187
  }
147
188
 
189
+ /**
190
+ * Options for a single fetch of a query.
191
+ */
148
192
  export interface FetchOptions<TData = unknown> {
193
+ /**
194
+ * If `true`, an in-flight fetch is cancelled before starting a new one, when the query already
195
+ * has data. Otherwise, the in-flight fetch is reused.
196
+ */
149
197
  cancelRefetch?: boolean
198
+ /**
199
+ * Metadata of the fetch, stored in the query's `fetchMeta` state.
200
+ */
150
201
  meta?: FetchMeta
202
+ /**
203
+ * A promise to use for the first attempt instead of calling `fetchFn`, e.g. a pending promise
204
+ * restored by `hydrate`.
205
+ */
151
206
  initialPromise?: Promise<TData>
152
207
  }
153
208
 
@@ -191,6 +246,10 @@ interface SetStateAction<TData, TError> {
191
246
  state: Partial<QueryState<TData, TError>>
192
247
  }
193
248
 
249
+ /**
250
+ * The actions a query dispatches to update its state, e.g. when it starts fetching, fails, or
251
+ * succeeds.
252
+ */
194
253
  export type Action<TData, TError> =
195
254
  | ContinueAction
196
255
  | ErrorAction<TError>
@@ -211,7 +270,6 @@ export type Action<TData, TError> =
211
270
  * code typically interacts with queries indirectly through `QueryClient` or
212
271
  * a framework hook like `useQuery`. Direct access to a `Query` instance is
213
272
  * possible via `queryCache.find()`/`findAll()` for inspecting cache state.
214
- *
215
273
  * @example
216
274
  * ```ts
217
275
  * const queryCache = queryClient.getQueryCache()
@@ -260,12 +318,17 @@ export class Query<
260
318
  }
261
319
  /**
262
320
  * The `meta` object passed in the query's options, if any.
321
+ * @returns The query's `meta`, or `undefined` if none was set.
263
322
  */
264
323
  get meta(): QueryMeta | undefined {
265
324
  return this.options.meta
266
325
  }
267
326
 
268
- /** @internal */
327
+ /**
328
+ * `'infinite'` for an infinite query, otherwise `undefined`.
329
+ * @internal
330
+ * @returns The type of the query, set from the `_type` option (e.g. `'infinite'`).
331
+ */
269
332
  get queryType() {
270
333
  return this.#queryType
271
334
  }
@@ -273,12 +336,18 @@ export class Query<
273
336
  /**
274
337
  * The promise for the currently in-flight fetch, if the query is fetching.
275
338
  * `undefined` when the query is not fetching.
339
+ * @returns The promise of the in-flight fetch, or `undefined`.
276
340
  */
277
341
  get promise(): Promise<TData> | undefined {
278
342
  return this.#retryer?.promise
279
343
  }
280
344
 
281
- /** @internal */
345
+ /**
346
+ * Replaces the query's options and applies their `gcTime`. If the query has no data yet, it gets
347
+ * the `initialData` from the new options, if any.
348
+ * @internal
349
+ * @param options - The new query options, merged on top of the query's default options.
350
+ */
282
351
  setOptions(
283
352
  options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
284
353
  ): void {
@@ -290,7 +359,7 @@ export class Query<
290
359
 
291
360
  this.updateGcTime(this.options.gcTime)
292
361
 
293
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
362
+ // oxlint-disable-next-line typescript/no-unnecessary-condition
294
363
  if (this.state && this.state.data === undefined) {
295
364
  const defaultState = getDefaultState(this.options)
296
365
  if (defaultState.data !== undefined) {
@@ -302,13 +371,20 @@ export class Query<
302
371
  }
303
372
  }
304
373
 
305
- protected optionalRemove() {
374
+ protected override optionalRemove() {
306
375
  if (!this.observers.length && this.state.fetchStatus === 'idle') {
307
376
  this.#cache.remove(this)
308
377
  }
309
378
  }
310
379
 
311
- /** @internal */
380
+ /**
381
+ * Writes new data to the query and marks it as successfully fetched.
382
+ * @internal
383
+ * @param newData - The data to write. Structural sharing with the current data is applied.
384
+ * @param options - Set `updatedAt` to override the timestamp, and `manual` to mark the write as
385
+ * manual (e.g. from `queryClient.setQueryData`).
386
+ * @returns The data that was written.
387
+ */
312
388
  setData(
313
389
  newData: TData,
314
390
  options?: SetDataOptions & { manual: boolean },
@@ -330,6 +406,7 @@ export class Query<
330
406
  * Merges the given partial state directly into this query's state, notifying observers. Used
331
407
  * by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
332
408
  * user manually trigger a loading/error state or edit the cached data.
409
+ * @param state - The partial state to merge into the query's state.
333
410
  */
334
411
  setState(state: Partial<QueryState<TData, TError>>): void {
335
412
  this.#dispatch({ type: 'setState', state })
@@ -339,7 +416,9 @@ export class Query<
339
416
  * Cancels the query's currently in-flight fetch, if any.
340
417
  * - Returns a promise that resolves once the cancellation has settled.
341
418
  * - If no fetch is in progress, resolves immediately.
342
- *
419
+ * @param options - Set `revert` to restore the state from before the fetch started, and `silent`
420
+ * to suppress the cancellation error when a new fetch replaces the cancelled one.
421
+ * @returns A promise that resolves once the cancellation has settled.
343
422
  * @example
344
423
  * ```ts
345
424
  * await query.cancel()
@@ -355,16 +434,19 @@ export class Query<
355
434
  * Clears the query's garbage collection timeout and silently cancels any
356
435
  * in-flight fetch. Called by `QueryCache` when the query is removed from
357
436
  * the cache.
358
- *
359
437
  * @see {@link Query#cancel}
360
438
  */
361
- destroy(): void {
439
+ override destroy(): void {
362
440
  super.destroy()
363
441
 
364
442
  this.cancel({ silent: true })
365
443
  }
366
444
 
367
- /** @internal */
445
+ /**
446
+ * The state the query was created with.
447
+ * @internal
448
+ * @returns The state the query had when it was first created, used by {@link Query#reset}.
449
+ */
368
450
  get resetState(): QueryState<TData, TError> {
369
451
  return this.#initialState
370
452
  }
@@ -382,6 +464,7 @@ export class Query<
382
464
  /**
383
465
  * Returns `true` if the query has at least one observer for which `enabled`
384
466
  * does not resolve to `false`.
467
+ * @returns `true` if the query has an enabled observer.
385
468
  */
386
469
  isActive(): boolean {
387
470
  return this.observers.some(
@@ -396,6 +479,7 @@ export class Query<
396
479
  * (see `isActive`).
397
480
  * - If the query has no observers, it is disabled when its `queryFn` is
398
481
  * `skipToken` or it has never been fetched.
482
+ * @returns `true` if the query is disabled.
399
483
  */
400
484
  isDisabled(): boolean {
401
485
  if (this.getObserversCount() > 0) {
@@ -408,6 +492,7 @@ export class Query<
408
492
  /**
409
493
  * Returns `true` if the query has been fetched, i.e. it has resolved with
410
494
  * either data or an error at least once.
495
+ * @returns `true` if the query has been fetched.
411
496
  */
412
497
  isFetched() {
413
498
  return this.state.dataUpdateCount + this.state.errorUpdateCount > 0
@@ -416,6 +501,7 @@ export class Query<
416
501
  /**
417
502
  * Returns `true` if the query has at least one observer configured with
418
503
  * `staleTime: 'static'`, meaning it is treated as never stale.
504
+ * @returns `true` if the query is static.
419
505
  */
420
506
  isStatic(): boolean {
421
507
  if (this.getObserversCount() > 0) {
@@ -435,7 +521,7 @@ export class Query<
435
521
  * `staleTime` and `enabled` state).
436
522
  * - If the query has no observers, it is considered stale when it has no
437
523
  * data or has been invalidated.
438
- *
524
+ * @returns `true` if the query is stale.
439
525
  * @see {@link Query#isStaleByTime}
440
526
  * @example
441
527
  * ```ts
@@ -463,7 +549,9 @@ export class Query<
463
549
  * - `staleTime: 'static'` is never stale.
464
550
  * - An invalidated query is always stale.
465
551
  * - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
466
- *
552
+ * @param staleTime - The time, in milliseconds, after which data is considered stale, or
553
+ * `'static'` to never treat existing data as stale. A query without data is stale either way.
554
+ * @returns `true` if the query's data is stale.
467
555
  * @see {@link Query#isStale}
468
556
  * @example
469
557
  * ```ts
@@ -487,7 +575,11 @@ export class Query<
487
575
  return !timeUntilStale(this.state.dataUpdatedAt, staleTime)
488
576
  }
489
577
 
490
- /** @internal */
578
+ /**
579
+ * Refetches the query when the window regains focus, if an observer wants that, and continues a
580
+ * paused fetch.
581
+ * @internal
582
+ */
491
583
  onFocus(): void {
492
584
  const observer = this.observers.find((x) => x.shouldFetchOnWindowFocus())
493
585
 
@@ -497,7 +589,11 @@ export class Query<
497
589
  this.#retryer?.continue()
498
590
  }
499
591
 
500
- /** @internal */
592
+ /**
593
+ * Refetches the query when the app reconnects, if an observer wants that, and continues a paused
594
+ * fetch.
595
+ * @internal
596
+ */
501
597
  onOnline(): void {
502
598
  const observer = this.observers.find((x) => x.shouldFetchOnReconnect())
503
599
 
@@ -507,7 +603,12 @@ export class Query<
507
603
  this.#retryer?.continue()
508
604
  }
509
605
 
510
- /** @internal */
606
+ /**
607
+ * Subscribes an observer to the query and stops its garbage collection.
608
+ * @internal
609
+ * @param observer - The observer to add. Adding an observer that is already subscribed does
610
+ * nothing.
611
+ */
511
612
  addObserver(observer: QueryObserver<any, any, any, any, any>): void {
512
613
  if (!this.observers.includes(observer)) {
513
614
  this.observers.push(observer)
@@ -519,7 +620,13 @@ export class Query<
519
620
  }
520
621
  }
521
622
 
522
- /** @internal */
623
+ /**
624
+ * Unsubscribes an observer from the query.
625
+ * @internal
626
+ * @param observer - The observer to remove. When the last observer is removed, the in-flight
627
+ * fetch is cancelled if its abort signal was consumed (otherwise only its retries are stopped),
628
+ * and garbage collection is scheduled.
629
+ */
523
630
  removeObserver(observer: QueryObserver<any, any, any, any, any>): void {
524
631
  const index = this.observers.indexOf(observer)
525
632
  if (index !== -1) {
@@ -549,7 +656,7 @@ export class Query<
549
656
 
550
657
  /**
551
658
  * Returns the number of observers currently subscribed to this query.
552
- *
659
+ * @returns The number of observers.
553
660
  * @example
554
661
  * ```ts
555
662
  * if (query.getObserversCount() === 0) {
@@ -565,7 +672,6 @@ export class Query<
565
672
  * Marks the query as invalidated, unless it is already invalidated. This
566
673
  * updates `state.isInvalidated` and notifies observers, but does not by
567
674
  * itself trigger a refetch.
568
- *
569
675
  * @example
570
676
  * ```ts
571
677
  * query.invalidate()
@@ -586,6 +692,13 @@ export class Query<
586
692
  * cancelled first.
587
693
  * - If `options` is passed, it replaces the query's current options
588
694
  * before fetching.
695
+ * @param options - Query options that replace the query's current options before fetching. They
696
+ * are not applied when an in-flight fetch is reused.
697
+ * @param fetchOptions - Set `cancelRefetch` to cancel an in-flight fetch first (only if the query
698
+ * already has data), and `meta` to pass extra information to the query's behavior.
699
+ * @returns A promise that resolves with the fetched data, or rejects with the fetch error. If the
700
+ * fetch is cancelled with `revert` while the query has data, it resolves with the restored data
701
+ * instead.
589
702
  */
590
703
  async fetch(
591
704
  options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
@@ -725,7 +838,8 @@ export class Query<
725
838
  // Try to fetch the data
726
839
  const retryer = (this.#retryer = createRetryer({
727
840
  initialPromise: fetchOptions?.initialPromise as
728
- Promise<TData> | undefined,
841
+ | Promise<TData>
842
+ | undefined,
729
843
  fn: context.fetchFn as () => Promise<TData>,
730
844
  onCancel: (error) => {
731
845
  if (error instanceof CancelledError && error.revert) {
@@ -754,7 +868,6 @@ export class Query<
754
868
  try {
755
869
  const data = await retryer.start()
756
870
  // this is more of a runtime guard
757
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
758
871
  if (data === undefined) {
759
872
  if (process.env.NODE_ENV !== 'production') {
760
873
  console.error(
@@ -903,6 +1016,14 @@ export class Query<
903
1016
  }
904
1017
  }
905
1018
 
1019
+ /**
1020
+ * Returns the state changes applied when a query starts fetching.
1021
+ * @param data - The query's current data. If it is `undefined`, the query is also reset to
1022
+ * `'pending'` with no error.
1023
+ * @param options - The query options, whose `networkMode` decides whether the query is `'fetching'`
1024
+ * or `'paused'`.
1025
+ * @returns The partial query state for a starting fetch.
1026
+ */
906
1027
  export function fetchState<
907
1028
  TQueryFnData,
908
1029
  TError,
@@ -924,6 +1045,12 @@ export function fetchState<
924
1045
  } as const
925
1046
  }
926
1047
 
1048
+ /**
1049
+ * Returns the state changes applied when a query receives data.
1050
+ * @param data - The new data.
1051
+ * @param dataUpdatedAt - The timestamp the data is recorded with. Defaults to the current time.
1052
+ * @returns The partial query state for a successful update.
1053
+ */
927
1054
  function successState<TData>(data: TData | undefined, dataUpdatedAt?: number) {
928
1055
  return {
929
1056
  data,
@@ -934,6 +1061,12 @@ function successState<TData>(data: TData | undefined, dataUpdatedAt?: number) {
934
1061
  }
935
1062
  }
936
1063
 
1064
+ /**
1065
+ * Returns the initial state of a query, based on its `initialData` and `initialDataUpdatedAt`
1066
+ * options.
1067
+ * @param options - The query options.
1068
+ * @returns The initial query state: `'success'` if `initialData` is set, otherwise `'pending'`.
1069
+ */
937
1070
  function getDefaultState<
938
1071
  TQueryFnData,
939
1072
  TError,
package/src/queryCache.ts CHANGED
@@ -93,11 +93,29 @@ export type QueryCacheNotifyEvent =
93
93
 
94
94
  type QueryCacheListener = (event: QueryCacheNotifyEvent) => void
95
95
 
96
+ /**
97
+ * The store a `QueryCache` keeps its queries in, keyed by query hash.
98
+ */
96
99
  export interface QueryStore {
100
+ /**
101
+ * Returns whether a query with the given hash is stored.
102
+ */
97
103
  has: (queryHash: string) => boolean
104
+ /**
105
+ * Stores a query under its hash.
106
+ */
98
107
  set: (queryHash: string, query: Query) => void
108
+ /**
109
+ * Returns the query with the given hash, if any.
110
+ */
99
111
  get: (queryHash: string) => Query | undefined
112
+ /**
113
+ * Removes the query with the given hash.
114
+ */
100
115
  delete: (queryHash: string) => void
116
+ /**
117
+ * Returns an iterator over all stored queries.
118
+ */
101
119
  values: () => IterableIterator<Query>
102
120
  }
103
121
 
@@ -112,7 +130,6 @@ export interface QueryStore {
112
130
  * safe/known updates to the cache, such as queries being added, removed, or updated — updates made
113
131
  * outside of the cache's own tracked mechanisms (e.g. mutating a query's state object directly) do
114
132
  * not notify subscribers.
115
- *
116
133
  * @example
117
134
  * ```ts
118
135
  * const unsubscribe = queryCache.subscribe((event) => {
@@ -133,7 +150,12 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
133
150
  * builds and adds a new one to the cache if none exists yet. Used by framework adapters and
134
151
  * plugins (e.g. broadcast/persistence) that need to get-or-create a `Query` directly, bypassing
135
152
  * the reactive `QueryObserver` machinery.
136
- *
153
+ * @param client - The client the query belongs to, used to default its options.
154
+ * @param options - The query options, including the `queryKey`. A new query is created with the
155
+ * options defaulted by {@link QueryClient#defaultQueryOptions}.
156
+ * @param state - The initial state of a newly created query, e.g. when hydrating. Ignored if the
157
+ * query already exists.
158
+ * @returns The existing or newly created query.
137
159
  * @example
138
160
  * ```ts
139
161
  * const queryCache = queryClient.getQueryCache()
@@ -177,7 +199,12 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
177
199
  return query
178
200
  }
179
201
 
180
- /** @internal */
202
+ /**
203
+ * Adds a query to the cache.
204
+ * @internal
205
+ * @param query - The query to add. If a query with the same hash is already cached, nothing
206
+ * happens.
207
+ */
181
208
  add(query: Query<any, any, any, any>): void {
182
209
  if (!this.#queries.has(query.queryHash)) {
183
210
  this.#queries.set(query.queryHash, query)
@@ -194,7 +221,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
194
221
  * `'removed'` event. A no-op if the query is no longer the one currently stored under its hash
195
222
  * (e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror
196
223
  * removals across `QueryCache` instances.
197
- *
224
+ * @param query - The query to remove.
198
225
  * @example
199
226
  * ```ts
200
227
  * const queryCache = queryClient.getQueryCache()
@@ -217,7 +244,6 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
217
244
 
218
245
  /**
219
246
  * Removes all queries from the cache.
220
- *
221
247
  * @example
222
248
  * ```ts
223
249
  * const queryCache = queryClient.getQueryCache()
@@ -238,7 +264,8 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
238
264
  * exists. Unlike {@link QueryCache#find}, this looks up by the already-computed hash rather
239
265
  * than by `QueryFilters`. Used by plugins (e.g. broadcast/hydration) that already have a hash
240
266
  * to look up directly.
241
- *
267
+ * @param queryHash - The hash of the query to look up.
268
+ * @returns The query stored under the hash, or `undefined`.
242
269
  * @example
243
270
  * ```ts
244
271
  * const queryCache = queryClient.getQueryCache()
@@ -256,12 +283,13 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
256
283
  queryHash: string,
257
284
  ): Query<TQueryFnData, TError, TData, TQueryKey> | undefined {
258
285
  return this.#queries.get(queryHash) as
259
- Query<TQueryFnData, TError, TData, TQueryKey> | undefined
286
+ | Query<TQueryFnData, TError, TData, TQueryKey>
287
+ | undefined
260
288
  }
261
289
 
262
290
  /**
263
291
  * Returns all queries within the cache.
264
- *
292
+ * @returns Every query in the cache.
265
293
  * @example
266
294
  * ```ts
267
295
  * const queryCache = queryClient.getQueryCache()
@@ -282,7 +310,9 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
282
310
  * This is not typically needed for most applications, but can come in handy when needing more
283
311
  * information about a query in rare scenarios (e.g. looking at `query.state.dataUpdatedAt` to
284
312
  * decide whether a query is fresh enough to be used as an initial value).
285
- *
313
+ * @param filters - The filters to match, including the required `queryKey`. `exact` defaults to
314
+ * `true`.
315
+ * @returns The first matching query, or `undefined`.
286
316
  * @see {@link QueryCache#findAll}
287
317
  * @example
288
318
  * ```ts
@@ -307,7 +337,8 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
307
337
  *
308
338
  * This is not typically needed for most applications, but can come in handy when needing more
309
339
  * information about queries in rare scenarios.
310
- *
340
+ * @param filters - The filters to match. Without filters, every query is returned.
341
+ * @returns The matching queries.
311
342
  * @see {@link QueryCache#find}
312
343
  * @example
313
344
  * ```ts
@@ -323,7 +354,11 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
323
354
  : queries
324
355
  }
325
356
 
326
- /** @internal */
357
+ /**
358
+ * Notifies every cache listener of an event, in one batch.
359
+ * @internal
360
+ * @param event - The event passed to every listener.
361
+ */
327
362
  notify(event: QueryCacheNotifyEvent): void {
328
363
  notifyManager.batch(() => {
329
364
  this.listeners.forEach((listener) => {
@@ -332,7 +367,10 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
332
367
  })
333
368
  }
334
369
 
335
- /** @internal */
370
+ /**
371
+ * Calls {@link Query#onFocus} on every cached query, in one batch.
372
+ * @internal
373
+ */
336
374
  onFocus(): void {
337
375
  notifyManager.batch(() => {
338
376
  this.getAll().forEach((query) => {
@@ -341,7 +379,10 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
341
379
  })
342
380
  }
343
381
 
344
- /** @internal */
382
+ /**
383
+ * Calls {@link Query#onOnline} on every cached query, in one batch.
384
+ * @internal
385
+ */
345
386
  onOnline(): void {
346
387
  notifyManager.batch(() => {
347
388
  this.getAll().forEach((query) => {