Skip to main content

​
Constructor

new Kweri(options: KweriOptions, timer?: TimerAdapter)

​
KweriOptions

interface KweriOptions {
  // Required
  baseURL: string

  // Optional — HTTP
  fetcher?: Fetcher          // custom HTTP transport (default: global fetch)

  // Optional — caching
  staleTime?: number         // ms data is fresh (default: 0)
  cacheTime?: number         // ms to keep stale data in memory (default: 300_000)
  maxRetries?: number        // retries for network/server errors (default: 0)

  // Optional — garbage collection
  gcInterval?: number        // ms between GC sweeps (default: no GC)

  // Optional — persistence
  persistence?: PersistenceAdapter

  // Optional — devtools
  enableDevTools?: boolean
  devtools?: MountKweriDevToolsOptions
}

​
Example

import { Kweri } from 'kweri'

export const kweri = new Kweri({
  baseURL: 'https://api.example.com',
  staleTime: 30_000,
  cacheTime: 300_000,
  gcInterval: 60_000,
  maxRetries: 3,
  enableDevTools: true,
  devtools: { position: 'bottom-right' }
})

​
Querying

​
kweri.query

Execute a query. Returns cached data immediately if fresh; otherwise fetches and caches the result. 
async query<E extends Endpoint>(
  endpoint: E,
  params: InferParams<E>
): Promise<InferResponse<E>>
Concurrent calls for the same key share a single in-flight request. 
const users = await kweri.query(getUsers, {})
const user  = await kweri.query(getUserById, { path: { id: 1 } })

​
Mutations

​
kweri.mutate

Execute a mutation with full lifecycle hooks. 
async mutate<E extends Endpoint, TContext = unknown>(
  endpoint: E,
  params: InferParams<E>,
  options?: MutationOptions<...>
): Promise<InferResponse<E>>
See Mutations for the full options reference.

​
Cache access

​
kweri.getCachedData

Return the currently cached data for a query without triggering a fetch. 
getCachedData<E extends Endpoint>(
  endpoint: E,
  params: InferParams<E>
): InferResponse<E> | undefined

​
kweri.setCachedData

Write data directly into the cache. The entry is marked as success with updatedAt = now. 
setCachedData<E extends Endpoint>(
  endpoint: E,
  params: InferParams<E>,
  data: InferResponse<E>
): void
Useful for optimistic updates before a mutation fires.

​
Invalidation

​
kweri.invalidateQuery

Mark a specific cached entry as stale. Subscribers will receive a background refetch on their next render. 
invalidateQuery<E extends Endpoint>(endpoint: E, params: InferParams<E>): void

​
kweri.invalidateByPath

Mark all entries whose cache key contains the given string or matches the given regex as stale. 
invalidateByPath(pattern: string | RegExp): void

kweri.invalidateByPath('/users')         // matches /users, /users/1, /users?page=2
kweri.invalidateByPath(/\/users\/\d+/)   // matches /users/1, /users/42, etc.

​
kweri.invalidateQueryByKey

Invalidate by the raw serialized cache key — primarily used by DevTools. 
invalidateQueryByKey(key: string): void

​
Removal

​
kweri.removeQuery

Delete a cache entry entirely. 
removeQuery<E extends Endpoint>(endpoint: E, params: InferParams<E>): void

​
kweri.removeQueryByKey

Delete by raw key string. 
removeQueryByKey(key: string): void

​
Subscriptions

​
kweri.subscribe

Subscribe to cache changes for a specific query. Returns an unsubscribe function. 
subscribe<E extends Endpoint>(
  endpoint: E,
  params: InferParams<E>,
  callback: (entry: CacheEntry) => void
): () => void

const unsubscribe = kweri.subscribe(getUsers, {}, (entry) => {
  console.log(entry.status, entry.data)
})

// Later:
unsubscribe()

​
kweri.onCacheChange

Subscribe to all cache changes globally. Useful for logging or custom devtools. 
onCacheChange(callback: (key: string, entry: CacheEntry) => void): () => void

​
Status

​
kweri.isInFlight

Check whether a fetch is currently in progress for a given query. 
isInFlight<E extends Endpoint>(endpoint: E, params: InferParams<E>): boolean

​
kweri.getQueryKey

Get the serialized cache key for a query/params pair. 
getQueryKey<E extends Endpoint>(endpoint: E, params: InferParams<E>): string

​
Garbage collection

​
kweri.startGC / kweri.stopGC

Manually control the eviction engine. If gcInterval is set in KweriOptions, GC starts automatically on construction. 
kweri.startGC(60_000)  // sweep every 60 seconds
kweri.stopGC()

​
Devtools

​
kweri.getDevToolsSnapshot

Returns a point-in-time snapshot of the cache, observer counts, and in-flight requests. Used internally by the DevTools panel. 
getDevToolsSnapshot(): KweriDevToolsSnapshot

interface KweriDevToolsSnapshot {
  cache:     Array<{ key: string; entry: CacheEntry }>
  observers: Array<{ key: string; count: number }>
  inFlight:  string[]
}

​
Lifecycle

​
kweri.destroy

Stops the GC timer, unmounts DevTools, and clears all subscriptions. Call this when the application shuts down or when testing. 
kweri.destroy()

​
Public properties

readonly queryClient: QueryClient  // direct access to cache operations
readonly apiClient:   ApiClient    // direct access to HTTP execution