Apply suggestions from code review

Co-authored-by: Shrugsy <[email protected]>

Author: maruhgar

docs/rtk-query/usage/pagination.mdx

@@ -76,39 +76,75 @@ const PostList = () => {
 };
 ```
 
-## Pagination and Caching
-
-If you have caching enabled for your paginated queries, it maybe a good idea to invalidate the `LIST` cache as well when you do a `delete` mutation.
+### Automated Re-fetching of Paginated Queries
+
+It is a common use-case to utilize tag invalidation to perform
+[automated re-fetching](./automated-refetching.mdx) with RTK Query.
+
+A potential pitfall when combining this with pagination is that your paginated query may only
+provide a _partial_ list at any given time, and hence not `provide` tags for entity IDs that
+fall on pages which aren't currently shown. If a specific entity is deleted that falls on an
+earlier page, the paginated query will not be providing a tag for that specific ID, and will
+not be invalidated to trigger re-fetching data. As a result, items on the current page that
+should shift one item up will not have done so, and the total count of items and/or pages
+may be incorrect.
+
+A strategy to overcome this is to ensure that the `delete` mutation always `invalidates` the
+paginated query, even if the deleted item is not _currently_ provided on that page. We can
+leverage the concept of
+[advanced invalidation with abstract tag ids](./automated-refetching.mdx#advanced-invalidation-with-abstract-tag-ids)
+to do this by `providing` a `'Posts'` tag with the `'PARTIAL-LIST'` ID in our paginated query,
+and `invalidating` that corresponding tag for any mutation that should affect it.
 
 ```ts title="Example of invalidating cache for paginated queries"
-// file: types.ts noEmit
-export interface Post {
+// file: api.ts
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
+interface Post {
   id: number
   name: string
 }
+interface ListResponse<T> {
+  page: number
+  per_page: number
+  total: number
+  total_pages: number
+  data: T[]
+}
 
-// file: api.ts
-// Or from '@reduxjs/toolkit/query/react'
-import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
-import { Post } from './types'
-
-export const postApi = createApi({  
-  reducerPath: 'postsApi',  
-  baseQuery: fetchBaseQuery({ baseUrl: '/' }),  
-  tagTypes: ['Posts'],  
+export const postApi = createApi({
+  reducerPath: 'postsApi',
+  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
+  tagTypes: ['Posts'],
   endpoints: (build) => ({
-    deletePost: build.mutation<{ success: boolean; id: number }, number>({ 
-      query(id) {        
-        return {          
-          url: `post/${id}`,          
-          method: 'DELETE',        
-        }      
-      },      
-      // Invalidates queries that subscribe to this Post `id` as well as the `LIST`.
+    listPosts: build.query<ListResponse<Post>, number | void>({
+      query: (page = 1) => `posts?page=${page}`,
+      // highlight-start
+      providesTags: (result, error, page) =>
+        result
+          ? [
+              // Provides a tag for each post in the current page,
+              // as well as the 'PARTIAL-LIST' tag.
+              ...result.data.map(({ id }) => ({ type: 'Posts' as const, id })),
+              { type: 'Posts', id: 'PARTIAL-LIST' },
+            ]
+          : [{ type: 'Posts', id: 'PARTIAL-LIST' }],
+      // highlight-end
+    }),
+    deletePost: build.mutation<{ success: boolean; id: number }, number>({
+      query(id) {
+        return {
+          url: `post/${id}`,
+          method: 'DELETE',
+        }
+      },
+      // Invalidates the tag for this Post `id`, as well as the `PARTIAL-LIST` tag,
+      // causing the `listPosts` query to re-fetch if a component is subscribed to the query.
+      // highlight-start
       invalidatesTags: (result, error, id) => [
-        { type: "Posts", id },
-        { type: "Posts", id: "LIST" },
+        { type: 'Posts', id },
+        { type: 'Posts', id: 'PARTIAL-LIST' },
       ],
+      // highlight-end
     }),
   }),
 })