Browse documentation

QueryClient

Creates query and mutation handles over a shared cache with invalidation and persistence controls.

Table of contents

Category

Value

Import

js
import { QueryClient } from "valyrian.js/query";

Public signature

ts
new QueryClient(options?: QueryClientOptions): QueryClient

API form

QueryClient is a class. One client owns the cache and creates QueryHandle and MutationHandle instances.

Options and defaults

ts
type QueryClientOptions = {
  staleTime?: number; // 60000 ms
  cacheTime?: number; // 600000 ms
  persist?: boolean; // false
  persistId?: string; // "valyrian-query" when persistence is active
};

type QueryKey = Array<string | number | boolean | Record<string, unknown>>;
type QueryConfig<TData> = {
  key: QueryKey;
  fetcher: () => Promise<TData> | TData;
  staleTime?: number;
};
type MutationConfig<TPayload, TResult> = {
  execute: (payload: TPayload) => Promise<TResult> | TResult;
  onSuccess?: (result: TResult) => void;
  onError?: (error: unknown) => void;
};
type QueryState<TData> = {
  status: "idle" | "loading" | "success" | "error";
  loading: boolean;
  success: boolean;
  error: unknown;
  data: TData | null;
  updatedAt: number;
};
type QueryChangeEvent = {
  type: string;
  key?: QueryKey;
  payload?: unknown;
  state?: QueryState<unknown>;
};

Factories and cache methods

ts
query<TData>(config: QueryConfig<TData>): QueryHandle<TData>
mutation<TPayload, TResult>(config: MutationConfig<TPayload, TResult>): MutationHandle<TPayload, TResult>
invalidate(partialKey: QueryKey): void
clear(): void
on("change", callback: (event: QueryChangeEvent) => void): () => void
off("change", callback): void

Events and persistence

Change events include query:start, query:success, query:error, query:invalidate, mutation:start, mutation:success, mutation:error, cache:clear and gc. Persistence is opt-in and restores stored query state through native local storage.