@bgub/fig-convex

Experimental native Fig queries over Convex's framework-independent clients. Fig owns cached values and Suspense; mounted readers own shared live subscriptions. There is no React runtime or second query cache.

Create createConvexBrowserQueries({ data, client, scope }) from /client, or createConvexServerQueries({ data, client, scope }) from /server. The server factory uses the HTTP client's consistent queries. Create a fresh authenticated HTTP client and Fig store for each request. The caller owns authentication and closing the browser client. scope must be the same non-secret session identity on server and browser, or a fixed public scope for anonymous data.

Call queries.query(api.episodes.get, { id }) to obtain a typed, shared handle. In the loader, await handle.prefetchQuery() for critical data; start secondary prefetches without returning their promises. In the component, call useSuspenseQuery(handle) from /query inside a nearby Suspense/error boundary. The returned { data } retains the generated Convex function's return type.

handle.retry() invalidates the stored error/value before remounting an error boundary. queries.dispose() retires subscriptions and pending initial reads. It does not purge fulfilled Fig data. For TinyLingo, preserve the existing full-document reload after sign-out; retire queries before changing identity. Do not reuse a disposed session's registry or Fig store for a different user.

The public factories accept existing Convex clients. Call their native mutation and action methods with Fig action state; actions are not cached queries.

Build with pnpm --filter @bgub/fig-convex build. Package exports contain compiled ESM and declaration files. Tests cover hydration, committed-reader ownership, shared descriptors, errors/retry, request identity, and late callback retirement. TinyLingo uses these adapters across its migrated web routes. App-level tests cover hydration, auth transitions and mutation invalidation with controlled transports. Real signed-in deployment and reconnect checks remain release gates.

The app runtime's queryClient.invalidate(query?) accepts a typed Convex query reference. It refreshes all cached argument variants of that query; omit the reference to refresh all registered queries. convexQuery(query, args) describes a resource for fetching and prefetching and does not expose compatibility keys.

queryClient.setQueryData(convexQuery(query, args), value) seeds an authenticated resource from a mutation's authoritative response. Readers can render immediately without another initial query; mounted readers still subscribe to live updates. The seed belongs to the current registry's session scope and cannot be written after disposal.

appData.fetchAccessToken(forceRefresh?) shares the browser client's token cache with authenticated media requests. It deduplicates renewal, refreshes JWTs near expiration, and returns null after session retirement. Keep media caches scoped to that app and clear them when identity changes; tokens are never cache keys.

useConvexMutation(reference, { optimisticUpdate }) accepts a typed Convex optimistic update. Change immutable query snapshots in its local store; Convex replays pending updates over fresh server data and removes them on success or failure. Live Fig readers receive these changes through the existing subscription. The HTTP/SSR client ignores the optimistic option. Keep permission changes server-authoritative; an optimistic result is never an access grant.

The returned runner also accepts per-call options: mutate(args, { optimisticUpdate }). Use these to capture a temporary creation ID once per submission, before Convex replays the update. Per-call options override the hook's defaults for that call.