Skip to content

Data hooks

The React data layer with seeded queries, optimistic writes, a live room and lazy parts.

API

Functions

FunctionSignatureDoes
useSeededQuery<T, S extends T | undefined = undefined>(options: { queryKey: readonly unknown[]; queryFn: (context: { signal: AbortSignal; }) => Promise<T>; enabled?: boolean | undefined; }, seed?: S | undefined): SeededResult<...>A query that starts from its route loader's data (server-rendered, no loading flash) and then lives in the cache. A loader that runs again (a navigation, a search parameter) hands down a newer object, which replaces what the cache holds for the same key.
useWrite<V = void, R = unknown>(spec: WriteSpec<V, R>, words?: (error: unknown) => string | null): { run: (vars: V) => Promise<R | undefined>; fire: (vars: V) => void; pending: boolean; error: string | null; reset: () => void; }A write with optimistic cache patches that roll back on failure and a targeted read of only the keys it touched, so a save never reloads the page. words turns the failure into the line the reader sees.
useFlag(flag: Flag): boolean---- Answers as queries ------------------------------------------------------------------------- A page-wide flag as React state. False on the server, which renders only signed-in pages.
useAnswer<T>(key: readonly unknown[], read: () => Promise<Answer<T>>, { keep, staleTime, enabled, }?: { keep?: boolean | undefined; staleTime?: number | undefined; enabled?: boolean | undefined; }): Load<T> & { ...; }A route's Answer, cached under key. A new key keeps what is on screen and marks it loading (keep: false starts empty); a failed read keeps it too and says why; a SignedOut is not shown as an error (the client's onError sets the signed-out flag). reread reads it again now.
useLiveRoom(room: string | null, open: (room: string) => WebSocket, options: LiveRoomOptions): { connected: boolean; }A WebSocket that stays open: it reconnects after a drop with exponential backoff and jitter, at once when the network comes back, and closes on unmount or when room changes. room null opens nothing. open makes the socket (an app's own, which may add a session cookie).
sessionEnded(res: Response, forbidden?: boolean): booleanThe session ended: Access answers with a redirect to its login, or the Worker answers 401, or 403 when forbidden (an action endpoint answers 403 for a CSRF or cross-site refusal, with its text, so it passes false and shows that text). redirect: "manual" keeps a cross-origin login redirect from surfacing as an opaque network error.
answerOf<T>(res: Response, forbidden?: boolean): Promise<Answer<T>>A response as an Answer: 410 is expired (a preview token that lapsed); a non-JSON success is an error.
getAnswer<T>(url: string, { headers }?: { headers?: Record<string, string> | undefined; }): Promise<Answer<T>>GET a JSON route on this origin, never cached, as an Answer.
postAnswer<T>(url: string, body: unknown, { headers, timeoutMs, timeoutMessage, }?: { headers?: Record<string, string> | undefined; timeoutMs?: number | undefined; timeoutMessage?: ((seconds: number) => string) | undefined; }): Promise<...>POST JSON to a route on this origin as an Answer. A request with no answer within timeoutMs (20 s) is aborted and says so, so a dialog never stays busy with nothing said. A 403 is the server's refusal (CSRF, cross-site), not a sign-out.
ask<T>(read: () => Promise<Answer<T>>): Promise<T>An Answer's value, or a throw: SignedOut, or an Error carrying the server's text.
createFlag(initial?: boolean): Flag
reconnectDelay(attempt: number, { base, max, random, }?: { base?: number | undefined; max?: number | undefined; random?: (() => number) | undefined; }): numberHow long a live room waits before reconnecting after its attemptth drop: exponential from base (1 s) to max (30 s), with full jitter so a restart does not bring every tab back in the same second (AWS Architecture Blog, "Exponential Backoff And Jitter").
socketUrl(path: string, origin?: string): stringThe ws: or wss: address for a path on origin (this page's by default).
NO_ANSWER(seconds: number): stringThe words for a request that had no answer in time.