Serialize null

README.md

@@ -25,12 +25,18 @@ Serialization is guaranteed to be well-defined within each type, i.e.,
 if the type of value for a given key in the query string is fixed and known by
 the consumer parsing the string, it can be unambigously parsed back to the original primitive value.
 
+- The primitive `null` is serialized to an empty value,
+  e.g., `{ foo: null }` serializes to `foo=`.
+- Any `undefined` values are removed,
+  e.g., `{ foo: undefined, bar: 1 }` serializes to `baz=1`.
 - The primitive type `string` is serialized using `.toString()`.
+  - Serialization of the empty string
+    is not supported and will throw 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 null.
 - 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`.
-- The primitive `null` and `undefined` values are removed,
-  e.g., `{ foo: null, bar: undefined, baz: 1 }` serializes to `baz=1`.
 - `Date` objects are detected and serialized using `Date.toISOString()`,
   e.g., `{ foo: new Date(0) }` serializes to `foo=1970-01-01T00%3A00%3A00.000Z`.
 - `Temporal.Instant` objects are detected and serialized by first converting them to `Date`
@@ -41,9 +47,12 @@ the consumer parsing the string, it can be unambigously parsed back to the origi
   - 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=`.
+    As this serialization overlaps with `null`, parser implementations are advised
+    not to support nullable array parameters and parse this as the empty array.
+  - To support typed tuples, serialization of arrays containing mixed values is allowed.
   - 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
+  - Serialization of arrays 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.

src/lib/serialize.ts

@@ -31,14 +31,28 @@ const nestedUpdateUrlSearchParams = (
 
     const name = currentPath.join('.')
 
-    if (value == null) continue
+    if (value == null && value !== null) {
+      continue
+    }
 
     if (Array.isArray(value)) {
       if (value.length === 0) searchParams.set(name, '')
       if (value.length === 1 && value[0] === '') {
         throw new UnserializableParamError(
           name,
-          `is a single element array containing the empty string which is unsupported because it serializes to the empty array`,
+          'is a single element array containing the empty string which is unsupported',
+        )
+      }
+      if (value.some((v) => v === '')) {
+        throw new UnserializableParamError(
+          name,
+          'is an array containing the empty string which is unsupported',
+        )
+      }
+      if (value.some((v) => v == null)) {
+        throw new UnserializableParamError(
+          name,
+          'is an array containing null or undefined values which is unsupported',
         )
       }
       for (const v of value) {
@@ -52,7 +66,16 @@ const nestedUpdateUrlSearchParams = (
 }
 
 const serialize = (k: string, v: unknown): string => {
-  if (typeof v === 'string') return v.toString()
+  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') return v.toString()
   if (typeof v === 'bigint') return v.toString()
   if (typeof v === 'boolean') return v.toString()

test/serialization.test.ts

@@ -32,9 +32,9 @@ test('removes undefined params', (t) => {
   t.is(serializeUrlSearchParams({ foo: 1, bar: undefined }), 'foo=1')
 })
 
-test('removes null params', (t) => {
-  t.is(serializeUrlSearchParams({ bar: null }), '')
-  t.is(serializeUrlSearchParams({ foo: 1, bar: null }), 'foo=1')
+test('serializes null params', (t) => {
+  t.is(serializeUrlSearchParams({ bar: null }), 'bar=')
+  t.is(serializeUrlSearchParams({ foo: 1, bar: null }), 'bar=&foo=1')
 })
 
 test('serializes empty array params', (t) => {
@@ -56,18 +56,6 @@ test('serializes array params with many values', (t) => {
     serializeUrlSearchParams({ foo: 1, bar: ['null', '2', 'undefined'] }),
     'bar=null&bar=2&bar=undefined&foo=1',
   )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', '', ''] }),
-    'bar=&bar=&bar=&foo=1',
-  )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', 'a', '2'] }),
-    'bar=&bar=a&bar=2&foo=1',
-  )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', 'a', ''] }),
-    'bar=&bar=a&bar=&foo=1',
-  )
 })
 
 test('cannot serialize single element array params with empty string', (t) => {
@@ -116,7 +104,7 @@ test('serializes plain objects', (t) => {
       foo: 1,
       bar: { baz: { x: { z: null } } },
     }),
-    'foo=1',
+    'bar.baz.x.z=&foo=1',
   )
 
   t.is(
@@ -171,4 +159,13 @@ test('cannot serialize array params with unserializable values', (t) => {
   t.throws(() => serializeUrlSearchParams({ bar: ['a', () => {}] }), {
     instanceOf: UnserializableParamError,
   })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', 'a', ''] }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', 'a', '2'] }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', '', ''] }), {
+    instanceOf: UnserializableParamError,
+  })
 })