Synchronize Stale time

[acraftydev]

I have a number of api endpoints that show data but could be viewed from various screens and the stale time whilst set to the same value will be based on when they open the screen eg

/api/invoice-summary
/api/invoices
/api/inoivce/1/

The issue i have is the stale time will expire differently dependng when the queries are triggered which means they can get out of synch, where i would prefer there are synced so that i have some confiendence they are showing similar values. is that possible?

thanks

[ado11231]

Instead of a countdown, use clock alignment, make all queries expire at the same fixed points in time, TanStack v5 lets staleTime accept a function that returns a number. You calculate "how many milliseconds until the next 5-minute mark" and return that. Every query, no matter when it loads, will go stale at the same clock boundary.

function alignedStaleTime(intervalMs) {
  return () => {
    const now = Date.now();
    const nextBoundary = Math.ceil(now / intervalMs) * intervalMs;
    return nextBoundary - now;
  };
}

Apply the same function to all related queries and they'll always expire together.

[devangpratap]

staleTime starts counting from when each query's data was last fetched. If the queries fire at different times, they'll naturally drift out of sync. There's no built-in way to align their timers.

The simplest fix is to structure your keys with a shared prefix and invalidate them together.

useQuery({ queryKey: ['invoices', 'summary'], queryFn: fetchSummary })
useQuery({ queryKey: ['invoices', 'list'], queryFn: fetchInvoices })
useQuery({ queryKey: ['invoices', 'detail', id], queryFn: () => fetchInvoice(id) })

Then after any mutation that touches invoice data:

queryClient.invalidateQueries({ queryKey: ['invoices'] })

This forces every query under the ['invoices'] prefix to refetch at the same time, so they stay consistent.

If you're polling instead of doing mutation-based invalidation, set the same refetchInterval on each query. They'll drift slightly based on mount time but it keeps them close enough for most cases.