Reset query docs and tests (#1393)

* docs: Add resetQueries

* test: Add resetQueries tests

Author: aaronjensen

docs/src/pages/reference/QueryClient.md

@@ -32,6 +32,7 @@ Its available methods are:
 - [`refetchQueries`](#queryclientrefetchqueries)
 - [`cancelQueries`](#queryclientcancelqueries)
 - [`removeQueries`](#queryclientremovequeries)
+- [`resetQueries`](#queryclientresetqueries)
 - [`isFetching`](#queryclientisfetching)
 - [`getDefaultOptions`](#queryclientsetdefaultoptions)
 - [`setDefaultOptions`](#queryclientgetdefaultoptions)
@@ -274,6 +275,30 @@ queryClient.removeQueries(queryKey, { exact: true })
 
 This method does not return anything
 
+## `queryClient.resetQueries`
+
+The `resetQueries` method can be used to reset queries in the cache to their
+initial state based on their query keys or any other functionally accessible
+property/state of the query.
+
+This will notify subscribers — unlike `clear`, which removes all
+subscribers — and reset the query to its pre-loaded state — unlike
+`invalidateQueries`. If a query has `initialData`, the query's data will be
+reset to that.
+
+```js
+queryClient.resetQueries(queryKey, { exact: true })
+```
+
+**Options**
+
+- `queryKey?: QueryKey`: [Query Keys](../guides/query-keys)
+- `filters?: QueryFilters`: [Query Filters](../guides/query-filters)
+
+**Returns**
+
+This method does not return anything
+
 ## `queryClient.isFetching`
 
 This `isFetching` method returns an `integer` representing how many queries, if any, in the cache are currently fetching (including background-fetching, loading new pages, or loading more infinite query results)

src/core/tests/queryCache.test.tsx

@@ -948,6 +948,56 @@ describe('queryCache', () => {
     expect(queryFn2).toHaveBeenCalledTimes(1)
   })
 
+  test('should notify listeners when a query is reset', async () => {
+    const key = queryKey()
+
+    const callback = jest.fn()
+
+    await queryClient.prefetchQuery(key, () => 'data')
+
+    queryCache.subscribe(callback)
+
+    queryClient.resetQueries(key)
+
+    expect(callback).toHaveBeenCalled()
+  })
+
+  test('resetQueries should reset query', async () => {
+    const key = queryKey()
+
+    await queryClient.prefetchQuery(key, () => 'data')
+
+    let state = queryClient.getQueryState(key)
+    expect(state?.data).toEqual('data')
+    expect(state?.status).toEqual('success')
+
+    queryClient.resetQueries(key)
+
+    state = queryClient.getQueryState(key)
+
+    expect(state).toBeTruthy()
+    expect(state?.data).toBeUndefined()
+    expect(state?.status).toEqual('idle')
+  })
+
+  test('resetQueries should reset query data to initial data if set', async () => {
+    const key = queryKey()
+
+    await queryClient.prefetchQuery(key, () => 'data', {
+      initialData: 'initial',
+    })
+
+    let state = queryClient.getQueryState(key)
+    expect(state?.data).toEqual('data')
+
+    queryClient.resetQueries(key)
+
+    state = queryClient.getQueryState(key)
+
+    expect(state).toBeTruthy()
+    expect(state?.data).toEqual('initial')
+  })
+
   test('find should filter correctly', async () => {
     const key = queryKey()
     const testCache = new QueryCache()