Add onSuccess/onError/onSettled callbacks to useQuery

docs/framework/react/reference/useQuery.md

@@ -43,6 +43,9 @@ const {
     notifyOnChangeProps,
     placeholderData,
     queryKeyHashFn,
+    onSuccess,
+    onError,
+    onSettled,
     refetchInterval,
     refetchIntervalInBackground,
     refetchOnMount,
@@ -106,6 +109,18 @@ const {
 - `queryKeyHashFn: (queryKey: QueryKey) => string`
   - Optional
   - If specified, this function is used to hash the `queryKey` to a string.
+- `onSuccess: (data: TData | undefined) => Promise<unknown> | unknown`
+  - Optional
+  - This function will fire when the `queryFn` is successful and will be passed the `data`.
+  - Void function, the returned value will be ignored
+- `onError: (error: TError | null) => Promise<unknown> | unknown`
+  - Optional
+  - This function will fire if the `queryFn` encounters an error and will be passed the `error`
+  - Void function, the returned value will be ignored
+- `onSettled: (data: TData | undefined, error: TError | null) => Promise<unknown> | unknown`
+  - Optional
+  - This function will fire when the `queryFn` is either successfully fetched or encounters an error and be passed either the `data` or `error`
+  - Void function, the returned value will be ignored
 - `refetchInterval: number | false | ((query: Query) => number | false | undefined)`
   - Optional
   - If set to a number, all queries will continuously refetch at this frequency in milliseconds

docs/framework/solid/reference/useQuery.md

@@ -43,6 +43,9 @@ const {
     initialDataUpdatedAt,
     meta,
     queryKeyHashFn,
+    onSuccess,
+    onError,
+    onSettled,
     refetchInterval,
     refetchIntervalInBackground,
     refetchOnMount,
@@ -244,6 +247,18 @@ function App() {
   - ##### `queryKeyHashFn: (queryKey: QueryKey) => string`
     - Optional
     - If specified, this function is used to hash the `queryKey` to a string.
+  - ##### `onSuccess: (data: TData | undefined) => Promise<unknown> | unknown`
+    - Optional
+    - This function will fire when the `queryFn` is successful and will be passed the `data`.
+    - Void function, the returned value will be ignored
+  - ##### `onError: (error: TError | null) => Promise<unknown> | unknown`
+    - Optional
+    - This function will fire if the `queryFn` encounters an error and will be passed the `error`
+    - Void function, the returned value will be ignored
+  - ##### `onSettled: (data: TData | undefined, error: TError | null) => Promise<unknown> | unknown`
+    - Optional
+    - This function will fire when the `queryFn` is either successfully fetched or encounters an error and be passed either the `data` or `error`
+    - Void function, the returned value will be ignored
   - ##### `refetchInterval: number | false | ((query: Query) => number | false | undefined)`
     - Optional
     - If set to a number, all queries will continuously refetch at this frequency in milliseconds

examples/react/nextjs-suspense-streaming/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES5",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -12,7 +16,7 @@
     "moduleResolution": "Bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "plugins": [
       {
@@ -27,5 +31,7 @@
     ".next/types/**/*.ts",
     ".next/dev/types/**/*.ts"
   ],
-  "exclude": ["node_modules"]
+  "exclude": [
+    "node_modules"
+  ]
 }

packages/angular-query-experimental/src/__tests__/inject-query.test.ts

@@ -766,4 +766,37 @@ describe('injectQuery', () => {
       expect(callCount).toBe(2)
     })
   })
+
+
+  test('callbacks `onSuccess`, `onError` and `onSettled` should be called after a successful fetch', async () => {
+    const onSuccessMock = vi.fn()
+    const onFailureMock = vi.fn()
+    const onSuccessSettledMock = vi.fn()
+    const onFailureSettledMock = vi.fn()
+
+
+    TestBed.runInInjectionContext(() => {
+      injectQuery(() => ({
+        queryKey: ['expected-success'],
+        queryFn: () => 'fetched',
+        onSuccess: (data) => onSuccessMock(data),
+        onSettled: (data, _) => onSuccessSettledMock(data),
+      }));
+
+      injectQuery(() => ({
+        queryKey: ['expected-failure'],
+        queryFn: () => Promise.reject(new Error('error')),
+        onError: (error) => onFailureMock(error),
+        onSettled: (_, error) => onFailureSettledMock(error),
+        retry: false,
+      }));
+    })
+
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect(onSuccessMock).toHaveBeenCalled()
+    expect(onSuccessSettledMock).toHaveBeenCalled()
+    expect(onFailureMock).toHaveBeenCalled()
+    expect(onFailureSettledMock).toHaveBeenCalled()
+  })
 })

