Support a custom paramsSerializer on fetchBaseQuery (#1594)

Co-authored-by: Josh Fraser <joshfraser91@gmail.com>

Author: msutkowski

docs/rtk-query/api/fetchBaseQuery.mdx

@@ -13,7 +13,7 @@ description: 'RTK Query > API: fetchBaseQuery reference'
 
 This is a very small wrapper around [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) that aims to simplify requests. It is not a full-blown replacement for `axios`, `superagent`, or any other more heavy-weight library, but it will cover the large majority of your needs.
 
-It takes all standard options from fetch's [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) interface, as well as `baseUrl`, a `prepareHeaders` function, and an optional `fetch` function.
+It takes all standard options from fetch's [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) interface, as well as `baseUrl`, a `prepareHeaders` function, an optional `fetch` function, and a `paramsSerializer` function.
 
 - `baseUrl` _(required)_
   - Typically a string like `https://api.your-really-great-app.com/v1/`. If you don't provide a `baseUrl`, it defaults to a relative path from where the request is being made. You should most likely _always_ specify this.
@@ -25,6 +25,8 @@ It takes all standard options from fetch's [`RequestInit`](https://developer.moz
     ;(headers: Headers, api: { getState: () => unknown }) => Headers
     ```
 
+- `paramsSerializer` _(optional)_
+  - A function that can be used to apply custom transformations to the data passed into [`params`](#setting-the-query-string). If you don't provide this, `params` will be given directly to `new URLSearchParms()`. With some API integrations, you may need to leverage this to use something like the [`query-string`](https://github.com/sindresorhus/query-string) library to support different array types.
 - `fetchFn` _(optional)_
   - A fetch function that overrides the default on the window. Can be useful in SSR environments where you may need to leverage `isomorphic-fetch` or `cross-fetch`.
 
@@ -154,15 +156,20 @@ By default, `fetchBaseQuery` assumes that every request you make will be `json`,
 
 ### Setting the query string
 
-`fetchBaseQuery` provides a simple mechanism that converts an `object` to a serialized query string. If this doesn't suit your needs, you can always build your own querystring and set it in the `url`.
+`fetchBaseQuery` provides a simple mechanism that converts an `object` to a serialized query string by passing the object. If this doesn't suit your needs, you have two options:
+
+1. Pass the `paramsSerializer` option to `fetchBaseQuery` to apply custom transformations
+2. Build your own querystring and set it in the `url`
 
 ```ts no-transpile
  // omitted
   endpoints: (builder) => ({
     updateUser: builder.query({
       query: (user: Record<string, string>) => ({
         url: `users`,
-        params: user // The user object is automatically converted and produces a request like /api/users?first_name=test&last_name=example
+        // Assuming no `paramsSerializer` is specified, the user object is automatically converted
+        // and produces a url like /api/users?first_name=test&last_name=example
+        params: user
       }),
     }),
 ```

packages/toolkit/package.json

@@ -66,6 +66,7 @@
     "msw": "^0.28.2",
     "node-fetch": "^2.6.1",
     "prettier": "^2.2.1",
+    "query-string": "^7.0.1",
     "rimraf": "^3.0.2",
     "rollup": "^2.47.0",
     "rollup-plugin-strip-code": "^0.2.6",

packages/toolkit/src/query/fetchBaseQuery.ts

@@ -119,6 +119,7 @@ export type FetchBaseQueryArgs = {
     input: RequestInfo,
     init?: RequestInit | undefined
   ) => Promise<Response>
+  paramsSerializer?: (params: Record<string, any>) => string
 } & RequestInit
 
 export type FetchBaseQueryMeta = { request: Request; response?: Response }
@@ -156,11 +157,14 @@ export type FetchBaseQueryMeta = { request: Request; response?: Response }
  * Accepts a custom `fetch` function if you do not want to use the default on the window.
  * Useful in SSR environments if you need to use a library such as `isomorphic-fetch` or `cross-fetch`
  *
+ * @param {(params: Record<string, unknown> => string} paramsSerializer
+ * An optional function that can be used to stringify querystring parameters.
  */
 export function fetchBaseQuery({
   baseUrl,
   prepareHeaders = (x) => x,
   fetchFn = defaultFetchFn,
+  paramsSerializer,
   ...baseFetchOptions
 }: FetchBaseQueryArgs = {}): BaseQueryFn<
   string | FetchArgs,
@@ -216,7 +220,9 @@ export function fetchBaseQuery({
 
     if (params) {
       const divider = ~url.indexOf('?') ? '&' : '?'
-      const query = new URLSearchParams(stripUndefined(params))
+      const query = paramsSerializer
+        ? paramsSerializer(params)
+        : new URLSearchParams(stripUndefined(params))
       url += divider + query
     }
 

packages/toolkit/src/query/tests/fetchBaseQuery.test.tsx

@@ -4,6 +4,7 @@ import { setupApiStore } from './helpers'
 import { server } from './mocks/server'
 import { default as crossFetch } from 'cross-fetch'
 import { rest } from 'msw'
+import queryString from 'query-string'
 
 const defaultHeaders: Record<string, string> = {
   fake: 'header',
@@ -450,6 +451,53 @@ describe('fetchBaseQuery', () => {
 
       expect(request.url).toEqual(`${baseUrl}/echo?apple=fruit&randy=null`)
     })
+
+    it('should support a paramsSerializer', async () => {
+      const baseQuery = fetchBaseQuery({
+        baseUrl,
+        fetchFn: fetchFn as any,
+        paramsSerializer: (params: Record<string, unknown>) =>
+          queryString.stringify(params, { arrayFormat: 'bracket' }),
+      })
+
+      const api = createApi({
+        baseQuery,
+        endpoints(build) {
+          return {
+            query: build.query({
+              query: () => ({ url: '/echo', headers: {} }),
+            }),
+            mutation: build.mutation({
+              query: () => ({
+                url: '/echo',
+                method: 'POST',
+                credentials: 'omit',
+              }),
+            }),
+          }
+        },
+      })
+
+      const params = {
+        someArray: ['a', 'b', 'c'],
+      }
+
+      let request: any
+      ;({ data: request } = await baseQuery(
+        { url: '/echo', params },
+        {
+          signal: new AbortController().signal,
+          dispatch: storeRef.store.dispatch,
+          getState: storeRef.store.getState,
+          extra: undefined,
+        },
+        {}
+      ))
+
+      expect(request.url).toEqual(
+        `${baseUrl}/echo?someArray[]=a&someArray[]=b&someArray[]=c`
+      )
+    })
   })
 
   describe('validateStatus', () => {

yarn.lock

@@ -5043,6 +5043,7 @@ __metadata:
     msw: ^0.28.2
     node-fetch: ^2.6.1
     prettier: ^2.2.1
+    query-string: ^7.0.1
     redux: ^4.1.0
     redux-thunk: ^2.3.0
     reselect: ^4.0.0
@@ -12272,6 +12273,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"filter-obj@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "filter-obj@npm:1.1.0"
+  checksum: 1049ac0c306198edf2c090375f7a80545a01e798b4996dbde13398a263cd923b5eb8a240dfadb03260621249a404a686e1a55980c6e59af70ee3880323998703
+  languageName: node
+  linkType: hard
+
 "finalhandler@npm:~1.1.2":
   version: 1.1.2
   resolution: "finalhandler@npm:1.1.2"
@@ -20152,6 +20160,18 @@ fsevents@^1.2.7:
   languageName: node
   linkType: hard
 
+"query-string@npm:^7.0.1":
+  version: 7.0.1
+  resolution: "query-string@npm:7.0.1"
+  dependencies:
+    decode-uri-component: ^0.2.0
+    filter-obj: ^1.1.0
+    split-on-first: ^1.0.0
+    strict-uri-encode: ^2.0.0
+  checksum: 0709d82a6dc332de978878b1bfe8de093b50527bcfcb2fd04e46f2d69c94bbad79e056a47e549b4ca5751cf624a03b27fb26ec3e29294a369e97be7d67279891
+  languageName: node
+  linkType: hard
+
 "querystring-es3@npm:^0.2.0":
   version: 0.2.1
   resolution: "querystring-es3@npm:0.2.1"
@@ -22657,6 +22677,13 @@ resolve@~1.19.0:
   languageName: node
   linkType: hard
 
+"split-on-first@npm:^1.0.0":
+  version: 1.1.0
+  resolution: "split-on-first@npm:1.1.0"
+  checksum: 2ef26fee62665be9547e8035734b856e658b08fd13e70271a2f258147f29d1f18e12b5cb7f7670d83e113c172a9c5fe3d87d9d7c02a1d3d57824818d75d942ab
+  languageName: node
+  linkType: hard
+
 "split-string@npm:^3.0.1, split-string@npm:^3.0.2":
   version: 3.1.0
   resolution: "split-string@npm:3.1.0"
@@ -22828,6 +22855,13 @@ resolve@~1.19.0:
   languageName: node
   linkType: hard
 
+"strict-uri-encode@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "strict-uri-encode@npm:2.0.0"
+  checksum: 775012e88b9d8dff939d514bf376d615a15e8228a5dd587a94ac3c71fce41aa3635cd808aa796e2c1cd33f3f2fe2fbf89b74ee18a504a1905efa1854311e04bb
+  languageName: node
+  linkType: hard
+
 "string-argv@npm:~0.3.1":
   version: 0.3.1
   resolution: "string-argv@npm:0.3.1"