[abedell-phantom]

Why

Returning to a screen reactivated all of its queries at once. Each one refetched if it was past staleTime, even when its data was seconds old or a live subscription had just updated it. All those refetches started in the same task, and poll() kept running while the app was in the background. In a large React Native app this made tab returns and app resumes bursty.

What changed

Every option here is opt-in. With defaults, behavior is unchanged.

• reactivationGraceMs on QueryClient, with a per-query override in the query config. A query that reactivates with data younger than the grace is not refetched.
• Data a subscription pushed to counts as fresh from the last push: a subscribe stream event, or a topic event sent with its topic.
• A poll() subscription counts only through the fetches it makes.
• Invalidation, markStale(), refetch(), network reconnects and a failed last fetch still refetch.
• TopicQueryAdapter.sendMutationEvent(event, topic?): pass the topic so that topic's query gets credit for the push.
• reactivationStaggerMs: reactivation refetches queued in the same task are spread evenly across the window, in activation order.
• A staggered refetch is skipped if another fetch started on that query while it waited.
• QueryAdapter.coalescesRequests: an adapter that sets it keeps its queries' reactivation refetches together, so they can share a request.
• activity: { isActive(), subscribe(listener) } on QueryClient: poll() stops while inactive and resumes when active. A tick not yet due keeps its original time.
• pollResumeJitterMs, with a per-poll poll({ interval, resumeJitterMs }) override: a tick overdue on resume, or one whose timer fired more than 1 s late, is rescheduled at a random point in the window.
• New exported type ActivitySource.

Behavior changes

None with default options.

Known limitations

• Fetchium can't observe foreground state itself. On React Native, wrap AppState in an ActivitySource.
• Topic queries get push credit only from adapters that pass the topic to sendMutationEvent. Otherwise the grace measures from the last fetch.
• With reactivationStaggerMs set, the stagger flush runs one task after reactivation.

Testing

• New reactivation-grace.test.ts: grace defaults and per-query override, invalidation, failed fetches, push credit for streams, polls and topics, reconnects, stagger order, coalescing adapters, skipped and cancelled staggered refetches.
• New poll-activity.test.ts: stop and resume, jitter, late ticks, listener cleanup.
• New react/pause-reactivation.test.tsx: resuming a paused screen with and without the grace.
• New topic-batch-delivery.test.ts: topic snapshots delivered in one task settle in one flush.

Changeset

minor: .changeset/quiet-reactivation.md, added during review so these options appear in the release notes.

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

🤖 Generated with Claude Code