[abedell-phantom]

Why

Tapping into a screen should start its data request at the tap, and live data shouldn't do redundant work. Three gaps stood in the way:

• Zero-delay refetches waited a setTimeout(0), up to a frame on React Native.
• There was no way to start a query at tap time and keep it alive until the screen mounts. watchOnce released it as soon as the response arrived, so the screen's mount had to reactivate it.
• A request started at tap time only went out after React's queued render.

What changed

• queryClient.prefetch(QueryClass, params, { ttl }): starts the query now and keeps it active for ttl ms (default DEFAULT_PREFETCH_TTL, 10 s) or until the returned release() is called.
• queryClient.retain(fn, { ttl }): keeps the queries fn reads or returns active until release(), or for ttl ms. It follows Signal params.
• Both send their first request before returning, ahead of a render already queued on the microtask queue. A query that depends on another's result starts when that result arrives.
• A reader that mounts while a lease is held joins the running query: no second request, and the data on its first render if it has arrived.
• destroy() releases outstanding leases and clears their timers.
• useSuspenseQuery in fetchium/react: suspends only on a cold miss (no value in memory or in a sync store), never for a refetch. A failed cold fetch is thrown to the error boundary, and resetting the boundary retries it.
• Refetches with no debounce (a stale query reactivating, a Signal param change) start on a microtask. Invalidation still waits a task, so a query whose last reader left in the same task is deactivated instead of refetched.
• Adds a shouldRetry(error, attempt, status) hook on QueryClientConfig and on RetryConfig (per query or mutation), so an app can stop retrying an error it knows is permanent, such as a 4xx. getErrorStatus is exported. Default retry behavior is unchanged: every failed attempt is retried.
• RetryConfig.retries is optional.
• A query whose first fetch was aborted (such as a prefetch released before its topic snapshot arrived) now loads when a reader mounts. The subscription is restored before the request is sent.
• Docs: useQuery never suspends and reading .value never throws. The error-handling guide shows how to throw to an error boundary.

Behavior changes / migration

• None for retries: shouldRetry is opt-in. When set, its status comes from the adapter's error response (ctx.response, set by RESTQueryAdapter) or from status, statusCode or response.status on the thrown error.
• prefetch's ttl is an upper bound. When it runs out, the lease is released even with a fetch in flight, and that fetch is aborted unless a reader has joined it.
• Zero-delay refetches start a macrotask earlier. Tests that wait on a timer before checking isPending may need updating.

Known limitations

• Call retain() and prefetch() from an event handler or effect. Called inside a reactive computation, they warn in development, start fetches on the usual microtask, and keep only the latest run's leases.
• That reactive-caller check reads a Signalium internal. If the internal changes, the check turns off.
• useSuspenseQuery can't run inside a Signalium component(). Use fetchQuery there.
• Changing useSuspenseQuery params to ones with no value suspends again. Wrap the change in startTransition to keep showing the previous result.

Impact

In a production React Native wallet app, this stack together with #67 and #61 is part of the build that took token-detail open from about 1.5 to 2.2 s down to about 770 ms.

Testing

• New retain-prefetch.test.ts: request timing, joining readers, params, sync store hits, ttl expiry mid-fetch, release(), destroy(), chained leases, Signal params, calls from a reactive computation.
• New retry-should-retry.test.ts: the default retries every status, status read from the response or the error (and not carried over to a later network error), fetchNext, client and query shouldRetry, mutations.
• New read-path-latency.test.ts: cold miss, cache hit, stale and staggered reactivation and Signal param changes start without a macrotask.
• New identical-redelivery.test.ts and react/identical-redelivery-react.test.tsx: unchanged data re-delivered through query results, mutations, topic events and nested entities notifies nothing and re-renders nothing.
• New react/prefetch-suspense.test.tsx: prefetch before mount, and useSuspenseQuery cold misses, refetches, sync store hits, errors, boundary resets, abandoned trees.
• Additions to live-value.test.ts (a reducer that mutates in place still notifies) and topic-query.test.ts (reactivating a topic query that never loaded).

Stack: #67 → #64 → #61 → #69 → #70 → #71 (this).

🤖 Generated with Claude Code