Getting Started
When two parts of an application need the same data, they should not have to coordinate duplicate requests themselves. Query gives them a shared query instance: an object that loads values, remembers results under string keys, and notifies subscribers when those values change.
This walkthrough builds a browser page with a profile and a refresh button. You provide the JSON file yourself, so no API account or external service is required. The core package does not require React; React integration adds rendering and subscriptions later.
Create the application
Section titled “Create the application”Use a current Node.js LTS release supported by Vite, npm, and a modern browser. Query itself declares Node.js 18 or newer; the application tooling can require a newer version.
Run these commands in a directory where you keep applications:
npm create vite@latest query-demo -- --template vanilla-tscd query-demonpm installnpm install @studiolambda/queryVite creates the application files, including index.html and src/main.ts. Keep its generated configuration. Create public/profile.json with this content:
{ "id": 1, "name": "Ada", "role": "Editor"}Vite serves this file at /profile.json. That URL will also be the key, the string Query uses to identify a cached value. With the default fetcher, keys are URLs and successful responses are parsed as JSON.
Load and display a profile
Section titled “Load and display a profile”Replace src/main.ts with the following file. The query instance lives outside the rendering function so all reads share its cache.
import { createQuery } from '@studiolambda/query'
/** The shape of the JSON file served by this application. */interface Profile { readonly id: number readonly name: string readonly role: string}
/** Shared data owner for this browser application. */const query = createQuery()/** Text output uses textContent so names are not interpreted as HTML. */const output = document.createElement('p')/** Explicit refresh control for the same profile key. */const button = document.createElement('button')button.textContent = 'Refresh profile'document.body.replaceChildren(output, button)
/** Loads the profile and reports failures without losing the page controls. */async function showProfile(isFresh = false): Promise<void> { button.disabled = true output.textContent = 'Loading profile…' try { const profile = await query.query<Profile>('/profile.json', { fresh: isFresh }) output.textContent = `${profile.name} — ${profile.role}` } catch (error) { output.textContent = error instanceof Error ? error.message : 'Profile unavailable' } finally { button.disabled = false }}
button.addEventListener('click', () => { void showProfile(true)})void showProfile()The first read fetches the file and stores the result. The refresh button uses fresh: true to bypass Query’s cached value. This still uses the browser’s normal HTTP cache policy; it does not mean “disable the HTTP cache.” The generic Profile describes the expected shape to TypeScript, but does not validate the JSON at runtime.
Check the result
Section titled “Check the result”Start Vite from query-demo:
npm run dev -- --port 5173 --strictPortOpen the local application. The page displays Ada — Editor and a Refresh profile button. If you change the role in public/profile.json to Reviewer, clicking the button displays Ada — Reviewer. If port 5173 is occupied, stop the other server or choose another port in the command and URL.
To see request sharing directly, add this block immediately before void showProfile() in src/main.ts, then reload:
/** Two consumers select the same pending request. */const first = query.query<Profile>('/profile.json')/** Ordinary same-key reads reuse the selected promise. */const second = query.query<Profile>('/profile.json')console.log('Shared request:', first === second)void Promise.all([first, second]).catch(console.error)The console prints Shared request: true. The subsequent showProfile() joins the same work. This is deduplication: eligible reads of the same key share a request rather than calling the fetcher again.
Understand what happens next
Section titled “Understand what happens next”Fetched results are considered valid for 2,000 milliseconds by default. After that deadline, a new read returns the old value while starting a background request. Expiration alone does not start a request and does not delete the value. An imperative caller must subscribe to events if it wants to react to the background result; React’s data hooks do this for you.
The example catches its awaited request failures. A failed background request instead reports through the error event while the stale read can still succeed. Read data fetching before choosing where an application may use older data.
Stop Vite with Ctrl+C when finished. This example creates no subscriptions, channels, or persistent storage to dispose. Next, design keys that keep distinct data separate, or build the React version.