Browse documentation

QueryHandle

Exposes the public state and operations of a query.

Table of contents

Category

Value

Import

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

Public signature

ts
client.query<TData>(config: QueryConfig<TData>): QueryHandle<TData>

API form

QueryHandle is a class instance returned by QueryClient.query(...). Application code obtains it from the client instead of calling its infrastructure constructor.

Configuration

ts
type QueryKey = Array<string | number | boolean | Record<string, unknown>>;

type QueryConfig<TData> = {
  key: QueryKey;
  fetcher: () => Promise<TData> | TData;
  staleTime?: number;
};

Properties and methods

ts
type QueryState<TData> = {
  status: "idle" | "loading" | "success" | "error";
  loading: boolean;
  success: boolean;
  error: unknown;
  data: TData | null;
  updatedAt: number;
};

readonly key: QueryKey
readonly state: QueryState<TData>
readonly data: TData | null
fetch(): Promise<TData | null>
invalidate(): void

Fetch behavior

fetch() returns fresh successful data, deduplicates an active request for the same key and invokes the fetcher when data is stale. invalidate() marks this query stale so its next fetch loads again.