feat: Serialize plain objects to dot path notation

Author: razor-x

README.md

@@ -36,12 +36,20 @@ which encodes most non-alphanumeric characters.
   - The array `{ foo: [1, 2] }` serializes to `foo=1&foo=2`.
   - The single element array `{ foo: [1] }` serializes to `foo=1`.
   - The empty array `{ foo: [] }` serializes to `foo=`.
-  - Serialization of the single element array containing the empty string is not supported
-    and will throw an `UnserializableParamError`.
+  - Serialization of arrays containing `null` or `undefined` values
+    is not supported and will throw an `UnserializableParamError`.
+  - Serialization of the single element array containing the empty string
+    is not supported and will throw an `UnserializableParamError`.
     Otherwise, the serialization of `{ foo: [''] }` would conflict with `{ foo: [] }`.
     This serializer chooses to support the more common and more useful case of an empty array.
-- Serialization of functions or other objects is not supported
-  and will throw an `UnserializableParamError`.
+- Serialization of objects and nested objects first serializes the keys
+- to dot-path format and then serializes the values as above, e.g.,
+  `{ foo: 'a', bar: { baz: 'b', fizz: [1, 2] } }` serializes to
+  `foo=a&bar.baz=b&bar.fizz=1&bar.fizz=2`.
+- Serialization of nested arrays or objects nested inside arrays
+  is not supported and will throw an `UnserializableParamError`.
+- Serialization of functions or other objects is
+  is not supported and will throw an `UnserializableParamError`.
 
 ## Installation
 

examples/axios.ts

@@ -25,6 +25,7 @@ export const handler: Handler<Options> = async ({ logger }) => {
       f: [],
       g: new Date(),
       h: Temporal.Now.instant(),
+      i: { foo: 1, bar: { baz: 2, fizz: [1, 'a'] } },
     },
   })
   logger.info({ data }, 'Response')

src/lib/object.ts

@@ -0,0 +1,8 @@
+export const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (v == null) return false
+  if (typeof v !== 'object') return false
+  const proto = Object.getPrototypeOf(v)
+  if (proto === null) return true
+  if (proto === Object.prototype) return true
+  return false
+}

src/lib/serialize.ts

@@ -1,4 +1,5 @@
 import { isDateLike, isTemporalInstantLike } from './date.js'
+import { isPlainObject } from './object.js'
 
 type Params = Record<string, unknown>
 
@@ -12,7 +13,24 @@ export const updateUrlSearchParams = (
   searchParams: URLSearchParams,
   params: Record<string, unknown>,
 ): void => {
-  for (const [name, value] of Object.entries(params)) {
+  nestedUpdateUrlSearchParams(searchParams, params, [])
+  searchParams.sort()
+}
+
+const nestedUpdateUrlSearchParams = (
+  searchParams: URLSearchParams,
+  params: Record<string, unknown>,
+  path: string[],
+): void => {
+  for (const [key, value] of Object.entries(params)) {
+    const currentPath = [...path, key]
+    if (isPlainObject(value)) {
+      nestedUpdateUrlSearchParams(searchParams, value, currentPath)
+      return
+    }
+
+    const name = currentPath.join('.')
+
     if (value == null) continue
 
     if (Array.isArray(value)) {
@@ -31,8 +49,6 @@ export const updateUrlSearchParams = (
 
     searchParams.set(name, serialize(name, value))
   }
-
-  searchParams.sort()
 }
 
 const serialize = (k: string, v: unknown): string => {

test/serialization.test.ts

@@ -94,14 +94,54 @@ test('serializes Temporal.Instant', (t) => {
   )
 })
 
-test('cannot serialize unserializable values', (t) => {
-  t.throws(() => serializeUrlSearchParams({ foo: {} }), {
-    instanceOf: UnserializableParamError,
-  })
-  t.throws(() => serializeUrlSearchParams({ foo: { x: 2 } }), {
+test('serializes plain objects', (t) => {
+  t.is(
+    serializeUrlSearchParams({
+      foo: 1,
+      bar: { baz: 'a' },
+    }),
+    'bar.baz=a&foo=1',
+  )
+
+  t.is(
+    serializeUrlSearchParams({
+      foo: 1,
+      bar: { baz: { x: { z: 1 } } },
+    }),
+    'bar.baz.x.z=1&foo=1',
+  )
+
+  t.is(
+    serializeUrlSearchParams({
+      foo: 1,
+      bar: { baz: { x: { z: null } } },
+    }),
+    'foo=1',
+  )
+
+  t.is(
+    serializeUrlSearchParams({
+      foo: 1,
+      bar: { baz: [1, 'a'] },
+    }),
+    'bar.baz=1&bar.baz=a&foo=1',
+  )
+})
+
+test('cannot serialize functions', (t) => {
+  t.throws(() => serializeUrlSearchParams({ foo: () => {} }), {
     instanceOf: UnserializableParamError,
   })
-  t.throws(() => serializeUrlSearchParams({ foo: () => {} }), {
+})
+
+test('cannot serialize non-plain objects', (t) => {
+  class Foo {
+    bar: string
+    constructor() {
+      this.bar = 'a'
+    }
+  }
+  t.throws(() => serializeUrlSearchParams({ foo: new Foo() }), {
     instanceOf: UnserializableParamError,
   })
 })
@@ -119,6 +159,9 @@ test('cannot serialize array params with unserializable values', (t) => {
   t.throws(() => serializeUrlSearchParams({ bar: ['a', []] }), {
     instanceOf: UnserializableParamError,
   })
+  t.throws(() => serializeUrlSearchParams({ bar: ['a', ['']] }), {
+    instanceOf: UnserializableParamError,
+  })
   t.throws(() => serializeUrlSearchParams({ bar: ['a', {}] }), {
     instanceOf: UnserializableParamError,
   })