feat(useInfiniteQuery): new maxPages option (#4984)

* feat(useInfiniteQuery): new maxPages option

* fix: pnpm lock file

I had to create an .npmrc file with link-workspace-packages = false to generate a lock file consistent with the previous version

* chore(examples): remove unused about file

* test: check if the query has been fetched exactly twice

* refactor: use util functions addToEnd addToStart

* docs(example): rename example and update config.json

* docs(reference): maxPages

* docs(guide): infinite-queries: maxPages example

Author: arnaudbzn

docs/config.json

@@ -238,6 +238,10 @@
               "label": "Load-More & Infinite Scroll",
               "to": "react/examples/react/load-more-infinite-scroll"
             },
+            {
+              "label": "Infinite query with Max pages",
+              "to": "react/examples/react/infinite-query-with-max-pages"
+            },
             {
               "label": "Suspense",
               "to": "react/examples/react/suspense"

docs/react/guides/infinite-queries.md

@@ -231,3 +231,29 @@ queryClient.setQueryData(['projects'], (data) => ({
 [//]: # 'Example7'
 
 Make sure to keep the same data structure of pages and pageParams!
+
+[//]: # 'Example8'
+
+## What if I want to limit the number of pages?
+
+In some use cases you may want to limit the number of pages stored in the query data to improve the performance and UX:
+
+- when the user can load a large number of pages (memory usage)
+- when you have to refetch an infinite query that contains dozens of pages (network usage: all the pages are sequentially fetched)
+
+The solution is to use an "Eternal Query": a scalable infinite query.
+This is made possible by using the `maxPages` option in conjunction with `getNextPageParam` and `getPreviousPageParam` to allow fetching pages when needed in both directions.
+
+In the following example only 3 pages are kept in the query data pages array. If a refetch is needed, only 3 pages will be refetched sequentially.
+
+[//]: # 'Example9'
+
+```tsx
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: fetchProjects,
+  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
+  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
+  maxPages: 3,
+})
+```

docs/react/reference/useInfiniteQuery.md

@@ -39,6 +39,12 @@ The options for `useInfiniteQuery` are identical to the [`useQuery` hook](../ref
   - When new data is received for this query, this function receives both the first page of the infinite list of data and the full array of all pages.
   - It should return a **single variable** that will be passed as the last optional parameter to your query function.
   - Return `undefined` to indicate there is no previous page available.
+- `maxPages: number | undefined`
+  - The maximum number of pages to store in the infinite query data.
+  - When the maximum number of pages is reached, fetching a new page will result in the removal of either the first or last page from the pages array, depending on the specified direction.
+  - If `undefined` or equals `0`, the number of pages is unlimited
+  - Default value is `undefined`
+  - `getNextPageParam` and `getPreviousPageParam` must be properly defined if `maxPages` value is greater than `0` to allow fetching a page in both directions when needed.
 
 **Returns**
 
@@ -68,4 +74,4 @@ The returned properties for `useInfiniteQuery` are identical to the [`useQuery`
   - This will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option).
 - `isRefetching: boolean`
   - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending` or fetching of next or previous page
-  - Is the same as `isFetching && !isPending && !isFetchingNextPage && !isFetchingPreviousPage`
+  - Is the same as `isFetching && !isPending && !isFetchingNextPage && !isFetchingPreviousPage`

examples/react/infinite-query-with-max-pages/.gitignore

@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/react/infinite-query-with-max-pages/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`

examples/react/infinite-query-with-max-pages/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@tanstack/query-example-react-infinite-query-with-max-pages",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^0.21.1",
+    "isomorphic-unfetch": "3.0.0",
+    "next": "12.2.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-intersection-observer": "^8.33.1",
+    "@tanstack/react-query": "^4.7.1",
+    "@tanstack/react-query-devtools": "^4.7.1"
+  },
+  "scripts": {
+    "dev": "next",
+    "start": "next start",
+    "build": "next build"
+  }
+}

examples/react/infinite-query-with-max-pages/pages/api/projects.js

@@ -0,0 +1,19 @@
+// an endpoint for getting projects data
+export default (req, res) => {
+  const cursor = parseInt(req.query.cursor) || 0
+  const pageSize = 4
+
+  const data = Array(pageSize)
+    .fill(0)
+    .map((_, i) => {
+      return {
+        name: 'Project ' + (i + cursor) + ` (server time: ${Date.now()})`,
+        id: i + cursor,
+      }
+    })
+
+  const nextId = cursor < 20 ? data[data.length - 1].id + 1 : null
+  const previousId = cursor > -20 ? data[0].id - pageSize : null
+
+  setTimeout(() => res.json({ data, nextId, previousId }), 300)
+}

examples/react/infinite-query-with-max-pages/pages/index.js

@@ -0,0 +1,107 @@
+import React from 'react'
+import axios from 'axios'
+import {
+  useInfiniteQuery,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+const queryClient = new QueryClient()
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Example />
+    </QueryClientProvider>
+  )
+}
+
+function Example() {
+  const {
+    status,
+    data,
+    error,
+    isFetching,
+    isFetchingNextPage,
+    isFetchingPreviousPage,
+    fetchNextPage,
+    fetchPreviousPage,
+    hasNextPage,
+    hasPreviousPage,
+  } = useInfiniteQuery({
+    queryKey: ['projects'],
+    queryFn: async ({ pageParam = 0 }) => {
+      const res = await axios.get('/api/projects?cursor=' + pageParam)
+      return res.data
+    },
+    getPreviousPageParam: (firstPage) => firstPage.previousId ?? undefined,
+    getNextPageParam: (lastPage) => lastPage.nextId ?? undefined,
+    maxPages: 3,
+  })
+
+  return (
+    <div>
+      <h1>Infinite Query with max pages</h1>
+      <h3>4 projects per page</h3>
+      <h3>3 pages max</h3>
+      {status === 'loading' ? (
+        <p>Loading...</p>
+      ) : status === 'error' ? (
+        <span>Error: {error.message}</span>
+      ) : (
+        <>
+          <div>
+            <button
+              onClick={() => fetchPreviousPage()}
+              disabled={!hasPreviousPage || isFetchingPreviousPage}
+            >
+              {isFetchingPreviousPage
+                ? 'Loading more...'
+                : hasPreviousPage
+                ? 'Load Older'
+                : 'Nothing more to load'}
+            </button>
+          </div>
+          {data?.pages.map((page) => (
+            <React.Fragment key={page.nextId}>
+              {page.data.map((project) => (
+                <p
+                  style={{
+                    border: '1px solid gray',
+                    borderRadius: '5px',
+                    padding: '8px',
+                    fontSize: '14px',
+                    background: `hsla(${project.id * 30}, 60%, 80%, 1)`,
+                  }}
+                  key={project.id}
+                >
+                  {project.name}
+                </p>
+              ))}
+            </React.Fragment>
+          ))}
+          <div>
+            <button
+              onClick={() => fetchNextPage()}
+              disabled={!hasNextPage || isFetchingNextPage}
+            >
+              {isFetchingNextPage
+                ? 'Loading more...'
+                : hasNextPage
+                ? 'Load Newer'
+                : 'Nothing more to load'}
+            </button>
+          </div>
+          <div>
+            {isFetching && !isFetchingNextPage
+              ? 'Background Updating...'
+              : null}
+          </div>
+        </>
+      )}
+      <hr />
+      <ReactQueryDevtools initialIsOpen />
+    </div>
+  )
+}

packages/query-core/src/infiniteQueryBehavior.ts

@@ -1,5 +1,5 @@
 import type { QueryBehavior } from './query'
-
+import { addToEnd, addToStart } from './utils'
 import type {
   InfiniteData,
   QueryFunctionContext,
@@ -53,10 +53,15 @@ export function infiniteQueryBehavior<
           page: unknown,
           previous?: boolean,
         ) => {
-          newPageParams = previous
-            ? [param, ...newPageParams]
-            : [...newPageParams, param]
-          return previous ? [page, ...pages] : [...pages, page]
+          const { maxPages } = context.options
+
+          if (previous) {
+            newPageParams = addToStart(newPageParams, param, maxPages)
+            return addToStart(pages, page, maxPages)
+          }
+
+          newPageParams = addToEnd(newPageParams, param, maxPages)
+          return addToEnd(pages, page, maxPages)
         }
 
         // Create function to fetch a page