feat(writeEarlyHints): add Link: rel:preload headers as fallback

[kricsleo]

resolves #1279

Summary by CodeRabbit

• New Features

  • writeEarlyHints now accepts array values to send multiple hint entries.

• Bug Fixes

  • Improved fallback in environments without native early hints to set Link headers for CDN compatibility and avoid native-call wrapping.

• Documentation

  • Clarified fallback behavior when native early hints are unavailable.

• Tests

  • Added tests covering writeEarlyHints and fallback scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds support for array-valued hints in writeEarlyHints, prefers native res.writeEarlyHints when available, and adds a CDN-friendly fallback that emits Link headers when native early hints are absent. Documentation and tests were updated to reflect the behavior.

Changes

Cohort / File(s)	Summary
Core Implementation src/utils/response.ts	Changed writeEarlyHints signature to accept Record<string, string | string[]>; uses native early hints when available; fallback emits only Link headers (supports multiple values); added doc comment about fallback behavior.
Documentation docs/2.utils/2.response.md	Added explanatory note describing fallback to response headers (Link: rel=preload) for runtimes without native early hints.
Tests test/utils.test.ts	Added tests for writeEarlyHints verifying Link-header fallback for single and multi-value hints; includes node-target conditional skip; exported function added via src/index.ts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• feat(writeEarlyHints): add Link: rel:preload headers as fallback #1288 — Implements the same writeEarlyHints changes: allowing array values and adding a Link: rel=preload fallback with matching docs and tests.

Poem

🐇 I nudged a hint into the spring,
Native doors open, or Link tags sing.
If runtimes nap, CDNs take flight,
Preloads hop forward, swift and light.
✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding Link headers as a fallback for writeEarlyHints when native support is unavailable.
Linked Issues check	✅ Passed	The PR implements the feature requested in issue #1279 by adding Link: rel=preload header fallbacks when native writeEarlyHints is unavailable.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the writeEarlyHints fallback feature: type signature update, implementation logic, documentation, and tests.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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 and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/h3js/h3@1288

commit: d1cdca3

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/utils/response.ts`:
- Around line 69-85: The fallback currently appends all hint headers from hints
into event.res.headers using event.res.headers.append, which can leak
undesirable headers (e.g., Set-Cookie); restrict the fallback to only propagate
Link headers: check for the "link" header key (case-insensitive) in hints and
append only those values (handling both string and string[] cases) via
event.res.headers.append, skipping any other hint names; keep the native early
hints branch (event.runtime?.node?.res?.writeEarlyHints) unchanged.

[pi0]

Thanks!