Test and document overlapping fetches

Author: markerikson

docs/rtk-query/usage/infinite-queries.mdx

@@ -256,13 +256,23 @@ Similarly, this example relies on manual user clicks on a "Fetch More" button to
 
 The endpoint itself only defines `getNextPageParam`, so this example doesn't support fetching backwards, but that can be provided in cases where backwards fetching makes sense. The page param here is a simple incremented number, but the page param
 
-## Refetching
+## Infinite Query Behaviors
+
+### Overlapping Page Fetches
+
+Since all pages are stored in a single cache entry, there can only be one request in progress at a time. RTK Query already has logic built in to bail out of running a new request if there is already a request in flight for that cache entry.
+
+That means that if you call `fetchNextPage()` again while an existing request is in progress, the second call won't actually execute a request. Be sure to either await the previous `fetchNextPage()` promise result first or check the `isFetching` flag if you have concerns about a potential request already in progress.
+
+The promise returned from `fetchNextPage()` does have [a `promise.abort()` method attached](../../api/createAsyncThunk.mdx#canceling-while-running) that will force the earlier request to reject and not save the results. Note that this will mark the cache entry as errored, but the data will still exist. Since `promise.abort()` is synchronous, you would also need to await the previous promise to ensure the rejection is handled, and then trigger the new page fetch.
+
+### Refetching
 
 When an infinite query endpoint is refetched (due to tag invalidation, polling, arg change configuration, or manual refetching), RTK Query will try to sequentially refetch all pages currently in the cache. This ensures that the client is always working with the latest data, and avoids stale cursors or duplicate records.
 
 If the cache entry is ever removed and then re-added, it will start with only fetching the initial page.
 
-## Limiting Cache Entry Size
+### Limiting Cache Entry Size
 
 All fetched pages for a given query arg are stored in the `pages` array in that cache entry. By default, there is no limit to the number of stored pages - if you call `fetchNextPage()` 1000 times, `data.pages` will have 1000 pages stored.
 

packages/toolkit/src/query/tests/infiniteQueries.test.ts

@@ -348,30 +348,6 @@ describe('Infinite queries', () => {
     })
   })
 
-  test.skip('does not break refetching query endpoints', async () => {
-    const promise0 = storeRef.store.dispatch(
-      pokemonApi.endpoints.counters.initiate('a'),
-    )
-
-    console.log('State after dispatch: ', storeRef.store.getState().api.queries)
-
-    const res0 = await promise0
-
-    console.log('State after promise: ', storeRef.store.getState().api.queries)
-    console.log(storeRef.store.getState().actions)
-
-    const promise1 = storeRef.store.dispatch(
-      pokemonApi.util.upsertQueryData('counters', 'a', { id: 'a', counter: 1 }),
-    )
-
-    console.log('State after dispatch: ', storeRef.store.getState().api.queries)
-
-    const res = await promise1
-
-    console.log('State after promise: ', storeRef.store.getState().api.queries)
-    console.log(storeRef.store.getState().actions)
-  })
-
   test('does not have a page limit without maxPages', async () => {
     for (let i = 1; i <= 10; i++) {
       const res = await storeRef.store.dispatch(
@@ -643,6 +619,77 @@ describe('Infinite queries', () => {
     ])
   })
 
+  test('Handles multiple next page fetches at once', async () => {
+    const initialEntry = await storeRef.store.dispatch(
+      pokemonApi.endpoints.getInfinitePokemon.initiate('fire', {}),
+    )
+
+    checkResultData(initialEntry, [[{ id: '0', name: 'Pokemon 0' }]])
+
+    expect(queryCounter).toBe(1)
+
+    const promise1 = storeRef.store.dispatch(
+      pokemonApi.endpoints.getInfinitePokemon.initiate('fire', {
+        direction: 'forward',
+      }),
+    )
+
+    expect(queryCounter).toBe(1)
+
+    const promise2 = storeRef.store.dispatch(
+      pokemonApi.endpoints.getInfinitePokemon.initiate('fire', {
+        direction: 'forward',
+      }),
+    )
+
+    console.log('Awaiting promises 1 and 2')
+
+    const entry1 = await promise1
+    const entry2 = await promise2
+
+    // The second thunk should have bailed out because the entry was now
+    // pending, so we should only have sent one request.
+    expect(queryCounter).toBe(2)
+
+    expect(entry1).toEqual(entry2)
+
+    checkResultData(entry1, [
+      [{ id: '0', name: 'Pokemon 0' }],
+      [{ id: '1', name: 'Pokemon 1' }],
+    ])
+
+    expect(queryCounter).toBe(2)
+
+    const promise3 = storeRef.store.dispatch(
+      pokemonApi.endpoints.getInfinitePokemon.initiate('fire', {
+        direction: 'forward',
+      }),
+    )
+
+    expect(queryCounter).toBe(2)
+
+    // We can abort an existing promise, but due to timing issues,
+    // we have to await the promise first before triggering the next request.
+    promise3.abort()
+    const entry3 = await promise3
+
+    const promise4 = storeRef.store.dispatch(
+      pokemonApi.endpoints.getInfinitePokemon.initiate('fire', {
+        direction: 'forward',
+      }),
+    )
+
+    const entry4 = await promise4
+
+    expect(queryCounter).toBe(4)
+
+    checkResultData(entry4, [
+      [{ id: '0', name: 'Pokemon 0' }],
+      [{ id: '1', name: 'Pokemon 1' }],
+      [{ id: '2', name: 'Pokemon 2' }],
+    ])
+  })
+
   test('can fetch pages with refetchOnMountOrArgChange active', async () => {
     const pokemonApiWithRefetch = createApi({
       baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),