fix(query): encode empty array strings as bare keys

[owenshen0907]

An empty scalar query value encodes as flag, but an empty string inside an array encodes as flag=. This produces different URL representations for the same empty value (#394).

Encode empty string array elements as bare keys, matching scalar empty strings. For example, encodeQueryItem("flag", ["", "value", ""]) now returns flag&flag=value&flag. Null/undefined array elements, zero, false, nonempty values, and empty arrays retain their existing behavior. Parsed query values remain the same; the serialized URL spelling changes for empty string array elements.

The regression tests reproduce the issue on main and cover encoded keys, mixed values, stringify/parse round trips, and withQuery output. Six new cases fail before the fix.

Validation (Node 22.23.3, pnpm 10.33.2):

• pnpm test — ESLint, Prettier, 503 tests, and type checks passed
• pnpm build — ESM, CJS, and declarations passed
• git diff --check — passed

Potential overlap: #391 optimizes the same array branch but preserves this bug. This small behavioral fix may need rebasing if that PR lands first.

Resolves #394.

Prepared with AI assistance; the regression and validation results above were verified locally.

Upstream CI status: ci run and autofix.ci run currently report action_required with no jobs executed. They require upstream approval; local validation above is complete.

Summary by CodeRabbit

• Bug Fixes
  • Empty strings in query parameter arrays are now encoded as key-only parameters. Other array values retain their existing encoding.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 747a1303-e25a-4b2e-ac14-85f4535c7aca

---

📥 Commits

Reviewing files that changed from the base of the PR and between f06c800 and 27aa249.

---

📒 Files selected for processing (2)

• src/query.ts
• test/query.test.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Array elements with empty strings now encode as key-only query parameters, matching the encoding used for scalar empty strings. Tests cover encoding, stringify/parse behavior, and withQuery expectations.

Changes

Query parameter encoding

Layer / File(s)	Summary
Encode empty array values src/query.ts, test/query.test.ts	Empty-string array elements now encode without an equals sign. Tests cover scalar and array values, query round-tripping, and withQuery output.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~5 minutes

Change: Bug fix · Severity of issue fixed: Low

---

Merge Risk: ⚪ Minimal · up to 27aa2

Empty-string array values use the intended bare-key encoding without changing how those keys parse. No merge-blocking issue was found.

Architecture Summary

Architecture risk: 🔵 Low · up to 27aa2

The change affects 2 systems.

Changed systems: src, test

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 1 changed file maps to changed impact.
• observed — test (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in src/query.ts: Array items equal to "" now encode as a key-only parameter; other items continue to encode as key-value pairs.
• observed — Modified behavior in test/query.test.ts: Added encodeQueryItem cases for scalar and array values, including empty arrays, empty strings, special characters, falsy values, null, and undefined. Expected encodings distinguish key-only empty strings from explicit values and encode array null/undefined as their string forms.
• observed — Modified behavior in test/query.test.ts: Added stringifyQuery tests asserting empty scalar and array strings round-trip through parseQuery, while zero, false, and null are retained and undefined is omitted.
• observed — Modified behavior in test/query.test.ts: Updated withQuery expectations so empty elements in arrays produce key-only parameters (param) instead of parameters with an equals sign and empty value (param=).

---

Pre-merge checks | 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: encoding empty-string array elements as bare query keys.
Linked Issues check		Issue #394 requires empty-string array elements to use the scalar bare-key encoding. src/query.ts maps each array element with encodeQueryItem(key) when _value === "", and otherwise preserves ke…
Out of Scope Changes check		The source change is limited to array encoding in encodeQueryItem. The added and updated tests verify the requested empty-string serialization and confirm related existing behavior for empty arrays,…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files.

---

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[owenshen0907]

This is now ready for review. Local lint, type checks, build, and all 503 tests pass.

Could a maintainer please approve the pending fork CI and autofix CI, and review this scoped fix for #394? The serialized URL spelling change and potential overlap with #391 are described above.

Thank you for taking a look.

[abhi-byte62]

Thanks for putting this together so quickly!

• Encoding empty string array items as bare keys brings complete consistency with scalar empty string encoding (\lag\ instead of \lag=).
• Clean check in \encodeQueryItem\ preserving existing behavior for
  ull, \undefined, and truthy/falsy values.
• Comprehensive test coverage in \query.test.ts\ including round-trip assertions and mixed array items.