Skip to main content

refetch

Description: Defines a "soft" expiration interval (in milliseconds). When a component renders, Archibald checks this interval to decide if a background refresh is needed.

Default Value: 300000 (5 minutes).

  • How It Works:

    • Reactive, not Proactive: refetch does not use an active timer (setInterval). It only performs a check when the component using the hook actually renders or re-renders.
    • Soft Limit: It acts as a "soft" expiration. When the refetch time passes, the cache entry is marked as stale.
    • Background Update: If a component renders and the data is stale, Archibald triggers a background fetch. The component continues to show the existing cached data (keeping isDone: true) until the new data arrives, preventing UI flickering.
    • Respects ttl: refetch respects the ttl (hard limit). If ttl is reached before refetch, the data is considered expired. If refetch is reached first, it is only stale.

  • Key Difference: refetch vs. poll:

    • poll: An active timer. It forces a fetch at fixed intervals regardless of component rendering (as long as it's mounted). Use this for real-time data.
    • refetch: A passive check. It only checks "is the data old?" when the UI actually needs to display it (i.e., on a re-render). Use this for data that doesn't change constantly but should stay relatively fresh.

  • How To: Use refetch to ensure that users who stay on a page for a long time eventually get updated data without seeing a "hard" loading state. Note that since it is reactive, the update is only triggered if the component (or its parent) re-renders for any reason.

    // Data is valid for 15 mins, but will attempt 
    // a background refresh after 5 mins on next render.
    useFetch(
        'profile',
        fetchProfile,
        { 
            ttl: 15 * 60 * 1000, 
            refetch: 5 * 60 * 1000 
        }
    );

  • Best Practice:

    refetch vs ttl

    Always keep refetch lower than or equal to ttl. If refetch is higher than ttl, the data will hit the hard expiration (ttl) and trigger a full fetch before the "soft" refetch interval is even reached.

    • Use refetch: -1 to disable this behavior entirely, meaning data will only be refreshed if it completely expires (ttl) or if a manual refetch() is called.
    • If you use ttl: -1 (endless caching), you can still use refetch to allow the "permanent" data to be updated in the background when components re-render.