Designing Keys
A profile page and an editing form can share a value only if they agree on its identity. A key is that identity: an exact string used for cached results, pending requests, mutation queues, and subscriptions within a query instance.
Start with URLs when your application fetches JSON over HTTP. Use a key-building function when callers need filters or identifiers; this prevents one screen from silently using another screen’s data.
Include everything that changes the result
Section titled “Include everything that changes the result”Query compares strings, not request meaning. It does not normalize URLs, sort parameters, inspect credentials, or add a namespace for a fetcher. /api/profiles/1 and /api/profiles/1/ are different keys. Two fetchers using the same key are not separate resources.
For a list filtered by role and page, build the key in one place:
/** Produces one canonical URL for each profile-list representation. */export function profilesKey(role: string, page: number): string { const search = new URLSearchParams({ role, page: String(page) }) return `/api/profiles?${search}`}Every consumer calling profilesKey('editor', 1) now requests the same key. A different page or role produces a different entry. Encode path segments with encodeURIComponent when they come from user input, and validate values such as page numbers at your application’s boundary.
If language, tenant, account, or permissions change the response, reflect that distinction in the key or give that scope its own query instance. A URL containing only /api/me does not change when credentials change. Reusing its old cache after sign-out can show another account’s data. Prefer a new instance when the authenticated scope changes, and stop displaying the old tree before introducing the new one.
Do not put bearer tokens or other secrets in keys. Keys can appear in diagnostics, event names, and broadcast messages. A non-secret identifier can separate entries, but it does not authorize access to the underlying data.
Keep the fetcher consistent with the key
Section titled “Keep the fetcher consistent with the key”The default fetcher passes the key unchanged to fetch. If you use a non-URL key, supply a fetcher that understands it. This complete configuration maps one logical key to a real URL:
import { createQuery } from '@studiolambda/query'
/** A logical-key client whose transport still requests the local JSON file. */const query = createQuery({ fetcher: async (key, { signal }) => { if (key !== 'profile:current') throw new Error('unknown profile key') const response = await fetch('/profile.json', { signal }) if (!response.ok) throw new Error(`profile request failed: ${response.status}`) return response.json() },})Use query.query('profile:current') with this instance, not with an unrelated default client. The /profile.json file is the one created in Getting Started. Unknown keys reject rather than being interpreted as arbitrary URLs.
Same-key callers share the first eligible pending request. A later caller cannot replace that request’s fetcher, expiration policy, or error-removal policy by passing different options. Use one agreed policy per key. If you need a genuinely different representation, use another key; if you need a replacement request, use fresh reads.
Plan invalidation alongside identity
Section titled “Plan invalidation alongside identity”A consistent prefix makes a group of entries easy to remove. For example, keys under /api/profiles/ can be selected with an anchored regular expression:
await query.forget(/^\/api\/profiles\//)Here query is your application’s shared instance. The pattern matches stored keys and selected fresh resources, not a dependency graph. It does not match /api/profiles?role=editor, and invalidating one profile does not automatically invalidate profile lists. Remove or update each affected representation deliberately; see cache management.
There are no array keys, automatic hashing, query-key factories, or entity normalization in the public API. Your string convention is the contract between the application’s readers and writers.