Skip to main content

Stale time

A post viewer next to a live table of the cache. Each post stays fresh for 10 seconds and is removed after 30. Switch between posts and watch the "Requests" column: fresh posts come from the cache, stale ones are fetched again.

intermediateuseFetchcache
import { Time, createClient } from "@hyper-fetch/core";

export const client = createClient({ url: "https://dummyjson.com" });

export type Post = { id: number; title: string; body: string };

/**
* Short times so you can watch them run out:
* - `staleTime`: for 10 seconds after a response, the cached post counts as fresh and is not fetched again.
* - `cacheTime`: 30 seconds after a response, the cached post is removed.
*/
export const getPostRequest = client.createRequest<{ response: Post }>()({
endpoint: "/posts/:postId",
staleTime: 10 * Time.SEC,
cacheTime: 30 * Time.SEC,
});
Run locallynpx tiged BetterTyped/hyper-fetch/examples/react/stale-time hyper-fetch-react-stale-time && cd hyper-fetch-react-stale-time && npm install && npm run dev
What it shows
  1. staleTime: how long a response counts as fresh. Fresh data is not fetched again.
  2. cacheTime: how long a response stays in the cache before it is removed.
  3. revalidate: a useFetch option that refetches on mount even when the data is fresh, while it shows the cached data right away.
  4. Cache source: the request counter shows when the data came from the network and when it came from the cache.

How it works​

  1. getPostRequest sets both times on the request, so every post shares them:

    export const getPostRequest = client.createRequest<{ response: Post }>()({
    endpoint: "/posts/:postId",
    staleTime: 10 * Time.SEC,
    cacheTime: 30 * Time.SEC,
    });

    The defaults are 5 minutes for both. setStaleTime() and setCacheTime() change them on a single request.

  2. PostView calls useFetch(getPostRequest.setParams({ postId }), { revalidate }). Each postId has its own cache key, so each post has its own timers, counted from its last response.

  3. With revalidate off, switching to a fresh post shows the cached data and sends nothing. Switching to a stale post, or one that was removed, sends a request.

  4. With revalidate on, every switch sends a request. The cached post is still shown at once and replaced when the response arrives (stale-while-revalidate). This is the useFetch default.

  5. CacheTable reads client.cache.get(cacheKey) every half second. responseTimestamp plus staleTime and cacheTime give the countdowns. When cacheTime runs out, the entry is deleted; a mounted useFetch for that key fetches it again.

  6. onRequestStart fires only when a request goes to the network, which is what the "Requests" column counts.

Stale data is not refetched on a timer. It is fetched again the next time something asks for it: a mount, a key change, refetch(), or focus and reconnect events when those options are on.

When to use it
  • Set a long staleTime with revalidate: false for data that rarely changes, such as settings, country lists or profiles. Users switching around the app then trigger no requests.
  • Keep revalidate on for data that changes often, so users see cached data at once and the latest data a moment later.
  • Set cacheTime longer than staleTime. Stale data is still useful as a placeholder while the refetch runs.

Summary

staleTime decides when cached data needs a refetch, cacheTime decides when it is thrown away, and revalidate asks for a background refetch even while the data is fresh.