Reactive queries
@hedystia/query combines shared query caching with View resources and actions. It depends only on Hedystia View and adds no third-party runtime dependencies.
npm install @hedystia/queryUse a typed Hedystia client
import { createClient } from "@hedystia/client";
import { createQueryClient } from "@hedystia/query";
import { sig, val } from "@hedystia/view";
import type { app } from "./server";
const api = createClient<typeof app>("https://api.example.com");
const queries = createQueryClient();
const userId = sig(1);
const user = queries.query(
() => ["users", val(userId)] as const,
async (key, signal) => {
const result = await api.users.id(key[1]).get({ signal });
if (!result.ok) throw result.error;
return result.data;
},
);The route shape comes from your server. Query does not generate routes or add a second HTTP transport. Forward the supplied signal to the existing client, check ok, and throw on failure. This keeps transport and HTTP errors out of successful cached results.
Create queries inside a View component or createRoot. Read user() or user.data() for the current value, user.loading() for pending work, user.error() for errors, and user.ready for a successful resolution. Resources reuse View's loading and cancellation lifecycle.
Share requests safely
Two consumers of the same key share an in-flight fetch. Changing a key or disposing a component releases only its own consumer. The shared AbortSignal is cancelled when the final consumer leaves. If an old fetcher ignores cancellation, its late result cannot overwrite a newer cache entry.
Each key identifies one consistent result type and fetcher contract. The first active fetcher supplies the shared request. Create separate query clients for separate sessions or server-rendered requests; a shared global cache could expose one user's cached result to another user.
Invalidate after mutations
const saveUser = queries.mutation(
async (name: string) => {
const result = await api.users.id(1).patch({ body: { name } });
if (!result.ok) throw result.error;
return result.data;
},
{ invalidate: [["users"]] },
);
await saveUser.run("Alice");Only a successful mutation invalidates its configured prefixes. Mounted matching resources refetch; inactive values become stale until requested again. You can also call queries.invalidate(["users", 1]) or queries.invalidate() to invalidate all keys. Matching compares key parts structurally, so ["user"] does not accidentally match ["users"].
Mutations reuse View's action API, including direct calls and .run(). Loading stays true while any concurrent call is pending. The latest-started call determines the exposed data or error, and every caller still receives its own result or rejection.
Fetch outside components
const controller = new AbortController();
const result = await queries.fetchQuery(
["health"],
async (signal) => {
const response = await fetch("/health", { signal });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return response.text();
},
controller.signal,
);Use fetchQuery for imperative work that does not have a View owner. Its optional third argument cancels that caller independently.
Keys, freshness and retention
Keys must be arrays of finite, acyclic JSON values. Plain-object property order is canonicalized. Undefined values, sparse arrays, symbols, functions, BigInts, Date objects and other class instances are rejected. Shared acyclic subobjects are supported.
Successful results, including undefined, stay fresh until invalidated or evicted. There are no automatic retries, freshness timers, polling, persistence or telemetry. Values are shared by reference within one client.
Unused entries are evicted in access order once the cache exceeds 128 entries. Mounted resources and active requests remain available until their consumers release them; their presence can temporarily exceed that bound.
