feat: add error callback for queries and mutations (#1504)

Author: boschni

docs/src/pages/reference/MutationCache.md

@@ -10,7 +10,11 @@ The `MutationCache` is the storage for mutations.
 ```js
 import { MutationCache } from 'react-query'
 
-const mutationCache = new MutationCache()
+const mutationCache = new MutationCache({
+  onError: error => {
+    console.log(error)
+  },
+})
 ```
 
 Its available methods are:
@@ -19,6 +23,12 @@ Its available methods are:
 - [`subscribe`](#mutationcachesubscribe)
 - [`clear`](#mutationcacheclear)
 
+**Options**
+
+- `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => void`
+  - Optional
+  - This function will be called if some mutation encounters an error.
+
 ## `mutationCache.getAll`
 
 `getAll` returns all mutations within the cache.

docs/src/pages/reference/QueryCache.md

@@ -10,7 +10,12 @@ The `QueryCache` is the storage mechanism for React Query. It stores all of the
 ```js
 import { QueryCache } from 'react-query'
 
-const queryCache = new QueryCache()
+const queryCache = new QueryCache({
+  onError: error => {
+    console.log(error)
+  },
+})
+
 const query = queryCache.find('posts')
 ```
 
@@ -21,6 +26,12 @@ Its available methods are:
 - [`subscribe`](#querycachesubscribe)
 - [`clear`](#querycacheclear)
 
+**Options**
+
+- `onError?: (error: unknown, query: Query) => void`
+  - Optional
+  - This function will be called if some query encounters an error.
+
 ## `queryCache.find`
 
 `find` is a slightly more advanced synchronous method that can be used to get an existing query instance from the cache. This instance not only contains **all** the state for the query, but all of the instances, and underlying guts of the query as well. If the query does not exist, `undefined` will be returned.

src/core/mutation.ts

@@ -177,7 +177,19 @@ export class Mutation<
         return data
       })
       .catch(error => {
+        // Notify cache callback
+        if (this.mutationCache.config.onError) {
+          this.mutationCache.config.onError(
+            error,
+            this.state.variables,
+            this.state.context,
+            this as Mutation<unknown, unknown, unknown, unknown>
+          )
+        }
+
+        // Log error
         getLogger().error(error)
+
         return Promise.resolve()
           .then(() =>
             this.options.onError?.(

src/core/mutationCache.ts

@@ -7,16 +7,28 @@ import { Subscribable } from './subscribable'
 
 // TYPES
 
+interface MutationCacheConfig {
+  onError?: (
+    error: unknown,
+    variables: unknown,
+    context: unknown,
+    mutation: Mutation<unknown, unknown, unknown, unknown>
+  ) => void
+}
+
 type MutationCacheListener = (mutation?: Mutation) => void
 
 // CLASS
 
 export class MutationCache extends Subscribable<MutationCacheListener> {
+  config: MutationCacheConfig
+
   private mutations: Mutation<any, any, any, any>[]
   private mutationId: number
 
-  constructor() {
+  constructor(config?: MutationCacheConfig) {
     super()
+    this.config = config || {}
     this.mutations = []
     this.mutationId = 0
   }

src/core/query.ts

@@ -412,26 +412,32 @@ export class Query<
           })
         }
 
-        // Log error
         if (!isCancelledError(error)) {
+          // Notify cache callback
+          if (this.cache.config.onError) {
+            this.cache.config.onError(error, this as Query)
+          }
+
+          // Log error
           getLogger().error(error)
         }
+
         // Remove query after fetching if cache time is 0
         if (this.cacheTime === 0) {
           this.optionalRemove()
         }
 
         // Propagate error
         throw error
-      }).then(
-          promise => {
-            if (this.cacheTime === 0) {
-              this.optionalRemove()
-            }
-            return promise
-          }
-      )
+      })
+      .then(data => {
+        // Remove query after fetching if cache time is 0
+        if (this.cacheTime === 0) {
+          this.optionalRemove()
+        }
 
+        return data
+      })
 
     return this.promise
   }

src/core/queryCache.ts

@@ -12,6 +12,10 @@ import { Subscribable } from './subscribable'
 
 // TYPES
 
+interface QueryCacheConfig {
+  onError?: (error: unknown, query: Query<unknown, unknown, unknown>) => void
+}
+
 interface QueryHashMap {
   [hash: string]: Query<any, any>
 }
@@ -21,12 +25,14 @@ type QueryCacheListener = (query?: Query) => void
 // CLASS
 
 export class QueryCache extends Subscribable<QueryCacheListener> {
+  config: QueryCacheConfig
+
   private queries: Query<any, any>[]
   private queriesMap: QueryHashMap
 
-  constructor() {
+  constructor(config?: QueryCacheConfig) {
     super()
-
+    this.config = config || {}
     this.queries = []
     this.queriesMap = {}
   }

src/core/tests/mutationCache.test.tsx

@@ -0,0 +1,28 @@
+import { queryKey, mockConsoleError } from '../../react/tests/utils'
+import { MutationCache, QueryClient } from '../..'
+
+describe('mutationCache', () => {
+  describe('MutationCacheConfig.onError', () => {
+    test('should be called when a mutation errors', async () => {
+      const consoleMock = mockConsoleError()
+      const key = queryKey()
+      const onError = jest.fn()
+      const testCache = new MutationCache({ onError })
+      const testClient = new QueryClient({ mutationCache: testCache })
+
+      try {
+        await testClient.executeMutation({
+          mutationKey: key,
+          variables: 'vars',
+          mutationFn: () => Promise.reject('error'),
+          onMutate: () => 'context',
+        })
+      } catch {
+        consoleMock.mockRestore()
+      }
+
+      const mutation = testCache.getAll()[0]
+      expect(onError).toHaveBeenCalledWith('error', 'vars', 'context', mutation)
+    })
+  })
+})

src/core/tests/queryCache.test.tsx

@@ -1,4 +1,4 @@
-import { sleep, queryKey } from '../../react/tests/utils'
+import { sleep, queryKey, mockConsoleError } from '../../react/tests/utils'
 import { QueryCache, QueryClient } from '../..'
 
 describe('queryCache', () => {
@@ -130,4 +130,18 @@ describe('queryCache', () => {
       expect(queryCache.findAll('posts')).toEqual([query4])
     })
   })
+
+  describe('QueryCacheConfig.onError', () => {
+    test('should be called when a query errors', async () => {
+      const consoleMock = mockConsoleError()
+      const key = queryKey()
+      const onError = jest.fn()
+      const testCache = new QueryCache({ onError })
+      const testClient = new QueryClient({ queryCache: testCache })
+      await testClient.prefetchQuery(key, () => Promise.reject('error'))
+      consoleMock.mockRestore()
+      const query = testCache.find(key)
+      expect(onError).toHaveBeenCalledWith('error', query)
+    })
+  })
 })