Merge pull request #1 from acontreras89/feature/useQuery-reset

Add docs and tests for reset method in useQuery

Author: TkDodo

docs/src/pages/reference/useQuery.md

@@ -24,6 +24,7 @@ const {
   isSuccess,
   refetch,
   remove,
+  reset,
   status,
 } = useQuery(queryKey, queryFn?, {
   cacheTime,
@@ -228,3 +229,6 @@ 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.
+- `reset: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>`
+  - A function to manually reset the query to its initial state.
+  - `options` are used to call `refetch` on the query after it is resetted.

src/react/tests/useQuery.test.tsx

@@ -1032,6 +1032,82 @@ describe('useQuery', () => {
     expect(states[3]).toMatchObject({ data: 2 })
   })
 
+  it('should be able to reset a query', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<number>[] = []
+    let count = 0
+
+    function Page() {
+      const state = useQuery(key, () => ++count)
+
+      states.push(state)
+
+      const { reset } = state
+
+      React.useEffect(() => {
+        setActTimeout(() => {
+          reset()
+        }, 5)
+      }, [reset])
+
+      return null
+    }
+
+    renderWithClient(queryClient, <Page />)
+
+    await sleep(20)
+
+    expect(states.length).toBe(5)
+    // Initial
+    expect(states[0]).toMatchObject({ data: undefined })
+    // Fetched
+    expect(states[1]).toMatchObject({ data: 1 })
+    // Reset
+    expect(states[2]).toMatchObject({ data: undefined })
+    // Initial (refetch)
+    expect(states[3]).toMatchObject({ data: undefined })
+    // Fetched
+    expect(states[4]).toMatchObject({ data: 2 })
+  })
+
+  it('should reset the query to its initial state', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<number>[] = []
+    let count = 0
+
+    function Page() {
+      const state = useQuery(key, () => ++count, { initialData: 99 })
+
+      states.push(state)
+
+      const { reset } = state
+
+      React.useEffect(() => {
+        setActTimeout(() => {
+          reset()
+        }, 5)
+      }, [reset])
+
+      return null
+    }
+
+    renderWithClient(queryClient, <Page />)
+
+    await sleep(20)
+
+    expect(states.length).toBe(5)
+    // Initial
+    expect(states[0]).toMatchObject({ data: 99 })
+    // Fetched
+    expect(states[1]).toMatchObject({ data: 1 })
+    // Reset
+    expect(states[2]).toMatchObject({ data: 99 })
+    // Initial (refetch)
+    expect(states[3]).toMatchObject({ data: 99 })
+    // Fetched
+    expect(states[4]).toMatchObject({ data: 2 })
+  })
+
   it('should share equal data structures between query results', async () => {
     const key = queryKey()