Update method query observer base result

docs/src/pages/reference/useQuery.md

@@ -25,6 +25,7 @@ const {
   isSuccess,
   refetch,
   remove,
+  update,
   status,
 } = useQuery(queryKey, queryFn?, {
   cacheTime,
@@ -246,3 +247,7 @@ const result = useQuery({
   - If `cancelRefetch` is `true`, then the current request will be cancelled before a new request is made
 - `remove: () => void`
   - A function to remove the query from the cache.
+- `update: (updater: TData | (oldData: TData | undefined) => TData) => void`
+  - A convenience function to optimistically update the query.
+  - It calls [`queryClient.setQueryData`](../reference/QueryClient#queryclientsetquerydata) internally with the key that was provided to the `useQuery` hook
+  - If its called without providing a query key to the `useQuery` hook, it will throw a warning in the console

src/core/queryObserver.ts

@@ -1,4 +1,4 @@
-import { RefetchQueryFilters } from './types'
+import { RefetchQueryFilters, SetDataOptions } from './types'
 import {
   isServer,
   isValidTimeout,
@@ -99,6 +99,7 @@ export class QueryObserver<
   protected bindMethods(): void {
     this.remove = this.remove.bind(this)
     this.refetch = this.refetch.bind(this)
+    this.update = this.update.bind(this)
   }
 
   protected onSubscribe(): void {
@@ -311,6 +312,18 @@ export class QueryObserver<
     })
   }
 
+  update(updater: any, setDataOptions?: SetDataOptions | undefined) {
+    if (this?.options?.queryKey) {
+      return this.client.setQueryData(
+        this.options.queryKey,
+        updater,
+        setDataOptions
+      )
+    }
+
+    getLogger().warn('Called update on a query without queryKey being set')
+  }
+
   fetchOptimistic(
     options: QueryObserverOptions<
       TQueryFnData,
@@ -604,6 +617,7 @@ export class QueryObserver<
       isStale: isStale(query, options),
       refetch: this.refetch,
       remove: this.remove,
+      update: this.update,
     }
 
     return result as QueryObserverResult<TData, TError>

src/core/tests/queryObserver.test.tsx

@@ -814,4 +814,18 @@ describe('queryObserver', () => {
 
     unsubscribe()
   })
+
+  test('optimistically update result after calling the update method', async () => {
+    const key = queryKey()
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => Promise.reject({ count: 1 }),
+    })
+
+    observer.update({ count: 2 })
+
+    expect(observer.getOptimisticResult(observer.options)).toMatchObject({
+      data: { count: 2 },
+    })
+  })
 })

src/core/types.ts

@@ -346,6 +346,7 @@ export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
     options?: RefetchOptions & RefetchQueryFilters<TPageData>
   ) => Promise<QueryObserverResult<TData, TError>>
   remove: () => void
+  update: (updater: any, setDataOptions?: SetDataOptions | undefined) => void
   status: QueryStatus
 }
 

src/react/tests/useInfiniteQuery.test.tsx

@@ -95,6 +95,7 @@ describe('useInfiniteQuery', () => {
       isSuccess: false,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'loading',
     })
 
@@ -126,6 +127,7 @@ describe('useInfiniteQuery', () => {
       isSuccess: true,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'success',
     })
   })

src/react/tests/useQuery.test.tsx

@@ -185,6 +185,7 @@ describe('useQuery', () => {
       isSuccess: false,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function), 
       status: 'loading',
     })
 
@@ -210,6 +211,7 @@ describe('useQuery', () => {
       isSuccess: true,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'success',
     })
   })
@@ -265,6 +267,7 @@ describe('useQuery', () => {
       isSuccess: false,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'loading',
     })
 
@@ -290,6 +293,7 @@ describe('useQuery', () => {
       isSuccess: false,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'loading',
     })
 
@@ -315,6 +319,7 @@ describe('useQuery', () => {
       isSuccess: false,
       refetch: expect.any(Function),
       remove: expect.any(Function),
+      update: expect.any(Function),
       status: 'error',
     })
 
@@ -4871,4 +4876,61 @@ describe('useQuery', () => {
 
     consoleMock.mockRestore()
   })
+  it('should optimistically update query after calling update', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<string>[] = []
+
+    function Page() {
+      const state = useQuery<string>(key, () => Promise.resolve('data'))
+      states.push(state)
+      return (
+        <>
+          <button onClick={() => state.update('updated')}>update</button>
+          <div>{state.data}</div>
+        </>
+      )
+    }
+
+    const rendered = renderWithClient(queryClient, <Page />)
+
+    const fetchBtn = rendered.getByRole('button', { name: 'update' })
+    await waitFor(() => rendered.getByText('data'))
+    fireEvent.click(fetchBtn)
+    await waitFor(() => rendered.getByText('updated'))
+
+    expect(states[0]).toMatchObject({ data: undefined })
+    expect(states[1]).toMatchObject({ data: 'data' })
+    expect(states[2]).toMatchObject({ data: 'updated' })
+    expect(queryClient.getQueryData(key)).toBe('updated')
+    expect(queryCache.find(key)?.state.data).toBe('updated')
+  })
+
+  it('should optimistically update query after calling update with an updater function', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<string>[] = []
+
+    function Page() {
+      const state = useQuery<string>(key, () => Promise.resolve('data'))
+      states.push(state)
+      return (
+        <>
+          <button onClick={() => state.update((old: string) => 'new ' + old)}>update</button>
+          <div>{state.data}</div>
+        </>
+      )
+    }
+
+    const rendered = renderWithClient(queryClient, <Page />)
+
+    const fetchBtn = rendered.getByRole('button', { name: 'update' })
+    await waitFor(() => rendered.getByText('data'))
+    fireEvent.click(fetchBtn)
+    await waitFor(() => rendered.getByText('new data'))
+
+    expect(states[0]).toMatchObject({ data: undefined })
+    expect(states[1]).toMatchObject({ data: 'data' })
+    expect(states[2]).toMatchObject({ data: 'new data' })
+    expect(queryClient.getQueryData(key)).toBe('new data')
+    expect(queryCache.find(key)?.state.data).toBe('new data')
+  })
 })