Skip to content

Configuration

When most screens use the same transport and freshness policy, configure that policy once rather than repeating it at every read. createQuery() creates an isolated data owner with its own result cache, pending requests, mutation queues, render resources, and event target.

Keep the instance stable for the application’s intended lifetime. Use a separate instance per authenticated browser scope and per server request; server rendering and isolation explains why.

Install the released package with npm install @studiolambda/query. The package publishes ESM and CommonJS entry points:

Entry pointSupported use
@studiolambda/queryFramework-independent core and exported TypeScript contracts
@studiolambda/query/reactReact 19.2+ hooks, providers, transitions, and prefetch components

Core declares Node.js 18 or newer and also runs in modern browsers. It uses the platform AbortController, EventTarget, CustomEvent, promises, and queueMicrotask. The default JSON transport also requires global fetch; a supplied custom fetcher can use another transport. Check the actual runtime, not only the Node version: some older Node runtimes lack a global CustomEvent. Use a newer runtime or install the required platform polyfill before creating the client. BroadcastChannel is optional and is not constructed by core or React.

React and React DOM are optional peers for core consumers; the React bindings need compatible React 19.2+ installations because they use use and useEffectEvent. A consuming application does not have to enable React Compiler to use the bindings. Do not rely on compiler optimization to stabilize an instance created during your own render.

There is no @studiolambda/query/solid export in the released package contract. The unfinished Solid source contains a context/provider but no data-reading hook; it is not a React-equivalent integration. Use the framework-independent core with your application’s own Solid lifecycle/subscription wiring instead of importing an invented subpath. This guide does not recommend source-only internals as a consumer API.

For JSON URL keys and a longer freshness window:

import { createQuery } from '@studiolambda/query'
/** Application-scoped defaults; individual reads can override these. */
export const query = createQuery({
expiration: () => 30_000,
stale: true,
removeOnError: false,
fresh: false,
})

The options below are available both in Configuration at creation and in Options<T> on individual reads. An omitted or undefined per-read option uses the instance default. Explicit false is an override, not an omission.

OptionInitial defaultMeaning
fetcherdefaultFetcher(fetch)Exact key and { signal } to a promise for data
expiration() => 2000Fetched-value lifetime in milliseconds, starting at commit
staletrueReturn expired data while revalidating
removeOnErrorfalseDelete cached item when its owning fetch fails
freshfalseImperatively abort and replace same-key work, bypassing cached data

expiration is a function, not a number. Its argument is the fetched value, so a per-read Options<Profile> can use validated response fields to choose a duration. A cache hit does not rerun the callback. Hydration and mutation use their own HydrateOptions<T> and MutateOptions<T>; both default to zero milliseconds regardless of instance defaults.

Read fetching and freshness for the selection order. The first eligible pending request owns its options; later same-key readers do not change an already-running request.

To change defaults for future selections, use the same instance’s configure() method:

query.configure({ expiration: () => 5000, stale: false })

Unspecified or nullish settings retain their previous values. configure() does not reset the instance, recalculate existing expiration dates, migrate entries, or cancel active transports. configure({ fresh: false }) turns off that default; configure({ broadcast: undefined }) does not remove an existing channel.

Supplying any request/cache property invalidates selected fresh render resources, even when that property’s value is undefined. Changing only events or broadcast preserves those selections. Existing subscriptions are not migrated when you replace an event target or channel. Dispose them before reconfiguration and subscribe again afterward; React providers subscribe by query identity, so mutating the channel on a still-mounted identical instance does not reconnect their effect.

Prefer replacing the whole instance at a user/session boundary instead of reconfiguring a live authenticated client.

Configuration also accepts itemsCache, resolversCache, events, and broadcast. Each is retained by reference. Core creates new Map caches and an EventTarget if you omit them; there is no default channel.

An existing synchronous store can satisfy Cache<T> with get, set, delete, and keys. A Map already does so:

import { createQuery, type ItemsCacheItem, type ResolversCacheItem } from '@studiolambda/query'
/** Result promises and their absolute freshness deadlines. */
const itemsCache = new Map<string, ItemsCacheItem>()
/** Pending promises and their cancellation/ownership controllers. */
const resolversCache = new Map<string, ResolversCacheItem>()
/** A client using explicit application-owned stores. */
const query = createQuery({ itemsCache, resolversCache, events: new EventTarget() })

Sharing result storage shares data, not the two instances’ subscriptions. Sharing resolver storage also shares request ownership and deduplication, while mutation queues and render selections still belong to each instance. Prefer sharing one query instance rather than composing partially shared clients.

These stores contain promises, dates, and controllers, not a JSON persistence format. Async database or localStorage operations do not directly satisfy the synchronous contract. Use public cache methods for writes; direct store edits bypass events and ownership protection. For optional browser communication and caller-owned channel cleanup, follow cross-tab events.