feat(cachecontrol): add second target argument to cacheControl

[maiieul]

Add second target argument to cacheControl for backwards compatibility.

Fix #5192

Overview

What is it?

• Feature / enhancement
• Bug
• Docs / tests / types / typos

Description

Added a second target parameter to cacheControl to fix #5192.

Ex:

cacheControl({
  maxAge: 5,
  staleWhileRevalidate: 60 * 60 * 24 * 365,
}, "CDN-Cache-Control");

The API shouldn't change much, so I simply added a second parameter instead of converting it to something like

cacheControl({
  options: {
    maxAge: 5,
    staleWhileRevalidate: 60 * 60 * 24 * 365,
  },
  target: "CDN-Cache-Control",
});

This way it is backward compatible and reduces boilerplate as setting the second target argument is probably usually an edge case.

I added the most common values to the CacheControlTarget type for autocomplete.

Use cases and why

It's not really a bug fix, but it felt buggy to see Vercel Edge strip "stale-while-revalidate" from my "Cache-Control" headers (see #5192). So this needed documentation and I thought that improving cacheControl was necessary to allow users to keep using this convenience method even for that situation.

Use cases:

1. Ability to set stale-while-revalidate or s-maxage on the Browser with Vercel Edge, allowing the browser to serve the response from its cache while fetching another in the background.
2. Ability to set different cache controls on the browser and on the CDN

Checklist:

• My code follows the developer guidelines of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• Added new tests to cover the fix / functionality

[netlify]

👷 Deploy request for qwik-insights pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	b08d8b5

[maiieul]

Forgot to mention one thing:

CacheControlOptions was not exported by request-handler/index.ts, so I didn't export CacheControlTarget type.

[mhevery]

Thank you for you contribution! This 🎸 !