feat: Serialize the empty string to undefined (#22)

BREAKING CHANGE: Serialization of the empty string is now treated as `undefined` instead of an UnserializableParamError.

Otherwise, the serialization of `{ foo: null }` would conflict with `{ foo: '' }`.
This serializer chooses to support the more common and more useful case of sending `null`
as a meaningful value while treating the empty string as sending no value.
This aligns with common UX patterns where input fields are initialized to the empty string.

Closes #20.

Author: razor-x

README.md

@@ -27,10 +27,11 @@ which encodes most non-alphanumeric characters.
 - Any `undefined` values are removed,
   e.g., `{ foo: undefined, bar: 1 }` serializes to `bar=1`.
 - The primitive type `string` is serialized using `.toString()`.
-  - Serialization of the empty string
-    is not supported and will throw an `UnserializableParamError`.
+  - Serialization of the empty string is treated as `undefined`.
     Otherwise, the serialization of `{ foo: null }` would conflict with `{ foo: '' }`.
-    This serializer chooses to support the more common and more useful case of `null`.
+    This serializer chooses to support the more common and more useful case of sending `null`
+    as a meaningful value while treating the empty string as sending no value.
+    This aligns with common UX patterns where input fields are initialized to the empty string.
 - The primitive `number` and `bigint` types are serialized using `.toString()`.
 - The primitive `boolean` type is serialized using `.toString()`,
   e.g., `{ foo: true, bar: false }` serializes to `foo=true&bar=false`.

src/lib/serialize.ts

@@ -42,6 +42,10 @@ const nestedUpdateUrlSearchParams = (
       continue
     }
 
+    if (typeof value === 'string' && value.length === 0) {
+      continue
+    }
+
     if (Array.isArray(value)) {
       if (value.length === 0) {
         searchParams.set(name, '')
@@ -79,12 +83,6 @@ const nestedUpdateUrlSearchParams = (
 const serialize = (k: string, v: unknown): string => {
   if (v === null) return ''
   if (typeof v === 'string') {
-    if (v.length === 0) {
-      throw new UnserializableParamError(
-        k,
-        'is the empty string which is unsupported',
-      )
-    }
     return v.toString()
   }
   if (typeof v === 'number') {

test/serialization.test.ts

@@ -17,6 +17,11 @@ test('serializes string', (t) => {
   t.is(serializeUrlSearchParams({ foo: '0' }), 'foo=0')
 })
 
+test('serializes the empty string to undefined', (t) => {
+  t.is(serializeUrlSearchParams({ foo: '' }), '')
+  t.is(serializeUrlSearchParams({ foo: 'd', bar: '' }), 'foo=d')
+})
+
 test('serializes number', (t) => {
   t.is(serializeUrlSearchParams({ foo: 1 }), 'foo=1')
   t.is(serializeUrlSearchParams({ foo: 23.8 }), 'foo=23.8')
@@ -173,12 +178,6 @@ test('cannot serialize non-plain objects', (t) => {
   })
 })
 
-test('cannot serialize the empty string', (t) => {
-  t.throws(() => serializeUrlSearchParams({ foo: '' }), {
-    instanceOf: UnserializableParamError,
-  })
-})
-
 test('cannot serialize array params with unserializable values', (t) => {
   t.throws(() => serializeUrlSearchParams({ foo: [''] }), {
     instanceOf: UnserializableParamError,