feat(queryCache): pass query to subscribers (TanStack#765)

Any cache update triggered by a query will pass the query as the second argument to subscribers.
This enables executing side-effects for specific query updates.

Author: TuckerWhitehouse

docs/src/pages/docs/api.md

@@ -580,15 +580,16 @@ The `subscribe` method can be used to subscribe to the query cache as a whole an
 ```js
 import { queryCache } from 'react-query'
 
-const callback = cache => {}
+const callback = (cache, query) => {}
 
 const unsubscribe = queryCache.subscribe(callback)
 ```
 
 **Options**
 
-- `callback: Function(queryCache) => void`
+- `callback: Function(queryCache, query?) => void`
   - This function will be called with the query cache any time it is updated via its tracked update mechanisms (eg, `query.setState`, `queryCache.removeQueries`, etc). Out of scope mutations to the queryCache are not encouraged and will not fire subscription callbacks
+  - Additionally, for updates to the cache triggered by a specific query, the `query` will be passed as the second argument to the callback
 
 **Returns**
 

src/core/query.js

@@ -65,7 +65,7 @@ export function makeQuery({
   query.dispatch = action => {
     query.state = queryReducer(query.state, action)
     query.instances.forEach(d => d.onStateUpdate(query.state))
-    notifyGlobalListeners()
+    notifyGlobalListeners(query)
   }
 
   query.scheduleStaleTimeout = () => {
@@ -158,7 +158,7 @@ export function makeQuery({
     query.cancel()
     query.dispatch = noop
     delete queryCache.queries[query.queryHash]
-    notifyGlobalListeners()
+    notifyGlobalListeners(query)
   }
 
   query.subscribe = (onStateUpdate = noop) => {

src/core/queryCache.js

@@ -17,21 +17,21 @@ export function makeQueryCache({ frozen = isServer, defaultConfig } = {}) {
   const globalListeners = []
 
   const configRef = defaultConfig
-    ? { current: { ...defaultConfigRef.current, ...defaultConfig }}
+    ? { current: { ...defaultConfigRef.current, ...defaultConfig } }
     : defaultConfigRef
 
   const queryCache = {
     queries: {},
     isFetching: 0,
   }
 
-  const notifyGlobalListeners = () => {
+  const notifyGlobalListeners = query => {
     queryCache.isFetching = Object.values(queryCache.queries).reduce(
       (acc, query) => (query.state.isFetching ? acc + 1 : acc),
       0
     )
 
-    globalListeners.forEach(d => d(queryCache))
+    globalListeners.forEach(d => d(queryCache, query))
   }
 
   queryCache.subscribe = cb => {

src/core/tests/queryCache.test.js

@@ -86,6 +86,17 @@ describe('queryCache', () => {
     expect(callback).toHaveBeenCalled()
   })
 
+  test('should include the queryCache and query when notifying listeners', () => {
+    const callback = jest.fn()
+
+    queryCache.subscribe(callback)
+
+    queryCache.prefetchQuery('test', () => 'data')
+    const query = queryCache.getQuery('test')
+
+    expect(callback).toHaveBeenCalledWith(queryCache, query)
+  })
+
   test('should notify subscribers when new query with initialData is added', async () => {
     const callback = jest.fn()
 

types/index.d.ts

@@ -627,7 +627,7 @@ export interface QueryCache {
     { exact }?: { exact?: boolean }
   ): void
   isFetching: number
-  subscribe(callback: (queryCache: QueryCache) => void): () => void
+  subscribe(callback: (queryCache: QueryCache, query?: CachedQuery<unknown>) => void): () => void
   clear(options?: { notify?: boolean }): void
   resetErrorBoundaries: () => void
 }