Concept of Stale, Revalidate, & Invalidate

Understanding these concepts is key to how FloppyDisk manages async state efficiently and predictably.

Stale vs Fresh

Every query can be either:

This is controlled by staleTime (default: 2.5 seconds).

The timer starts right after the promise resolves.

Let's say a query with { staleTime: 2500 }.
Timeline simulation:

Stale time starts after data is available, not when the request begins. This ensures freshness is based on actual data age, not network duration.

Mental Model

execute() means:
Always run the promise, no matter what.

💡 In TanStack Query terms, execute is equivalent to fetch.

revalidate() is conditional:

Revalidation respects freshness.

💡 In TanStack Query terms, revalidate is equivalent to refetch.

invalidate() marks a query as invalid, even if it's still fresh.

Then:

If the query is subscribed → automatically execute
If the query is unsubscribed → stop here → wait until it becomes subscribed, then execute

This ensures:

💡 In TanStack Query terms, invalidate is equivalent to invalidateQueries.

Based on total subscribers, a query can be classified into two conditions:

This distinction is important because it determines whether a query should actively update or stay idle.

If a query is used by a currently rendered component, it becomes subscribed, because the component internally subscribes to the query store.

Command	Fresh/Stale	Subscribed	Query function called?
`execute()`	Any	Any	✅ Called
`revalidate()`	Fresh	Any	❌ Not called
`revalidate()`	Stale	Any	✅ Called
`invalidate()`	Any	Yes	✅ Called immediately
`invalidate()`	Any	No	⏳ Deferred → Called when the query becomes subscribed