feat(queryClient): add setQueriesData utility (TanStack#2204)

* feat(queryClient): add setQueriesData utility

a function which can be used to fuzzily set queryData for multiple queries

* feat(queryClient): add setQueriesData utility

docs

* feat(queryClient): add setQueriesData utility

improve docs

* feat(queryClient): add setQueriesData utility

wrap setQueriesData in notifyManager.batch to avoid unnecessary re-renders

Author: TkDodo

docs/src/pages/reference/QueryClient.md

@@ -29,6 +29,7 @@ Its available methods are:
 - [`prefetchInfiniteQuery`](#queryclientprefetchinfinitequery)
 - [`getQueryData`](#queryclientgetquerydata)
 - [`setQueryData`](#queryclientsetquerydata)
+- [`setQueriesData`](#queryclientsetqueriesdata)
 - [`getQueryState`](#queryclientgetquerystate)
 - [`invalidateQueries`](#queryclientinvalidatequeries)
 - [`refetchQueries`](#queryclientrefetchqueries)
@@ -187,7 +188,7 @@ queryClient.setQueryData(queryKey, updater)
 **Options**
 
 - `queryKey: QueryKey`: [Query Keys](../guides/query-keys)
-- `updater: unknown | (oldData: TData | undefined) => TData`
+- `updater: TData | (oldData: TData | undefined) => TData`
   - If non-function is passed, the data will be updated to this value
   - If a function is passed, it will receive the old data value and be expected to return a new one.
 
@@ -219,6 +220,22 @@ console.log(state.dataUpdatedAt)
 - `queryKey?: QueryKey`: [Query Keys](../guides/query-keys)
 - `filters?: QueryFilters`: [Query Filters](../guides/filters#query-filters)
 
+## `queryClient.setQueriesData`
+
+`setQueriesData` is a synchronous function that can be used to immediately update cached data of multiple queries. Only queries that match the passed queryKey or queryFilter will be updated - no new cache entries will be created. Under the hood, [`setQueryData`](#queryclientsetquerydata) is called for each query.
+
+```js
+queryClient.setQueriesData(queryKey | filters, updater)
+```
+
+**Options**
+
+- `queryKey: QueryKey`: [Query Keys](../guides/query-keys) | `filters: QueryFilters`: [Query Filters](../guides/filters#query-filters)
+  - if a queryKey is passed as first argument, queryKeys fuzzily matching this param will be updated
+  - if a filter is passed, queryKeys matching the filter will be updated
+- `updater: TData | (oldData: TData | undefined) => TData`
+  - the [setQueryData](#queryclientsetquerydata) updater function or new data, will be called for each matching queryKey
+
 ## `queryClient.invalidateQueries`
 
 The `invalidateQueries` method can be used to invalidate and refetch single or multiple queries in the cache based on their query keys or any other functionally accessible property/state of the query. By default, all matching queries are immediately marked as invalid and active queries are refetched in the background.

src/core/queryClient.ts

@@ -123,6 +123,33 @@ export class QueryClient {
       .setData(updater, options)
   }
 
+  setQueriesData<TData>(
+    queryKey: QueryKey,
+    updater: Updater<TData | undefined, TData>,
+    options?: SetDataOptions
+  ): [QueryKey, TData][]
+
+  setQueriesData<TData>(
+    filters: QueryFilters,
+    updater: Updater<TData | undefined, TData>,
+    options?: SetDataOptions
+  ): [QueryKey, TData][]
+
+  setQueriesData<TData>(
+    queryKeyOrFilters: QueryKey | QueryFilters,
+    updater: Updater<TData | undefined, TData>,
+    options?: SetDataOptions
+  ): [QueryKey, TData][] {
+    return notifyManager.batch(() =>
+      this.getQueryCache()
+        .findAll(queryKeyOrFilters)
+        .map(({ queryKey }) => [
+          queryKey,
+          this.setQueryData<TData>(queryKey, updater, options),
+        ])
+    )
+  }
+
   getQueryState<TData = unknown, TError = undefined>(
     queryKey: QueryKey,
     filters?: QueryFilters

src/core/tests/queryClient.test.tsx

@@ -166,6 +166,44 @@ describe('queryClient', () => {
     })
   })
 
+  describe('setQueriesData', () => {
+    test('should update all existing, matching queries', () => {
+      queryClient.setQueryData(['key', 1], 1)
+      queryClient.setQueryData(['key', 2], 2)
+
+      const result = queryClient.setQueriesData<number>('key', old => old! + 5)
+
+      expect(result).toEqual([
+        [['key', 1], 6],
+        [['key', 2], 7],
+      ])
+      expect(queryClient.getQueryData(['key', 1])).toBe(6)
+      expect(queryClient.getQueryData(['key', 2])).toBe(7)
+    })
+
+    test('should accept queryFilters', () => {
+      queryClient.setQueryData(['key', 1], 1)
+      queryClient.setQueryData(['key', 2], 2)
+      const query1 = queryCache.find(['key', 1])!
+
+      const result = queryClient.setQueriesData<number>(
+        { predicate: query => query === query1 },
+        old => old! + 5
+      )
+
+      expect(result).toEqual([[['key', 1], 6]])
+      expect(queryClient.getQueryData(['key', 1])).toBe(6)
+      expect(queryClient.getQueryData(['key', 2])).toBe(2)
+    })
+
+    test('should not update non existing queries', () => {
+      const result = queryClient.setQueriesData<string>('key', 'data')
+
+      expect(result).toEqual([])
+      expect(queryClient.getQueryData('key')).toBe(undefined)
+    })
+  })
+
   describe('getQueryData', () => {
     test('should return the query data if the query is found', () => {
       const key = queryKey()