feat: Explode query string

OpenAPI 3 accepts parameters whose schema is an object
When specified, these parameters can be `in: query`
Such parameters can specify a style used to express them in the URL
The default style for `in: query` parameters is `form`
`form`-style parameters are expressed with a parameter-per-terminal value in the query object

This change extends the existing query params encoder.
It can now express nested objects and arrays in addition to scalar values

Author: duncanbeevers

src/explodeQueryFormStyle.ts

@@ -0,0 +1,36 @@
+export default function explodeQueryFormStyle(
+  acc: string[],
+  prefix: string,
+  params: unknown,
+): string[] {
+  if (params == null) {
+    return acc
+  }
+
+  if (Array.isArray(params)) {
+    return acc.concat(
+      params.flatMap((param, i) =>
+        explodeQueryFormStyle(
+          acc,
+          typeof param === 'object' ? `${prefix}[${i}]` : prefix,
+          param,
+        ),
+      ),
+    )
+  }
+
+  if (typeof params === 'object') {
+    return Object.entries(params || {}).flatMap(([key, value]) => {
+      return explodeQueryFormStyle(
+        acc,
+        prefix
+          ? `${prefix}[${encodeURIComponent(key)}]`
+          : encodeURIComponent(key),
+        value,
+      )
+    })
+  }
+
+  const encodedTerminalValue = encodeURIComponent(String(params))
+  return prefix ? [`${prefix}=${encodedTerminalValue}`] : [encodedTerminalValue]
+}

src/fetcher.ts

@@ -1,3 +1,4 @@
+import explodeQueryFormStyle from './explodeQueryFormStyle'
 import {
   ApiError,
   ApiResponse,
@@ -21,28 +22,12 @@ const sendBody = (method: Method) =>
   method === 'patch' ||
   method === 'delete'
 
-function queryString(params: Record<string, unknown>): string {
-  const qs: string[] = []
+function queryString<TParams extends Record<string, unknown>>(
+  params: TParams,
+): string {
+  const encoded = explodeQueryFormStyle([], '', params).join('&')
 
-  const encode = (key: string, value: unknown) =>
-    `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
-
-  Object.keys(params).forEach((key) => {
-    const value = params[key]
-    if (value != null) {
-      if (Array.isArray(value)) {
-        value.forEach((value) => qs.push(encode(key, value)))
-      } else {
-        qs.push(encode(key, value))
-      }
-    }
-  })
-
-  if (qs.length > 0) {
-    return `?${qs.join('&')}`
-  }
-
-  return ''
+  return encoded.length ? `?${encoded}` : ''
 }
 
 function getPath(path: string, payload: Record<string, any>) {
@@ -53,15 +38,12 @@ function getPath(path: string, payload: Record<string, any>) {
   })
 }
 
-function getQuery(
-  method: Method,
-  payload: Record<string, any>,
-  query: string[],
-) {
+function getQuery(request: Request, payload: Record<string, any>) {
+  const { method, queryParams } = request
   let queryObj = {} as any
 
   if (sendBody(method)) {
-    query.forEach((key) => {
+    queryParams.forEach((key) => {
       queryObj[key] = payload[key]
       delete payload[key]
     })
@@ -119,7 +101,7 @@ function getFetchParams(request: Request) {
   )
 
   const path = getPath(request.path, payload)
-  const query = getQuery(request.method, payload, request.queryParams)
+  const query = getQuery(request, payload)
   const body = getBody(request.method, payload)
   const headers = getHeaders(body, request.init?.headers)
   const url = request.baseUrl + path + query

test/explodeQueryFormStyle.test.ts

@@ -0,0 +1,83 @@
+import explodeQueryFormStyle from '../src/explodeQueryFormStyle'
+
+describe('explodeQueryFormStyle', () => {
+  it.each([
+    [null, []],
+    [undefined, []],
+    ['someString', ['someString']],
+    [{ query: 'queryValue' }, ['query=queryValue']],
+    [{ query: 9 }, ['query=9']],
+    [
+      {
+        level1: {
+          level1a: 'a',
+          level1b: 'b',
+        },
+      },
+      ['level1[level1a]=a', 'level1[level1b]=b'],
+    ],
+    [
+      {
+        level1: {
+          level1a: 'a',
+          level1b: 'b',
+        },
+        level2: {
+          level2a: {
+            level2sigma: 'off limits',
+          },
+          level2b: 'b',
+        },
+      },
+      [
+        'level1[level1a]=a',
+        'level1[level1b]=b',
+        'level2[level2a][level2sigma]=off%20limits',
+        'level2[level2b]=b',
+      ],
+    ],
+    [
+      {
+        options: ['staySignedIn', 'darkMode'],
+      },
+      ['options=staySignedIn', 'options=darkMode'],
+    ],
+    [
+      {
+        user1: {
+          options: ['staySignedIn', 'darkMode'],
+        },
+      },
+      ['user1[options]=staySignedIn', 'user1[options]=darkMode'],
+    ],
+    [
+      ['isFirstView', 'isRedirect'],
+      ['isFirstView', 'isRedirect'],
+    ],
+    [
+      {
+        list: [{ name: 'Turtle' }, { name: 'Mouse' }],
+      },
+      ['list[0][name]=Turtle', 'list[1][name]=Mouse'],
+    ],
+    [
+      {
+        parts: [
+          ['red', 200],
+          ['green', 25],
+          ['blue', 170],
+        ],
+      },
+      [
+        'parts[0]=red',
+        'parts[0]=200',
+        'parts[1]=green',
+        'parts[1]=25',
+        'parts[2]=blue',
+        'parts[2]=170',
+      ],
+    ],
+  ])('should explode %p to %p', (input, expectedOutput) => {
+    expect(explodeQueryFormStyle([], '', input)).toEqual(expectedOutput)
+  })
+})

test/fetch.test.ts

@@ -270,4 +270,38 @@ describe('fetch', () => {
     expect(captured.url).toEqual('https://api.backend.dev/bodyquery/1?scalar=a')
     expect(captured.body).toEqual('{"list":["b","c"]}')
   })
+
+  describe('stringify params', () => {
+    it('should use form-style stringifier', async () => {
+      fetcher.configure({
+        baseUrl: 'https://api.backend.dev',
+      })
+
+      const captured = { url: '' }
+
+      fetcher.use(async (url, init, next) => {
+        captured.url = url
+        return next(url, init)
+      })
+
+      const fun = fetcher.path('/query/{a}/{b}').method('get').create()
+
+      await fun({
+        a: 1,
+        b: '/',
+        scalar: 'a',
+        list: ['b', 'c'],
+        object: {
+          nestedObject: {
+            nestedKey: 'd',
+          },
+          nestedList: ['e', 'f'],
+        },
+      })
+
+      expect(captured.url).toBe(
+        'https://api.backend.dev/query/1/%2F?scalar=a&list=b&list=c&object[nestedObject][nestedKey]=d&object[nestedList]=e&object[nestedList]=f',
+      )
+    })
+  })
 })

test/paths.ts

@@ -9,7 +9,16 @@ export type Data = {
 type Query = {
   parameters: {
     path: { a: number; b: string }
-    query: { scalar: string; list: string[] }
+    query: {
+      scalar: string
+      list: string[]
+      object?: {
+        nestedObject: {
+          nestedKey: string
+        }
+        nestedList: string[]
+      }
+    }
   }
   responses: { 200: { schema: Data } }
 }