feat(subscriptions): add event types and metadata to subscriptions (TanStack#1792)

* feat(subscriptions): add event types and metadata to subscriptions

* better types, update tests

* remove unnecessary setStateOptions

* rename to queryUpdated event, add observers where possible

* Cleanup

* Update queryObserver.ts

Author: tannerlinsley

src/core/query.ts

@@ -289,7 +289,7 @@ export class Query<
       // Stop the query from being garbage collected
       this.clearGcTimeout()
 
-      this.cache.notify(this)
+      this.cache.notify({ type: 'observerAdded', query: this, observer })
     }
   }
 
@@ -315,7 +315,7 @@ export class Query<
         }
       }
 
-      this.cache.notify(this)
+      this.cache.notify({ type: 'observerRemoved', query: this, observer })
     }
   }
 
@@ -401,7 +401,7 @@ export class Query<
           this.optionalRemove()
         }
       },
-      onError: error => {
+      onError: (error: TError | { silent?: boolean }) => {
         // Optimistically update state if needed
         if (!(isCancelledError(error) && error.silent)) {
           this.dispatch({
@@ -451,7 +451,7 @@ export class Query<
         observer.onQueryUpdate(action)
       })
 
-      this.cache.notify(this)
+      this.cache.notify({ query: this, type: 'queryUpdated', action })
     })
   }
 

src/core/queryCache.ts

@@ -4,11 +4,12 @@ import {
   matchQuery,
   parseFilterArgs,
 } from './utils'
-import { Query, QueryState } from './query'
+import { Action, Query, QueryState } from './query'
 import type { QueryKey, QueryOptions } from './types'
 import { notifyManager } from './notifyManager'
 import type { QueryClient } from './queryClient'
 import { Subscribable } from './subscribable'
+import { QueryObserver } from './queryObserver'
 
 // TYPES
 
@@ -20,7 +21,48 @@ interface QueryHashMap {
   [hash: string]: Query<any, any>
 }
 
-type QueryCacheListener = (query?: Query) => void
+interface NotifyEventQueryAdded {
+  type: 'queryAdded'
+  query: Query<any, any>
+}
+
+interface NotifyEventQueryRemoved {
+  type: 'queryRemoved'
+  query: Query<any, any>
+}
+
+interface NotifyEventQueryUpdated {
+  type: 'queryUpdated'
+  query: Query<any, any>
+  action: Action<any, any>
+}
+
+interface NotifyEventObserverAdded {
+  type: 'observerAdded'
+  query: Query<any, any>
+  observer: QueryObserver<any, any, any, any>
+}
+
+interface NotifyEventObserverRemoved {
+  type: 'observerRemoved'
+  query: Query<any, any>
+  observer: QueryObserver<any, any, any, any>
+}
+
+interface NotifyEventObserverResultsUpdated {
+  type: 'observerResultsUpdated'
+  query: Query<any, any>
+}
+
+type QueryCacheNotifyEvent =
+  | NotifyEventQueryAdded
+  | NotifyEventQueryRemoved
+  | NotifyEventQueryUpdated
+  | NotifyEventObserverAdded
+  | NotifyEventObserverRemoved
+  | NotifyEventObserverResultsUpdated
+
+type QueryCacheListener = (event?: QueryCacheNotifyEvent) => void
 
 // CLASS
 
@@ -66,7 +108,10 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     if (!this.queriesMap[query.queryHash]) {
       this.queriesMap[query.queryHash] = query
       this.queries.push(query)
-      this.notify(query)
+      this.notify({
+        type: 'queryAdded',
+        query,
+      })
     }
   }
 
@@ -82,7 +127,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
         delete this.queriesMap[query.queryHash]
       }
 
-      this.notify(query)
+      this.notify({ type: 'queryRemoved', query })
     }
   }
 
@@ -127,10 +172,10 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
       : this.queries
   }
 
-  notify(query?: Query<any, any>) {
+  notify(event: QueryCacheNotifyEvent) {
     notifyManager.batch(() => {
       this.listeners.forEach(listener => {
-        listener(query)
+        listener(event)
       })
     })
   }

src/core/queryObserver.ts

@@ -614,7 +614,9 @@ export class QueryObserver<
 
       // Then the cache listeners
       if (notifyOptions.cache) {
-        this.client.getQueryCache().notify(this.currentQuery)
+        this.client
+          .getQueryCache()
+          .notify({ query: this.currentQuery, type: 'observerResultsUpdated' })
       }
     })
   }

src/core/tests/queryCache.test.tsx

@@ -22,7 +22,7 @@ describe('queryCache', () => {
       queryClient.setQueryData(key, 'foo')
       const query = queryCache.find(key)
       await sleep(1)
-      expect(subscriber).toHaveBeenCalledWith(query)
+      expect(subscriber).toHaveBeenCalledWith({ query, type: 'queryAdded' })
       unsubscribe()
     })
 
@@ -42,7 +42,7 @@ describe('queryCache', () => {
       queryClient.prefetchQuery(key, () => 'data')
       const query = queryCache.find(key)
       await sleep(100)
-      expect(callback).toHaveBeenCalledWith(query)
+      expect(callback).toHaveBeenCalledWith({ query, type: 'queryAdded' })
     })
 
     test('should notify subscribers when new query with initialData is added', async () => {