packages/query-core/src/__tests__/query.test.tsx

@@ -1305,6 +1305,29 @@ describe('query', () => {
     })
   })
 
+  test('query options callbacks should be called in correct order with correct arguments for error case', async () => {
+    const onError = vi.fn()
+    const onSettled = vi.fn()
+
+    const key = queryKey()
+
+    await expect(
+      queryClient.fetchQuery({
+        queryKey: key,
+        queryFn: () => Promise.reject(new Error('error')),
+        retry: false,
+        onError,
+        onSettled,
+      }),
+    ).rejects.toBeDefined()
+
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect(onError.mock.calls[0]![0]).toEqual(expect.any(Error))
+
+    expect(onSettled).toHaveBeenCalledTimes(1)
+    expect(onSettled).toHaveBeenCalledWith(undefined, expect.any(Error))
+  })
+
   test('should not increment dataUpdateCount when setting initialData on prefetched query', async () => {
     const key = queryKey()
     const queryFn = vi.fn().mockImplementation(() => 'fetched-data')
@@ -1347,4 +1370,34 @@ describe('query', () => {
     const updatedResult = observer.getCurrentResult()
     expect(updatedResult.isFetchedAfterMount).toBe(true)
   })
+
+
+  test('callbacks `onSuccess`, `onError` and `onSettled` should be called', async () => {
+    const onSuccessMock = vi.fn()
+    const onFailureMock = vi.fn()
+    const onSuccessSettledMock = vi.fn()
+    const onFailureSettledMock = vi.fn()
+
+    await queryClient.fetchQuery({
+      queryKey: ['expected-success'],
+      queryFn: () => 'fetched',
+      onSuccess: onSuccessMock,
+      onSettled: onSuccessSettledMock,
+    })
+
+    await expect(
+      queryClient.fetchQuery({
+        queryKey: ['expected-failure'],
+        queryFn: () => Promise.reject(new Error('error')),
+        onError: (error) => onFailureMock(error),
+        onSettled: (_, error) => onFailureSettledMock(error),
+        retry: false
+      })
+    ).rejects.toBeDefined()
+
+    expect(onSuccessMock).toHaveBeenCalled()
+    expect(onSuccessSettledMock).toHaveBeenCalled()
+    expect(onFailureMock).toHaveBeenCalled()
+    expect(onFailureSettledMock).toHaveBeenCalled()
+  })
 })

packages/query-core/src/__tests__/queryObserver.test.tsx

@@ -934,6 +934,62 @@ describe('queryObserver', () => {
     expect(observer.getCurrentResult().data).toBe(selectedData2)
   })
 
+  test('observer callbacks should be called in correct order with correct arguments for success case', async () => {
+    const onSuccess = vi.fn()
+    const onSettled = vi.fn()
+
+    const key = queryKey()
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => Promise.resolve('SUCCESS'),
+      onSuccess,
+      onSettled,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(onSuccess).toHaveBeenCalled()
+    expect(onSuccess).toHaveBeenLastCalledWith('SUCCESS')
+
+    expect(onSettled).toHaveBeenCalled()
+    expect(onSettled).toHaveBeenLastCalledWith('SUCCESS', null)
+
+    unsubscribe()
+  })
+
+  test('observer callbacks should be called in correct order with correct arguments for error case', async () => {
+    const onError = vi.fn()
+    const onSettled = vi.fn()
+
+    const err = new Error('err')
+    const key = queryKey()
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => Promise.reject(err),
+      retry: false,
+      onError,
+      onSettled,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(onError).toHaveBeenCalled()
+    const onErrorLast = onError.mock.calls.at(-1)![0]
+    expect(onErrorLast).toEqual(expect.any(Error))
+    expect(onErrorLast.message).toBe('err')
+
+    expect(onSettled).toHaveBeenCalled()
+    expect(onSettled).toHaveBeenLastCalledWith(undefined, expect.any(Error))
+
+    unsubscribe()
+  })
+
   test('should pass the correct previous queryKey (from prevQuery) to placeholderData function params with select', async () => {
     const results: Array<QueryObserverResult> = []
     const keys: Array<ReadonlyArray<unknown> | null> = []

packages/query-core/src/query.ts

@@ -557,6 +557,13 @@ export class Query<
 
       this.setData(data)
 
+      // Notify per-query callback
+      await this.options.onSuccess?.(data)
+      await this.options.onSettled?.(
+        data,
+        this.state.error as any,
+      )
+
       // Notify cache callback
       this.#cache.config.onSuccess?.(data, this as Query<any, any, any, any>)
       this.#cache.config.onSettled?.(
@@ -586,6 +593,13 @@ export class Query<
         error: error as TError,
       })
 
