No actionable comments were generated in the recent review. 🎉

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.

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

coverage: 100.0%. remained the same — well-known-headers-set into master

@pullfrog evaluate the approach thoughtfully: explain the impact on memory consumption and performance both for API runtime and when running Documentation generator.

Posted a detailed analysis of the approach's impact on memory consumption and performance. Key findings: the lazy Set pattern saves ~5 KB at API runtime (avoids eager array allocation), the 3.55x lookup speedup is real but absolute gains are negligible in practice (sub-microsecond per call), and the bundle size is effectively unchanged (+18 bytes). Also identified that errors.ts uses a value import of OpenAPIContext (an interface) which forces the entire documentation-helpers chain into the runtime bundle.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

Analysis: Impact on Memory and Performance

The import chain problem

The PR description mentions the array is "statically imported while only used by Documentation (not API runtime)." This is true at the source level — only documentation-helpers.ts imports well-known-headers.ts, and defaultIsHeader is only called during OpenAPI spec generation.

However, the well-known headers module cannot be excluded from the API runtime because the build produces a single bundle (dist/index.js), and the import graph forces inclusion regardless:

index.ts → errors.ts → documentation-helpers.ts → well-known-headers.ts

The bridge is errors.ts:3:

import { OpenAPIContext } from "./documentation-helpers";

This is a value import of an interface (could be import type), which forces the bundler to include the entire documentation-helpers.ts module and all its transitive dependencies. The header strings end up in the bundle either way.

Memory consumption

Both before and after this PR, the minified bundle contains the same ~2.7 KB string of dot-separated header names:

The lazy pattern does save memory at API runtime startup — the Set (which uses ~8–10 KB due to hash table overhead) is never constructed unless Documentation is instantiated. On master, the array (~5 KB) is created eagerly at module load.

Net savings for API-only runtime: ~5 KB (the array is never allocated). This is real but modest.

When Documentation is used: The Set costs more memory than the array (~8–10 KB vs ~5 KB due to hash table overhead), but the array is no longer created at all, so the net difference is roughly +3–5 KB. This is negligible for a documentation generation process.

Lookup performance

The benchmark confirms Set.has is ~3.55x faster than Array.includes for the worst-case lookup (x-frame-options, near the end of the 204-element list). This is consistent with O(1) vs O(n) for n=204.

In practice, defaultIsHeader is called once per input property per endpoint during Documentation construction. For a typical API with, say, 50 endpoints averaging 5 input properties each, that's ~250 calls. At ~0.0002 ms per Set.has call vs ~0.0002 ms per Array.includes call (both are sub-microsecond at this scale), the total wall-clock difference for the entire documentation generation is on the order of microseconds — unmeasurable in real use.

The performance gain is real in relative terms (3.55x) but the absolute improvement is negligible because documentation generation is dominated by JSON Schema processing, not header lookups.

The lazy initialization pattern

The let cache + cache ??= new Set(...) pattern is clean and works correctly:

• No extra dependency (R.once was rightly discarded)
• The module-level let is safe because ESM modules are singletons
• The ??= ensures the Set is constructed at most once

Summary

The approach is sound. The primary benefit is avoiding eager allocation of data that only the Documentation generator needs. The lookup speedup is a nice theoretical improvement but won't be measurable in practice.

A follow-up worth considering: changing errors.ts:3 to import type { OpenAPIContext } would break the runtime import chain from errors.ts into documentation-helpers.ts, which could let a future code-splitting setup fully exclude documentation code from the API runtime bundle.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

this may accompany another Set lookup in #3344