Skip to content

Commit

Permalink
docs: clarify caching behavior (#3221)
Browse files Browse the repository at this point in the history
The example contains at least one inacurate statement,

> It will then cache the data using `'todos'` and `fetchTodos` as the unique identifiers for that cache.

and could benefit from more precise language.
  • Loading branch information
aryzing authored Jan 22, 2022
1 parent 47bf076 commit 4afd0c3
Showing 1 changed file with 9 additions and 8 deletions.
17 changes: 9 additions & 8 deletions docs/src/pages/guides/caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,17 @@ This caching example illustrates the story and lifecycle of:
Let's assume we are using the default `cacheTime` of **5 minutes** and the default `staleTime` of `0`.

- A new instance of `useQuery(['todos'], fetchTodos)` mounts.
- Since no other queries have been made with this query + variable combination, this query will show a hard loading state and make a network request to fetch the data.
- It will then cache the data using `['todos']` as the unique identifiers for that cache.
- The hook will mark itself as stale after the configured `staleTime` (defaults to `0`, or immediately).
- Since no other queries have been made with the `['todos']` query key, this query will show a hard loading state and make a network request to fetch the data.
- When the network request has completed, the returned data will be cached under the `['todos']` key.
- The hook will mark the data as stale after the configured `staleTime` (defaults to `0`, or immediately).
- A second instance of `useQuery(['todos'], fetchTodos)` mounts elsewhere.
- Because this exact data exists in the cache from the first instance of this query, that data is immediately returned from the cache.
- A background refetch is triggered for both queries (but only one request), since a new instance appeared on screen.
- Both instances are updated with the new data if the fetch is successful
- Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache.
- The new instance triggers a new network request using its query function.
- Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/useQuery) are updated (including `isFetching`, `isLoading`, and other related values) because they have the same query key.
- When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data.
- Both instances of the `useQuery(['todos'], fetchTodos)` query are unmounted and no longer in use.
- Since there are no more active instances of this query, a cache timeout is set using `cacheTime` to delete and garbage collect the query (defaults to **5 minutes**).
- Before the cache timeout has completed another instance of `useQuery(['todos'], fetchTodos)` mounts. The query immediately returns the available cached value while the `fetchTodos` function is being run in the background to populate the query with a fresh value.
- Before the cache timeout has completed, another instance of `useQuery(['todos'], fetchTodos)` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
- The final instance of `useQuery(['todos'], fetchTodos)` unmounts.
- No more instances of `useQuery(['todos'], fetchTodos)` appear within **5 minutes**.
- This query and its data are deleted and garbage collected.
- The cached data under the `['todos']` key is deleted and garbage collected.

0 comments on commit 4afd0c3

Please sign in to comment.