perf: improve Headers class performance

[anonrig]

This relates to...

N/A

Rationale

Headers is on the fetch / Request / Response hot path. The current implementation pays for WebIDL conversion, token validation, and toLowerCase() as separate passes, and stores every entry as a { name, value } object.

Changes

• Combine ByteString conversion, HTTP token validation, and lowercasing into a single pass.
• Fast-path common lowercase names (content-type, accept, authorization, …) on get / has / delete.
• Store values as strings in the internal Map instead of { name, value } objects. Original casing is kept in a side table only when it differs from the lowercase name.
• Copy an existing Headers instance by cloning the list instead of re-validating every entry.
• Keep the existing fetch spec comments next to the new hot-path code. No changes outside lib/web/fetch/headers.js.

No intended behavioral change. Guard handling, set-cookie / getSetCookie(), iteration order, and original-name casing on the wire are preserved.

Features

N/A

Bug Fixes

N/A

Breaking Changes and Deprecations

N/A

Benchmark

Measured with the source Headers class (Node v22.14.0, 200k iterations, paired old vs new):

Operation	Before	After	Change
get (custom name)	18.4M ops/s	77.9M ops/s	4.2x
get (content-type)	17.6M ops/s	56.2M ops/s	3.2x
has	16.7M ops/s	80.7M ops/s	4.8x
set	15.4M ops/s	25.2M ops/s	+64%
new Headers(headers)	1.12M ops/s	1.72M ops/s	+54%
new Headers()	23.7M ops/s	23.3M ops/s	~same
append	4.36M ops/s	4.33M ops/s	~same
iterate	5.05M ops/s	5.15M ops/s	~same

Status

• I have read and agreed to the Developer's Certificate of Origin
• Tested
• Benchmarked (optional)
• Documented
• Review ready
• In review
• Merge ready

Tested locally:

node --test test/fetch/headers.js test/fetch/headers-inspect-custom.js test/fetch/headerslist-sortedarray.js test/fetch/headers-case.js

All 70 tests passed, including the 4000-iteration toSortedArray fast/slow paths and the fetch cloning cases.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.51100% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.48%. Comparing base (f387057) to head (ab9bd62).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/web/fetch/headers.js	99.51%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5699      +/-   ##
==========================================
+ Coverage   93.47%   93.48%   +0.01%     
==========================================
  Files         110      110              
  Lines       38846    39104     +258     
==========================================
+ Hits        36310    36557     +247     
- Misses       2536     2547      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mcollina]

Adding the benchmarks somewhere will be good.

Also, lint is failing.

@KhafraDev I'm generically ok with these improvements. However it's quite substantial in the code changes. Take a look.

[anonrig]

Addressed the review feedback:

• Lint: removed unused appendHeader (no-unused-vars).
• Benchmarks: added benchmarks/fetch/headers-methods.mjs for construct / get / set / append / has / delete / iterate. Existing iterator benches now clear sortedMap instead of the old private symbol.

[mcollina]

Can you fix the metadata of the commits? Cursor cannot signoff commits.

[anonrig]

Rewrote the commits so author, committer, and Signed-off-by are Yagiz Nizipli yagiz@nizipli.com.

[mcollina]

lgtm

[mcollina]

@tsctx @KhafraDev ptal

[tsctx]

One of the main advantages of the original implementation is that it closely follows the specification, with each step represented explicitly in the code. This keeps the maintenance cost low, makes it straightforward to adapt the implementation to future specification changes, and makes it easier to trace errors back to the relevant step.

The proposed changes also introduce a separate implementation of logic that is currently shared. This duplicates the same behavior and error messages across multiple places, increasing the maintenance burden and creating a risk of inconsistencies over time.

Maintaining a close correspondence with the specification is particularly important because the specification is a living standard. Although Headers is relatively stable compared with other areas, it may still evolve over time.

While performance improvements are certainly appealing, I believe the overall ROI of these changes is low. For Headers, iteration performance appears to be more important in typical usage. Operations such as get and append are generally performed only a limited number of times per instance, so optimizing them does not appear to provide much practical benefit, especially when weighed against the additional complexity and maintenance cost.

There are also several behavioral regressions that could result in unexpected behavior. Some of the proposed changes are valuable. However, given these trade-offs, I do not think the changes as a whole are worthwhile.