Consider renaming cacheTime

[TkDodo]

I see some confusion about cacheTime / staleTime. People tend to mix up the two, thinking that cacheTime is the time they need to tweak so that react-query will re-fetch the query (or set it to Infinity to try to avoid refetches).

I know the docs already mention what it’s for:

The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration.

But maybe something like gcTime would be more fitting? I think that it is not something that people need / want to tweak often, but judging by the current name, it sounds like an important setting.

Thoughts @tannerlinsley @boschni ?

[tannerlinsley]

I think they both technically describe exactly what they do, and I like that. A little bit of general education and clarification of a term also never hurts. I’d like to keep them.

[weyert]

The cacheTime suggests the time the queries will get cached, and staleTime suggest the time when a query is considered 'stale'. Suggested by their naming. Looks like that's an incorrect interpretation?

[TkDodo]

The cacheTime suggests the time the queries will get cached, and staleTime suggest the time when a query is considered 'stale'.

@weyert if you put it like that, I think the naming is spot-on. As long as you understand that "time the queries will get cached" means that they will removed from the cache completely after that time, and you understand what "stale" means.

[weyert]

Cool, that was my understanding, my understanding of stale is that the time since the last time a query has been used. E.g. staleTime is 5 minutes, if you call the query twice, then second call time + 5 minutes that the cached value of the query gets removed. Not sure how it works when cacheTime is higher than staleTime though.

[TkDodo]

Yes, this is also correct. If cacheTime is higher than staleTime, your query will never be stale. It will be active and then it will be removed from the cache if cacheTime hits, which means the next time you use it, you will be in "hard loading" state again.

[janaagaard75]

I think it's a great idea to rename cacheTime to something else, but I am not that fund of the proposed gcTime because I don't see 'gc' as an abbreviation that is generally understood - why not garbageCollectTime? If this name would mean that most (I guess) developers won't have to consult the documentation, and as such I think it is a big improvement over gcTime, even though it's longer.

[TkDodo]

In #4252 , we've discussed some alternatives and we currently think inactiveCacheTime would be a good name.