Document forceRefetch option

Author: markerikson

docs/rtk-query/api/createApi.mdx

@@ -380,6 +380,15 @@ If you specify `track: false` when manually dispatching queries, RTK Query will
 
 _(required if no `queryFn` provided)_
 
+```ts title="query signature" no-transpile
+export type query = <QueryArg>(
+  arg: QueryArg
+) => string | Record<string, unknown>
+
+// with `fetchBaseQuery`
+export type query = <QueryArg>(arg: QueryArg) => string | FetchArgs
+```
+
 [summary](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.query)
 
 [examples](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.query)
@@ -506,12 +515,29 @@ _(optional, only for query endpoints)_
 
 ### `merge`
 
-_(optional, only for query endpoints)_ w
+_(optional, only for query endpoints)_
 
 [summary](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.merge)
 
 [examples](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.merge)
 
+### `forceRefetch`
+
+_(optional, only for query endpoints)_
+
+```ts title="forceRefetch signature" no-transpile
+type forceRefetch = (params: {
+  currentArg: QueryArg | undefined
+  previousArg: QueryArg | undefined
+  state: RootState<any, any, string>
+  endpointState?: QuerySubState<any>
+}) => boolean
+```
+
+[summary](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.forceRefetch)
+
+[examples](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.forceRefetch)
+
 ### `onQueryStarted`
 
 _(optional)_

packages/toolkit/src/query/endpointDefinitions.ts

@@ -44,12 +44,23 @@ interface EndpointDefinitionWithQuery<
    *
    * const api = createApi({
    *   baseQuery: fetchBaseQuery({ baseUrl: '/' }),
+   *   tagTypes: ['Post'],
    *   endpoints: (build) => ({
    *     getPosts: build.query<PostsResponse, void>({
    *       // highlight-start
    *       query: () => 'posts',
    *       // highlight-end
-   *     })
+   *     }),
+   *     addPost: build.mutation<Post, Partial<Post>>({
+   *      // highlight-start
+   *      query: (body) => ({
+   *        url: `posts`,
+   *        method: 'POST',
+   *        body,
+   *      }),
+   *      // highlight-end
+   *      invalidatesTags: [{ type: 'Post', id: 'LIST' }],
+   *    }),
    *   })
    * })
    * ```
@@ -433,20 +444,37 @@ export interface QueryExtraOptions<
    * with `serializeQueryArgs` returning a fixed cache key and a `merge` callback
    * set to add incoming data to the cache entry each time.
    *
-   * Example:
+   * @example
    *
    * ```ts
-   * forceRefetch({currentArg, previousArg}) {
-   *   // Assume these are page numbers
-   *   return currentArg !== previousArg
-   * },
-   * serializeQueryArgs({endpointName}) {
-   *   return endpointName
-   * },
-   * merge(currentCacheData, responseData) {
-   *   currentCacheData.push(...responseData)
+   * // codeblock-meta title="forceRefresh: pagination"
+   *
+   * import { createApi, fetchBaseQuery, defaultSerializeQueryArgs } from '@reduxjs/toolkit/query/react'
+   * interface Post {
+   *   id: number
+   *   name: string
    * }
    *
+   * createApi({
+   *  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
+   *  endpoints: (build) => ({
+   *    listItems: build.query<string[], number>({
+   *      query: (pageNumber) => `/listItems?page=${pageNumber}`,
+   *     // Only have one cache entry because the arg always maps to one string
+   *     serializeQueryArgs: ({ endpointName }) => {
+   *       return endpointName
+   *      },
+   *      // Always merge incoming data to the cache entry
+   *      merge: (currentCache, newItems) => {
+   *        currentCache.push(...newItems)
+   *      },
+   *      // Refetch when the page arg changes
+   *      forceRefetch({ currentArg, previousArg }) {
+   *        return currentArg !== previousArg
+   *      },
+   *    }),
+   *  }),
+   *})
    * ```
    */
   forceRefetch?(params: {