Proposal: add an explicit infinite query refetch mode that preserves cached pages

Summary

RTK Query infinite queries currently support two refetch behaviors via refetchCachedPages:

• refetchCachedPages: true or omitted: refetch all cached pages.
• refetchCachedPages: false: refetch the first cached page only, and shrink the cache from N pages to 1 page.

I’d like to propose an explicit third mode:

• refetch the first page, and preserve cached pages 2..N.

In other words, after a refetch with cached pages [page1, page2, page3], RTK Query would fetch a fresh page1, then keep the existing page2 and page3 in the cache.

Use case

This is useful for activity-feed style UIs: inboxes, timelines, notifications, chat/thread lists, social feeds, etc.

In those UIs, polling or pull-to-refresh usually only needs to refresh the top of the list. Refetching every cached page can become very expensive if the user has scrolled through many pages. At the same time, shrinking the cache to only page 1 can make the list collapse or lose already loaded content.

For feeds sorted by recency/activity, an updated item is usually expected to reappear near the top. If the UI deduplicates the flattened page data before rendering, preserving older cached pages is often the desired tradeoff:

• page 1 is fresh
• pages 2..N are preserved and may be stale
• the UI does not collapse during polling/refetch
• network cost stays O(1) instead of O(number of cached pages)

Proposed API

One possible API would be to introduce a new explicit mode option while keeping refetchCachedPages fully backwards compatible:

type InfiniteQueryRefetchBehavior =
  | 'refetch-all-pages'
  | 'refetch-first-page-discard-rest'
  | 'refetch-first-page-preserve-rest'

Example:

infiniteQueryOptions: {
  initialPageParam: undefined,
  refetchBehavior: 'refetch-first-page-preserve-rest',
  getNextPageParam: ...
}

Backward compatibility mapping:

refetchCachedPages: true
// equivalent to refetchBehavior: 'refetch-all-pages'

refetchCachedPages: false
// equivalent to refetchBehavior: 'refetch-first-page-discard-rest'

The three behaviors would then be:

1. refetch-first-page-preserve-rest

   • refetch page 1
   • explicitly keep cached pages 2..N
   • keep the existing page params for those preserved pages

2. refetch-all-pages

   • current default behavior
   • refetch every cached page sequentially

3. refetch-first-page-discard-rest

   • current refetchCachedPages: false behavior
   • refetch page 1
   • discard the other cached pages, shrinking the cache to one page

I’m not attached to the exact option name. Another smaller API would be:

refetchCachedPages: true | false | 'preserve'

but a dedicated refetchBehavior / mode option may be clearer and avoids overloading a boolean option further.

Footgun / tradeoff

This can absolutely be a footgun if used for the wrong kind of pagination.

Preserving pages 2..N after refetching page 1 can create stale page boundaries, duplicated records, missing records, or stale cursors if the backend pagination requires every page to be refetched for consistency.

So I think this should be an explicit opt-in mode, documented as appropriate for feed-like UIs where:

• the first page contains the freshest items
• updated items are expected to bubble toward the top
• preserving older cached pages is acceptable
• the rendered flattened list is deduplicated by item id

It should not replace the current default behavior.

Related discussions / prior work

This builds on the same problem space as:

• #5011: “Add infinite query option to not fetch all pages when refetching”
  • This describes the feed / pull-to-refresh problem where refetching many cached pages is unnecessarily expensive.
• #5016: “Add refetchCachedPages option for infinite query”
  • This added the current refetchCachedPages option.
• #4920: “Infinite query always refetch all pages”
  • This discussion explicitly distinguished between “reload only the first page and keep the other pages” vs “remove all pages and go back to page 1”.
• #5143: v2.11.0 release discussion
  • Documents that refetchCachedPages: false currently shrinks the cache from N pages to 1 page.
• #3174: RTKQ infinite query use cases and concerns
  • Includes the consistency concerns around only refetching part of an infinite query.
• #4801: Infinite queries and refetching pages
  • Discusses the difficulty of page-level refetch/invalidation and why partial page updates can be incorrect when backend ordering changes.

Willing to contribute

I have a local patch for this behavior and can open a PR with tests and docs if this API shape seems acceptable, or adjust the implementation to whatever API naming you prefer.