Merge pull request #1081 from Shrugsy/docs/extend-customizing-queries-content

Author: markerikson

docs/package-lock.json

@@ -8,6 +8,7 @@
     "@types/redux-logger": "^3.0.8",
     "axios": "^0.20.0",
     "formik": "^2.1.5",
+    "graphql-request": "^3.4.0",
     "immutable": "^3.8.2",
     "rxjs": "^6.6.2"
   }

docs/package.json

@@ -58,6 +58,49 @@ export const { useGetPokemonByNameQuery } = pokemonApi
 
 [summary](docblock://query/createApi.ts?token=CreateApiOptions.baseQuery)
 
+#### baseQuery function arguments
+
+- `args` - The return value of the `query` function for a given endpoint
+- `api` - The `BaseQueryApi` object, containing `signal`, `dispatch` and `getState` properties
+  - `signal` - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) object that may be used to abort DOM requests and/or read whether the request is aborted.
+  - `dispatch` - The `store.dispatch` method for the corresponding Redux store
+  - `getState` - A function that may be called to access the current store state
+- `extraOptions` - The value of the optional `extraOptions` property provided for a given endpoint
+
+#### baseQuery function signature
+
+```ts title="Base Query signature" no-transpile
+export type BaseQueryFn<
+  Args = any,
+  Result = unknown,
+  Error = unknown,
+  DefinitionExtraOptions = {},
+  Meta = {}
+> = (
+  args: Args,
+  api: BaseQueryApi,
+  extraOptions: DefinitionExtraOptions
+) => MaybePromise<QueryReturnValue<Result, Error, Meta>>
+
+export interface BaseQueryApi {
+  signal: AbortSignal
+  dispatch: ThunkDispatch<any, any, any>
+  getState: () => unknown
+}
+
+export type QueryReturnValue<T = unknown, E = unknown, M = unknown> =
+  | {
+      error: E
+      data?: undefined
+      meta?: M
+    }
+  | {
+      error?: undefined
+      data: T
+      meta?: M
+    }
+```
+
 [examples](docblock://query/createApi.ts?token=CreateApiOptions.baseQuery)
 
 ### `endpoints`
@@ -300,83 +343,58 @@ _(required if no `query` provided)_
 
 [summary](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQueryFn.queryFn)
 
-[examples](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQueryFn.queryFn)
+Called with the same arguments as `baseQuery`, as well as the provided `baseQuery` function itself. It is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
 
-### `transformResponse`
-
-_(optional, can't be used with `queryFn`)_
-
-[summary](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.transformResponse)
+See also [Customizing queries with queryFn](../usage/customizing-queries.mdx#customizing-queries-with-queryfn).
 
-In some cases, you may want to manipulate the data returned from a query before you put it in the cache. In this instance, you can take advantage of `transformResponse`.
-
-By default, the payload from the server is returned directly.
-
-```ts
-function defaultTransformResponse(baseQueryReturnValue: unknown) {
-  return baseQueryReturnValue
+```ts title="queryFn signature" no-transpile
+queryFn(
+  arg: QueryArg,
+  api: BaseQueryApi,
+  extraOptions: BaseQueryExtraOptions<BaseQuery>,
+  baseQuery: (arg: Parameters<BaseQuery>[0]) => ReturnType<BaseQuery>
+): MaybePromise<
+| {
+    error: BaseQueryError<BaseQuery>
+    data?: undefined
+  }
+| {
+    error?: undefined
+    data: ResultType
+  }
+>
+
+export interface BaseQueryApi {
+  signal: AbortSignal
+  dispatch: ThunkDispatch<any, any, any>
+  getState: () => unknown
 }
 ```
 
-To change it, provide a function that looks like:
+#### queryFn function arguments
 
-```ts title="Unpack a deeply nested collection" no-transpile
-transformResponse: (response) => response.some.deeply.nested.collection
-```
+- `args` - The argument provided when the query itself is called
+- `api` - The `BaseQueryApi` object, containing `signal`, `dispatch` and `getState` properties
+  - `signal` - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) object that may be used to abort DOM requests and/or read whether the request is aborted.
+  - `dispatch` - The `store.dispatch` method for the corresponding Redux store
+  - `getState` - A function that may be called to access the current store state
+- `extraOptions` - The value of the optional `extraOptions` property provided for the endpoint
+- `baseQuery` - The `baseQuery` function provided to the api itself
 
-#### Example - Normalizing response data
+[examples](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQueryFn.queryFn)
 
-```ts title="Normalize the response data" no-transpile
-transformResponse: (response) =>
-  response.reduce((acc, curr) => {
-    acc[curr.id] = curr
-    return acc
-  }, {})
-```
+### `transformResponse`
 
-#### Example - Unpacking deeply nested data
+_(optional, not applicable with `queryFn`)_
 
-```ts title="GraphQL transformation example"
-// file: graphqlBaseQuery.ts noEmit
-import { BaseQueryFn } from '@reduxjs/toolkit/query'
-declare const graphqlBaseQuery: (args: { baseUrl: string }) => BaseQueryFn
-declare const gql: (literals: TemplateStringsArray) => void
-export { graphqlBaseQuery, gql }
+[summary](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.transformResponse)
 
-// file: graphqlApi.ts
-import { createApi } from '@reduxjs/toolkit/query'
-import { graphqlBaseQuery, gql } from './graphqlBaseQuery'
+In some cases, you may want to manipulate the data returned from a query before you put it in the cache. In this instance, you can take advantage of `transformResponse`.
 
-interface Post {
-  id: number
-  title: string
-}
+See also [Customizing query responses with `transformResponse`](../usage/customizing-queries.mdx#customizing-query-responses-with-transformresponse)
 
-export const api = createApi({
-  baseQuery: graphqlBaseQuery({
-    baseUrl: '/graphql',
-  }),
-  endpoints: (builder) => ({
-    getPosts: builder.query<Post[], void>({
-      query: () => ({
-        body: gql`
-          query {
-            posts {
-              data {
-                id
-                title
-              }
-            }
-          }
-        `,
-      }),
-      // highlight-start
-      transformResponse: (response: { posts: { data: Post[] } }) =>
-        response.posts.data,
-      // highlight-end
-    }),
-  }),
-})
+```ts title="Unpack a deeply nested collection" no-transpile
+transformResponse: (response) => response.some.deeply.nested.collection
 ```
 
 ### `extraOptions`

docs/rtk-query/api/createApi.mdx

@@ -1010,8 +1010,8 @@ The Redux docs have always recommended [keeping data in a normalized lookup tabl
 
 There are a couple additional points that can help here:
 
-- The generated query hooks have [a `selectFromResult` option](../api/created-api/hooks.mdx) that allow components to read individual pieces of data from a query result. As an example, a `<TodoList>` component might call `useTodosQuery()`, and each individual `<TodoListItem>` could use the same query hook but select from the result to get the right todo object.
-- You can use the [`transformResponse` endpoint option](../api/createApi.mdx) to modify the fetched data so that it's stored in a different shape, such as using `createEntityAdapter` to normalize the data _for this one response_ before it's inserted into the cache.
+- The generated query hooks have [a `selectFromResult` option](../api/created-api/hooks.mdx#selectfromresult) that allow components to read individual pieces of data from a query result. As an example, a `<TodoList>` component might call `useTodosQuery()`, and each individual `<TodoListItem>` could use the same query hook but select from the result to get the right todo object.
+- You can use the [`transformResponse` endpoint option](../api/createApi.mdx#transformresponse) to modify the fetched data so that it's [stored in a different shape](./customizing-queries.mdx#customizing-query-responses-with-transformresponse), such as using `createEntityAdapter` to normalize the data _for this one response_ before it's inserted into the cache.
 
 ## Further information