QueryClient

The primary interface for interacting with SoulCache.

Import

import { QueryClient } from '@soulcache/core';

Constructor

new QueryClient(config?: QueryClientConfig)

Parameters

Parameter	Type	Default	Description
`config.defaultOptions.gcTime`	`number`	`1800000` (30 min)	Time before garbage collection
`config.logger`	`Logger`	`undefined`	Custom logger implementing `{ info, warn, error, debug }`

Note: config.defaultOptions.staleTime is accepted and stamped on cache entries but is not yet used for revalidation decisions in the current public runtime. It will drive stale-time refetching in a future milestone.

Properties

Property	Type	Description
`isDestroyed`	`boolean`	Whether client is destroyed
`queryCount`	`number`	Number of active queries

Methods

`fetchQuery<T>(options)`

Fetch data with automatic caching and deduplication.

fetchQuery<T>(options: {
  queryKey: QueryKey;
  queryFn: () => Promise<T>;
}): Promise<T>

`getQueryData<T>(queryKey)`

Read cached data.

getQueryData<T>(queryKey: QueryKey): T | undefined

`getQuerySnapshot<T>(queryKey)`

Get the current snapshot for a query (compatible with useSyncExternalStore).

getQuerySnapshot<T>(queryKey: QueryKey): QuerySnapshot<T> | undefined

`setQueryData<T>(queryKey, updater)`

Manually update cache.

setQueryData<T>(queryKey: QueryKey, updater: Updater<T>): void

`subscribe<T>(queryKey, callback)`

Subscribe to query updates. Returns an unsubscribe function.

subscribe<T>(queryKey: QueryKey, callback: (snapshot: QuerySnapshot<T>) => void): () => void

`subscribeToQuery(queryKey, listener)`

Subscribe to query state changes. Compatible with useSyncExternalStore.

subscribeToQuery(queryKey: QueryKey, listener: () => void): () => void

`mutate<TData, TVariables>(options)`

Execute a mutation.

mutate<TData, TVariables = void>(options: {
  mutationId?: string;
  mutationFn: (variables: TVariables) => Promise<TData>;
  variables: TVariables;
  onMutate?: (variables: TVariables) => unknown;
  onSuccess?: (data: TData, variables: TVariables) => void;
  onError?: (error: Error, variables: TVariables) => void;
  onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
  retry?: number;
  retryDelay?: number;
}): Promise<TData>

Note: retry and retryDelay are accepted and forwarded to MutationCache.create(), but mutate() performs a single attempt. Use MutationEntry.mutateWithRetry() for retrying mutations.

`invalidateQueries(queryKey)`

Invalidate cache entries by prefix.

invalidateQueries(queryKey: QueryKey): Promise<void>

`removeQuery(queryKey)`

Remove a query entry.

removeQuery(queryKey: QueryKey): void

`clear()`

Clear all cache entries.

clear(): void

`destroy()`

Destroy client and cleanup resources.

destroy(): void

`getCache()`

Access the underlying CacheEngine instance.

getCache(): CacheEngine

`getMutationCache()`

Access the underlying MutationCache instance.

getMutationCache(): MutationCache

`getScheduler()`

Access the underlying Scheduler instance.

getScheduler(): Scheduler

QueryClient

On this page