Add docs for infinite queries (#4820)

Author: markerikson

docs/rtk-query/api/createApi.mdx

@@ -39,8 +39,8 @@ import type { Pokemon } from './types'
 export const pokemonApi = createApi({
   reducerPath: 'pokemonApi',
   baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
-  endpoints: (builder) => ({
-    getPokemonByName: builder.query<Pokemon, string>({
+  endpoints: (build) => ({
+    getPokemonByName: build.query<Pokemon, string>({
       query: (name) => `pokemon/${name}`,
     }),
   }),
@@ -148,6 +148,10 @@ See [Endpoint Definition Parameters](#endpoint-definition-parameters) for detail
 
 #### Query endpoint definition
 
+Query endpoints (defined with `build.query()`) are used to cache data fetched from the server.
+
+You must specify either a `query` field (which will use the API's `baseQuery` to make a request), or a `queryFn` function with your own async logic. All other fields are optional.
+
 ```ts title="Query endpoint definition" no-transpile
 export type QueryDefinition<
   QueryArg,
@@ -220,8 +224,70 @@ export type QueryDefinition<
 }
 ```
 
+#### Infinite Query endpoint definition
+
+Infinite query endpoints (defined with `build.infiniteQuery()`) are used to cache multi-page data sets from the server. They have all the same callbacks and options as standard query endpoints, but also require an additional [`infiniteQueryOptions`](#infinitequeryoptions) field to specify how to calculate the unique parameters to fetch each page.
+
+For infinite query endpoints, there is a separation between the "query arg" used for the cache key, and the "page param" used to fetch a specific page. For example, a Pokemon API endpoint might have a string query arg like `"fire"` , but use a page number as the param to determine which page to fetch out of the results. This means the page param is what will be passed to your `query` or `queryFn` methods.
+
+```ts title="Infinite Query endpoint definition" no-transpile
+export type PageParamFunction<DataType, PageParam> = (
+  firstPage: DataType,
+  allPages: Array<DataType>,
+  firstPageParam: PageParam,
+  allPageParams: Array<PageParam>,
+) => PageParam | undefined | null
+
+export type InfiniteQueryDefinition<
+  QueryArg,
+  PageParam,
+  BaseQuery extends BaseQueryFn,
+  TagTypes extends string,
+  ResultType,
+  ReducerPath extends string = string,
+> =
+  // Infinite queries have all the same options as query endpoints,
+  // but store the `{data, pages}` structure, and use the
+  // `PageParam` type as the `QueryArg` for fetching.
+  QueryDefinition<PageParam, BaseQuery, TagTypes, InfiniteData<ResultType>> & {
+    /**
+     * Required options to configure the infinite query behavior.
+     * `initialPageParam` and `getNextPageParam` are required, to
+     * ensure the infinite query can properly fetch the next page of data.
+     * `initialPageparam` may be specified when using the
+     * endpoint, to override the default value.
+     */
+    infiniteQueryOptions: {
+      /**
+       * The initial page parameter to use for the first page fetch.
+       */
+      initialPageParam: PageParam
+      /**
+       * If specified, only keep this many pages in cache at once.
+       * If additional pages are fetched, older pages in the other
+       * direction will be dropped from the cache.
+       */
+      maxPages?: number
+      /**
+       * This function can be set to automatically get the previous cursor for infinite queries.
+       * The result will also be used to determine the value of `hasPreviousPage`.
+       */
+      getPreviousPageParam?: PageParamFunction<DataType, PageParam>
+      /**
+       * This function is required to automatically get the next cursor for infinite queries.
+       * The result will also be used to determine the value of `hasNextPage`.
+       */
+      getNextPageParam: PageParamFunction<DataType, PageParam>
+    }
+  }
+```
+
 #### Mutation endpoint definition
 
+Mutation endpoints (defined with build.mutation()`) are used to send updates to the server, and force invalidation and refetching of query endpoints.
+
+As with queries, you must specify either the `query` option or the `queryFn` async method.
+
 ```ts title="Mutation endpoint definition" no-transpile
 export type MutationDefinition<
   QueryArg,
@@ -446,7 +512,7 @@ export interface BaseQueryApi {
 }
 ```
 
-#### queryFn function arguments
+#### `queryFn` function arguments
 
 - `args` - The argument provided when the query itself is called
 - `api` - The `BaseQueryApi` object, containing `signal`, `dispatch` and `getState` properties
@@ -458,6 +524,24 @@ export interface BaseQueryApi {
 
 [examples](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQueryFn.queryFn)
 
+### `infiniteQueryOptions`
+
+_(only for `infiniteQuery` endpoints)_
+
+[summary](docblock://query/endpointDefinitions.ts?token=InfiniteQueryExtraOptions.infiniteQueryOptions)
+
+The `infiniteQueryOptions` field includes:
+
+- `initialPageParam`: the default page param value used for the first request, if this was not specified at the usage site
+- `maxPages`: an optional limit to how many fetched pages will be kept in the cache entry at a time
+- `getNextPageParam`: a required callback you must provide to calculate the next page param, given the existing cached pages and page params
+- `getPreviousPageParam`: an optional callback that will be used to calculate the previous page param, if you try to fetch backwards.
+
+Both `initialPageParam` and `getNextPageParam` are required, to
+ensure the infinite query can properly fetch the next page of data.Also, `initialPageParam` may be specified when using the endpoint, to override the default value. `maxPages` and `getPreviousPageParam` are both optional.
+
+[examples](docblock://query/endpointDefinitions.ts?token=InfiniteQueryExtraOptions.infiniteQueryOptions)
+
 ### `transformResponse`
 
 _(optional, not applicable with `queryFn`)_