Merge branch 'upstream/main' into refactor/resolveValueOrFunction

Author: braden-w

.github/renovate.json

@@ -20,7 +20,6 @@
     "@types/node",
     "@types/react",
     "@types/react-dom",
-    "eslint-plugin-react-compiler",
     "node",
     "react",
     "react-dom",

docs/framework/react/guides/important-defaults.md

@@ -9,13 +9,20 @@ Out of the box, TanStack Query is configured with **aggressive but sane** defaul
 
 > To change this behavior, you can configure your queries both globally and per-query using the `staleTime` option. Specifying a longer `staleTime` means queries will not refetch their data as often
 
+- A Query that has a `staleTime` set is considered **fresh** until that `staleTime` has elapsed.
+
+  - set `staleTime` to e.g. `2 * 60 * 1000` to make sure data is read from the cache, without triggering any kinds of refetches, for 2 minutes, or until the Query is [invalidated manually](./query-invalidation.md).
+  - set `staleTime` to `Infinity` to never trigger a refetch until the Query is [invalidated manually](./query-invalidation.md).
+  - set `staleTime` to `'static'` to **never** trigger a refetch, even if the Query is [invalidated manually](./query-invalidation.md).
+
 - Stale queries are refetched automatically in the background when:
   - New instances of the query mount
   - The window is refocused
   - The network is reconnected
-  - The query is optionally configured with a refetch interval
 
-> To change this functionality, you can use options like `refetchOnMount`, `refetchOnWindowFocus`, `refetchOnReconnect` and `refetchInterval`.
+> Setting `staleTime` is the recommended way to avoid excessive refetches, but you can also customize the points in time for refetches by setting options like `refetchOnMount`, `refetchOnWindowFocus` and `refetchOnReconnect`.
+
+- Queries can optionally be configured with a `refetchInterval` to trigger refetches periodically, which is independent of the `staleTime` setting.
 
 - Query results that have no more active instances of `useQuery`, `useInfiniteQuery` or query observers are labeled as "inactive" and remain in the cache in case they are used again at a later time.
 - By default, "inactive" queries are garbage collected after **5 minutes**.

docs/framework/react/reference/useQuery.md

@@ -90,12 +90,13 @@ const {
   - This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
   - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
   - A function like `attempt => attempt * 1000` applies linear backoff.
-- `staleTime: number | ((query: Query) => number)`
+- `staleTime: number | 'static' ((query: Query) => number | 'static')`
   - Optional
   - Defaults to `0`
   - The time in milliseconds after which data is considered stale. This value only applies to the hook it is defined on.
-  - If set to `Infinity`, the data will never be considered stale
+  - If set to `Infinity`, the data will not be considered stale unless manually invalidated
   - If set to a function, the function will be executed with the query to compute a `staleTime`.
+  - If set to `'static'`, the data will never be considered stale
 - `gcTime: number | Infinity`
   - Defaults to `5 * 60 * 1000` (5 minutes) or `Infinity` during SSR
   - The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used.
@@ -116,21 +117,21 @@ const {
   - Defaults to `true`
   - If set to `true`, the query will refetch on mount if the data is stale.
   - If set to `false`, the query will not refetch on mount.
-  - If set to `"always"`, the query will always refetch on mount.
+  - If set to `"always"`, the query will always refetch on mount (except when `staleTime: 'static'` is used).
   - If set to a function, the function will be executed with the query to compute the value
 - `refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")`
   - Optional
   - Defaults to `true`
   - If set to `true`, the query will refetch on window focus if the data is stale.
   - If set to `false`, the query will not refetch on window focus.
-  - If set to `"always"`, the query will always refetch on window focus.
+  - If set to `"always"`, the query will always refetch on window focus (except when `staleTime: 'static'` is used).
   - If set to a function, the function will be executed with the query to compute the value
 - `refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")`
   - Optional
   - Defaults to `true`
   - If set to `true`, the query will refetch on reconnect if the data is stale.
   - If set to `false`, the query will not refetch on reconnect.
-  - If set to `"always"`, the query will always refetch on reconnect.
+  - If set to `"always"`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used).
   - If set to a function, the function will be executed with the query to compute the value
 - `notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)`
   - Optional

docs/reference/QueryClient.md

@@ -321,6 +321,7 @@ The `invalidateQueries` method can be used to invalidate and refetch single or m
 
 - If you **do not want active queries to refetch**, and simply be marked as invalid, you can use the `refetchType: 'none'` option.
 - If you **want inactive queries to refetch** as well, use the `refetchType: 'all'` option
+- For refetching, [queryClient.refetchQueries](#queryclientrefetchqueries) is called.
 
 ```tsx
 await queryClient.invalidateQueries(
@@ -390,6 +391,11 @@ await queryClient.refetchQueries({
 
 This function returns a promise that will resolve when all of the queries are done being refetched. By default, it **will not** throw an error if any of those queries refetches fail, but this can be configured by setting the `throwOnError` option to `true`
 
+**Notes**
+
+- Queries that are "disabled" because they only have disabled Observers will never be refetched.
+- Queries that are "static" because they only have Observers with a Static StaleTime will never be refetched.
+
 ## `queryClient.cancelQueries`
 
 The `cancelQueries` method can be used to cancel outgoing queries based on their query keys or any other functionally accessible property/state of the query.

examples/angular/auto-refetching/package.json

@@ -14,7 +14,7 @@
     "@angular/core": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/basic-persister/package.json

@@ -14,9 +14,9 @@
     "@angular/core": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "@tanstack/angular-query-persist-client": "^5.62.7",
-    "@tanstack/query-sync-storage-persister": "^5.77.2",
+    "@tanstack/query-sync-storage-persister": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/basic/package.json

@@ -14,7 +14,7 @@
     "@angular/core": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/devtools-panel/package.json

@@ -15,8 +15,8 @@
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
     "@angular/router": "^20.0.0",
-    "@tanstack/angular-query-devtools-experimental": "^5.77.2",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-devtools-experimental": "^5.79.0",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/infinite-query-with-max-pages/package.json

@@ -14,7 +14,7 @@
     "@angular/core": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"

examples/angular/optimistic-updates/package.json

@@ -15,7 +15,7 @@
     "@angular/forms": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
     "@angular/platform-browser-dynamic": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.77.2",
+    "@tanstack/angular-query-experimental": "^5.79.0",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"