Caching

Cache entry lifecycle

Every query result is stored as a cache entry keyed by METHOD:path:params. An entry moves through these states:

idle → loading → success → (stale after staleTime) → evicted after cacheTime
                    └→ error → retried or evicted after errorCacheTime

State	Description
`idle`	No fetch has been attempted yet
`loading`	A fetch is in progress
`success`	Data is available; may be fresh or stale
`error`	The last fetch failed

staleTime and cacheTime

These two values control the freshness lifecycle:

const kweri = new Kweri({
  staleTime: 30_000,   // data is fresh for 30 seconds after last fetch
  cacheTime: 300_000,  // keep the entry in memory for 5 minutes after going stale
})

staleTime — “when do I refetch?” How long data stays fresh. While fresh, kweri.query() returns the cached data without hitting the network. Once stale, the next access refetches in the background. Default: 0 (immediately stale).
cacheTime — “when do I forget?” How long an entry with no active observers is kept in memory before it can be garbage-collected. Default: 5 minutes.

They are independent: staleTime governs freshness (refetching), cacheTime governs retention (memory). An entry can be stale but still cached — it’s kept around and refetched on next access. Normally cacheTime ≥ staleTime.

	`staleTime`	`cacheTime`
Question	When do I refetch?	When do I forget?
Applies while	data exists	no observers are mounted
Expired ⇒	background refetch on next access	entry eligible for garbage collection

Per-query overrides

Freshness is really a property of the data, not the instance — a profile and a stock price want very different staleTimes. Override per call, taking precedence over the instance defaults:

// Direct
await kweri.query(getStock, { path: { id } }, { staleTime: 1_000 })
await kweri.query(getProfile, {}, { staleTime: 5 * 60_000, cacheTime: 30 * 60_000 })

// Via hooks — the third options arg accepts staleTime / cacheTime / maxRetries
const stock = useGet('/stocks/{id}', { path: { id } }, { staleTime: 1_000 })
const profile = useGet('/me', {}, { staleTime: 5 * 60_000 })

Overrides are stamped onto the cache entry when it’s (re)fetched, so they take effect from that write forward.

Stale-while-revalidate

When a query is called for data that exists in cache but is stale:

The cached data is returned immediately (no loading state)
A background network request is fired to refresh it
Subscribers are notified when the fresh data arrives

This means your UI never blocks on network latency for data you’ve already seen.

Cache structure

Each entry stores:

interface CacheEntry<T = unknown> {
  data: T | undefined
  status: 'idle' | 'loading' | 'success' | 'error'
  error: CachedError | undefined

  updatedAt: number       // timestamp when data was last set
  staleTime: number       // copied from KweriOptions at fetch time
  cacheTime: number       // copied from KweriOptions at fetch time

  errorUpdatedAt: number  // timestamp when error was last set
  errorCacheTime: number  // how long to keep the error (default: 5s)
  retryCount: number
}

isFresh

Data is considered fresh when:

updatedAt !== 0  AND  now < updatedAt + staleTime

If staleTime is 0 (the default), data is always stale and a background refetch will always fire when the query is called.

Invalidation

Invalidation marks an entry as stale without removing it. The cached data is still returned immediately; a refetch fires in the background.

// Invalidate a specific query
kweri.invalidateQuery(getUsers, {})

// Invalidate all queries whose cache key contains '/users'
kweri.invalidateByPath('/users')

// Invalidate with a regex
kweri.invalidateByPath(/\/users\/\d+/)

invalidateByPath is the most common pattern after a mutation — it catches all variants (e.g., /users, /users/1, /users?page=2) without you needing to enumerate every param combination.

Cache removal

Removal deletes the entry from memory entirely. The next query call starts from scratch.

kweri.removeQuery(getUsers, {})

Direct cache manipulation

You can read and write the cache directly without going through the network — useful for optimistic updates:

// Read cached data
const users = kweri.getCachedData(getUsers, {})

// Write data directly into cache
kweri.setCachedData(getUsers, {}, [...users, newUser])

Data written with setCachedData bypasses schema validation. It is marked as a success entry with updatedAt set to now, so it will remain fresh for staleTime milliseconds.

Error caching

Errors are also cached, but with a much shorter lifetime (default: 5 seconds). This prevents retry storms while still allowing the UI to recover quickly. When an error entry expires, the next call to kweri.query() will attempt a fresh fetch.

Getting Started

Core Concepts

Core API

Framework Adapters

CLI

Guides

Advanced

API Reference

Cache entry lifecycle

staleTime and cacheTime

Per-query overrides

Stale-while-revalidate

Cache structure

isFresh

Invalidation

Cache removal

Direct cache manipulation

Error caching

​Cache entry lifecycle

​staleTime and cacheTime

​Per-query overrides

​Stale-while-revalidate

​Cache structure

​isFresh

​Invalidation

​Cache removal

​Direct cache manipulation

​Error caching

Cache entry lifecycle

staleTime and cacheTime

Per-query overrides

Stale-while-revalidate

Cache structure

isFresh

Invalidation

Cache removal

Direct cache manipulation

Error caching