From 4afd0c319aead10d4a93791947ae2479ebcb8832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eduard=20Bardaj=C3=AD=20Puig?= Date: Sat, 22 Jan 2022 21:16:45 +0200 Subject: [PATCH] docs: clarify caching behavior (#3221) 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. --- docs/src/pages/guides/caching.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/src/pages/guides/caching.md b/docs/src/pages/guides/caching.md index e200b53721..1b31bbc494 100644 --- a/docs/src/pages/guides/caching.md +++ b/docs/src/pages/guides/caching.md @@ -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.