fix(openapi): only treat actual array values as multi-value headers when serializing (#1745)

dinwwwh · web-flow · commit 37e8837558c5 · 2026-07-29T14:52:02.000+07:00
Header values that serialize into arrays (`Set`, `Map`, custom handlers)
were treated as multi-value headers and split into multiple lines. Now
only an actual array value is a multi-value header — the structure is
checked before serialization, and serialized-to-array values are merged
into a single comma-delimited line.

## Fixes

- `new Set(['a', 'b'])` as a header value now produces the single line
`a,b` instead of two separate header lines.
- Each item of a multi-value array is now serialized individually, so
items like `Set` or plain objects render as `b,c` / `k,v` instead of
`[object Object]`.
- Single values and multi-value items share the same formatting logic,
so a value formats identically whether it appears alone or inside an
array.

## Testing

- New tests cover serialized-to-array merging and per-item serialization
of multi-value arrays; all 423 `@orpc/openapi` tests pass, typecheck and
lint clean.
diff --git a/packages/openapi/src/adapters/standard/utils.test.ts b/packages/openapi/src/adapters/standard/utils.test.ts
@@ -40,6 +40,24 @@ describe('serializeHeaders', () => {
     })
   })
 
+  it('merges values that serialize into arrays as a single comma-delimited line', () => {
+    expect(serializeHeaders({
+      'x-set': new Set(['a', 'b']),
+      'x-map': new Map([['k1', 'v1'], ['k2', 'v2']]),
+    }, serializer)).toEqual({
+      'x-set': 'a,b',
+      'x-map': 'k1,v1,k2,v2',
+    })
+  })
+
+  it('treats only actual arrays as multi-value headers, array items stay a single line each', () => {
+    expect(serializeHeaders({
+      'x-array': ['a', new Set(['b', 'c']), { k: 'v' }],
+    }, serializer)).toEqual({
+      'x-array': ['a', 'b,c', 'k,v'],
+    })
+  })
+
   it('drops undefined and null values, including array items', () => {
     const serialized = serializeHeaders({
       'x-null': null,
diff --git a/packages/openapi/src/adapters/standard/utils.ts b/packages/openapi/src/adapters/standard/utils.ts
@@ -9,25 +9,59 @@ export function serializeHeaders(
   const result = new NullProtoObj<Record<string, string | string[]>>()
 
   for (const [key, value] of Object.entries(headers)) {
-    const serialized = serializer.serialize(value)
+    /**
+     * Only an actual array value represents a multi-value header (sent as multiple lines).
+     * Serialization can turn non-array values into arrays (e.g. Set, Map, custom handlers),
+     * and those must stay a single line, so the structure is checked before serializing.
+     */
+    if (Array.isArray(value)) {
+      const lines: string[] = []
 
-    if (Array.isArray(serialized)) {
-      result[key] = serialized
-        .filter(item => item !== undefined && item !== null)
-        .map(String)
-    }
+      for (const item of value) {
+        const line = serializeHeaderValue(item, serializer)
+
+        if (line !== undefined) {
+          lines.push(line)
+        }
+      }
 
-    else if (isTypescriptObject(serialized)) {
-      result[key] = Object.entries(serialized)
-        .filter(([, val]) => val !== undefined && val !== null)
-        .map(([key, val]) => `${String(key)},${String(val)}`)
-        .join(',')
+      result[key] = lines
+      continue
     }
 
-    else if (serialized !== undefined && serialized !== null) {
-      result[key] = String(serialized)
+    const line = serializeHeaderValue(value, serializer)
+
+    if (line !== undefined) {
+      result[key] = line
     }
   }
 
   return result
 }
+
+function serializeHeaderValue(
+  value: unknown,
+  serializer: Pick<OpenAPISerializer, 'serialize'>,
+): string | undefined {
+  const serialized = serializer.serialize(value)
+
+  if (Array.isArray(serialized)) {
+    return serialized
+      .filter(item => item !== undefined && item !== null)
+      .map(String)
+      .join(',')
+  }
+
+  if (isTypescriptObject(serialized)) {
+    return Object.entries(serialized)
+      .filter(([, val]) => val !== undefined && val !== null)
+      .map(([key, val]) => `${String(key)},${String(val)}`)
+      .join(',')
+  }
+
+  if (serialized !== undefined && serialized !== null) {
+    return String(serialized)
+  }
+
+  return undefined
+}
