Cache

interface CacheEntry<T = unknown> {
  data:           T | undefined
  status:         CacheEntryStatus
  error:          CachedError | undefined

  updatedAt:      number   // ms timestamp when data was last set (0 = never)
  staleTime:      number   // copied from KweriOptions at fetch time
  cacheTime:      number   // copied from KweriOptions at fetch time

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

type CacheEntryStatus = 'idle' | 'loading' | 'success' | 'error'

interface CachedError {
  message:   string
  type:      'network' | 'validation' | 'server' | 'unknown'
  status?:   number   // HTTP status code, if available
  retryable: boolean
}

function createCacheEntry(options?: {
  data?:          unknown
  status?:        CacheEntryStatus
  error?:         CachedError
  staleTime?:     number   // default: 0
  cacheTime?:     number   // default: 300_000
  errorCacheTime?: number  // default: 5_000
}): CacheEntry

function isFresh(entry: CacheEntry, now?: number): boolean

entry.updatedAt !== 0  AND  now < entry.updatedAt + entry.staleTime

function isErrorExpired(entry: CacheEntry, now?: number): boolean

entry.error == null  OR  now >= entry.errorUpdatedAt + entry.errorCacheTime

function categorizeError(error: unknown): CachedError

// ValidationError → { type: 'validation', retryable: false }
// HTTP 4xx        → { type: 'validation', retryable: false, status: 4xx }
// HTTP 5xx        → { type: 'server',     retryable: true,  status: 5xx }
// TypeError /
// network failure → { type: 'network',    retryable: true }
// unknown         → { type: 'unknown',    retryable: true }