Merge branch 'main' into fix-some-links

Author: TkDodo

docs/framework/react/guides/mutations.md

@@ -267,7 +267,7 @@ try {
 
 ## Retry
 
-By default TanStack Query will not retry a mutation on error, but it is possible with the `retry` option:
+By default, TanStack Query will not retry a mutation on error, but it is possible with the `retry` option:
 
 [//]: # 'Example9'
 
@@ -390,6 +390,23 @@ We also have an extensive [offline example](../../examples/offline) that covers
 
 [//]: # 'Materials'
 
+## Mutation Scopes
+
+Per default, all mutations run in parallel - even if you invoke `.mutate()` of the same mutation multiple times. Mutations can be given a `scope` with an `id` to avoid that. All mutations with the same `scope.id` will run in serial, which means when they are triggered, they will start in `isPaused: true` state if there is already a mutation for that scope in progress. They will be put into a queue and will automatically resume once their time in the queue has come.
+
+[//]: # 'ExampleScopes'
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  scope: {
+    id: 'todo',
+  },
+})
+```
+
+[//]: # 'ExampleScopes'
+
 ## Further reading
 
 For more information about mutations, have a look at [#12: Mastering Mutations in React Query](../../community/tkdodos-blog#12-mastering-mutations-in-react-query) from

docs/framework/react/reference/useMutation.md

@@ -23,6 +23,7 @@ const {
 } = useMutation({
   mutationFn,
   gcTime,
+  meta,
   mutationKey,
   networkMode,
   onError,
@@ -31,8 +32,8 @@ const {
   onSuccess,
   retry,
   retryDelay,
+  scope,
   throwOnError,
-  meta,
 })
 
 mutate(variables, {
@@ -85,6 +86,10 @@ mutate(variables, {
   - 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.
+- `scope: { id: string }`
+  - Optional
+  - Defaults to a unique id (so that all mutations run in parallel)
+  - Mutations with the same scope id will run in serial
 - `throwOnError: undefined | boolean | (error: TError) => boolean`
   - Defaults to the global query config's `throwOnError` value, which is `undefined`
   - Set this to `true` if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary

examples/angular/basic/package.json

@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.3.3",
     "@angular/platform-browser-dynamic": "^17.3.3",
     "@angular/router": "^17.3.3",
-    "@tanstack/angular-query-experimental": "^5.30.0",
+    "@tanstack/angular-query-experimental": "^5.31.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.4"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.3.3",
     "@angular/cli": "^17.3.3",
     "@angular/compiler-cli": "^17.3.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.30.0",
+    "@tanstack/angular-query-devtools-experimental": "^5.31.0",
     "typescript": "5.2.2"
   }
 }

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

@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.3.3",
     "@angular/platform-browser-dynamic": "^17.3.3",
     "@angular/router": "^17.3.3",
-    "@tanstack/angular-query-experimental": "^5.30.0",
+    "@tanstack/angular-query-experimental": "^5.31.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.4"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.3.3",
     "@angular/cli": "^17.3.3",
     "@angular/compiler-cli": "^17.3.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.30.0",
+    "@tanstack/angular-query-devtools-experimental": "^5.31.0",
     "typescript": "5.2.2"
   }
 }

examples/angular/router/package.json

@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.3.3",
     "@angular/platform-browser-dynamic": "^17.3.3",
     "@angular/router": "^17.3.3",
-    "@tanstack/angular-query-experimental": "^5.30.0",
+    "@tanstack/angular-query-experimental": "^5.31.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.4"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.3.3",
     "@angular/cli": "^17.3.3",
     "@angular/compiler-cli": "^17.3.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.30.0",
+    "@tanstack/angular-query-devtools-experimental": "^5.31.0",
     "typescript": "5.2.2"
   }
 }

examples/angular/simple/package.json

@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.3.3",
     "@angular/platform-browser-dynamic": "^17.3.3",
     "@angular/router": "^17.3.3",
-    "@tanstack/angular-query-experimental": "^5.30.0",
+    "@tanstack/angular-query-experimental": "^5.31.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.4"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.3.3",
     "@angular/cli": "^17.3.3",
     "@angular/compiler-cli": "^17.3.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.30.0",
+    "@tanstack/angular-query-devtools-experimental": "^5.31.0",
     "typescript": "5.2.2"
   }
 }

examples/react/algolia/package.json

@@ -11,8 +11,8 @@
   "dependencies": {
     "@algolia/client-search": "4.22.1",
     "@algolia/transporter": "4.22.1",
-    "@tanstack/react-query": "^5.29.2",
-    "@tanstack/react-query-devtools": "^5.29.2",
+    "@tanstack/react-query": "^5.31.0",
+    "@tanstack/react-query-devtools": "^5.31.0",
     "algoliasearch": "4.22.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

examples/react/auto-refetching/package.json

@@ -7,8 +7,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.29.2",
-    "@tanstack/react-query-devtools": "^5.29.2",
+    "@tanstack/react-query": "^5.31.0",
+    "@tanstack/react-query-devtools": "^5.31.0",
     "axios": "^1.6.7",
     "isomorphic-unfetch": "4.0.2",
     "next": "^14.0.0",

examples/react/basic-graphql-request/package.json

@@ -8,8 +8,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.29.2",
-    "@tanstack/react-query-devtools": "^5.29.2",
+    "@tanstack/react-query": "^5.31.0",
+    "@tanstack/react-query-devtools": "^5.31.0",
     "graphql": "^16.8.1",
     "graphql-request": "^6.1.0",
     "react": "^18.2.0",

examples/react/basic-typescript/package.json

@@ -9,10 +9,10 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@tanstack/query-sync-storage-persister": "^5.29.0",
-    "@tanstack/react-query": "^5.29.2",
-    "@tanstack/react-query-devtools": "^5.29.2",
-    "@tanstack/react-query-persist-client": "^5.29.2",
+    "@tanstack/query-sync-storage-persister": "^5.31.0",
+    "@tanstack/react-query": "^5.31.0",
+    "@tanstack/react-query-devtools": "^5.31.0",
+    "@tanstack/react-query-persist-client": "^5.31.0",
     "axios": "^1.6.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"