+      // Notify per-query callback
+      await this.options.onError?.(error as any)
+      await this.options.onSettled?.(
+        this.state.data,
+        error as any,
+      )
+
       // Notify cache callback
       this.#cache.config.onError?.(
         error as any,

packages/query-core/src/queryObserver.ts

@@ -155,7 +155,7 @@ export class QueryObserver<
       typeof this.options.enabled !== 'boolean' &&
       typeof this.options.enabled !== 'function' &&
       typeof resolveEnabled(this.options.enabled, this.#currentQuery) !==
-        'boolean'
+      'boolean'
     ) {
       throw new Error(
         'Expected enabled to be a boolean or a callback that returns a boolean',
@@ -199,9 +199,9 @@ export class QueryObserver<
       mounted &&
       (this.#currentQuery !== prevQuery ||
         resolveEnabled(this.options.enabled, this.#currentQuery) !==
-          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
+        resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
         resolveStaleTime(this.options.staleTime, this.#currentQuery) !==
-          resolveStaleTime(prevOptions.staleTime, this.#currentQuery))
+        resolveStaleTime(prevOptions.staleTime, this.#currentQuery))
     ) {
       this.#updateStaleTimeout()
     }
@@ -213,7 +213,7 @@ export class QueryObserver<
       mounted &&
       (this.#currentQuery !== prevQuery ||
         resolveEnabled(this.options.enabled, this.#currentQuery) !==
-          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
+        resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
         nextRefetchInterval !== this.#currentRefetchInterval)
     ) {
       this.#updateRefetchInterval(nextRefetchInterval)
@@ -502,11 +502,11 @@ export class QueryObserver<
         placeholderData =
           typeof options.placeholderData === 'function'
             ? (
-                options.placeholderData as unknown as PlaceholderDataFunction<TQueryData>
-              )(
-                this.#lastQueryWithDefinedData?.state.data,
-                this.#lastQueryWithDefinedData as any,
-              )
+              options.placeholderData as unknown as PlaceholderDataFunction<TQueryData>
+            )(
+              this.#lastQueryWithDefinedData?.state.data,
+              this.#lastQueryWithDefinedData as any,
+            )
             : options.placeholderData
       }
 
@@ -606,7 +606,7 @@ export class QueryObserver<
       const recreateThenable = () => {
         const pending =
           (this.#currentThenable =
-          nextResult.promise =
+            nextResult.promise =
             pendingThenable())
 
         finalizeThenableIfPossible(pending)
@@ -662,7 +662,7 @@ export class QueryObserver<
       return
     }
 
-    this.#currentResult = nextResult
+    this.#currentResult = nextResult 
 
     const shouldNotifyListeners = (): boolean => {
       if (!prevResult) {
@@ -698,7 +698,7 @@ export class QueryObserver<
       })
     }
 
-    this.#notify({ listeners: shouldNotifyListeners() })
+    this.#notify({ query: this.#currentQuery, listeners: shouldNotifyListeners() })
   }
 
   #updateQuery(): void {
@@ -728,9 +728,31 @@ export class QueryObserver<
     }
   }
 
-  #notify(notifyOptions: { listeners: boolean }): void {
+  #notify(notifyOptions: { query: Query<TQueryFnData, TError, TQueryData, TQueryKey>, listeners: boolean }): void {
     notifyManager.batch(() => {
-      // First, trigger the listeners
+      // First trigger the mutate callbacks
+      if (this.hasListeners()) {
+
+        if (notifyOptions.query.state.status === 'success') {
+          this.options.onSuccess?.(
+            notifyOptions.query.state.data
+          )
+          this.options.onSettled?.(
+            notifyOptions.query.state.data,
+            null,
+          )
+        } else if (notifyOptions.query.state.status === 'error') {
+          this.options.onError?.(
+            notifyOptions.query.state.error,
+          )
+          this.options.onSettled?.(
+            undefined,
+            notifyOptions.query.state.error,
+          )
+        }
+      }
+
+      // Then trigger the listeners
       if (notifyOptions.listeners) {
         this.listeners.forEach((listener) => {
           listener(this.#currentResult)