@sdxc/http 0.0.0-pre.1

package/dist/cache/conditional.js

@@ -0,0 +1,108 @@
+/**
+ * Answering conditional requests: when the validators a client sends back still
+ * describe the response about to be sent, the body is dropped and a `304` is
+ * returned instead, carrying only the headers a `304` is allowed to carry.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { IfNoneMatch } from "remix/headers";
+import * as StatusCode from "../status-code.js";
+import { parseHttpDate } from "./http-date.js";
+import { ifModifiedSince, isModifiedSince } from "./if-modified-since.js";
+/**
+ * Methods a `304` may answer. A conditional header on any other method is a
+ * precondition for a write, which `precondition()` handles instead.
+ */
+const CONDITIONAL_METHODS = new Set(["GET", "HEAD"]);
+/**
+ * The only headers a `304` carries, per the caching specification. `Vary` stays
+ * on the list because a shared cache without it can no longer tell which
+ * negotiated variant was validated, and may serve the wrong one.
+ */
+const NOT_MODIFIED_HEADERS = [
+    "Cache-Control",
+    "Content-Location",
+    "Date",
+    "ETag",
+    "Expires",
+    "Vary",
+];
+/**
+ * The same entity tag written with the other strength, so weak comparison
+ * matches a tag against its counterpart while the framework's own quoting and
+ * wildcard handling stays in charge of the match.
+ */
+function counterpart(tag) {
+    return tag.startsWith("W/") ? tag.slice(2) : `W/${tag}`;
+}
+/**
+ * Whether the client's `If-None-Match` covers the response's own `ETag`, under
+ * the weak comparison the specification defines for this header. A `*` matches
+ * because a representation exists at all; a response with no `ETag` can't match.
+ */
+function matchesEtag(header, tag) {
+    let ifNoneMatch = IfNoneMatch.from(header);
+    if (ifNoneMatch.matches("*"))
+        return true;
+    if (tag === null)
+        return false;
+    return ifNoneMatch.matches(tag) || ifNoneMatch.matches(counterpart(tag));
+}
+/**
+ * Whether the copy the client already holds is still current. `If-None-Match`
+ * decides whenever present; `If-Modified-Since` is consulted only in its
+ * absence, per the precedence the specification sets between the two validators.
+ */
+function isCurrent(request, response) {
+    let ifNoneMatch = request.headers.get("If-None-Match");
+    if (ifNoneMatch !== null)
+        return matchesEtag(ifNoneMatch, response.headers.get("ETag"));
+    let since = ifModifiedSince(request.headers);
+    if (since === null)
+        return false;
+    let modifiedAt = parseHttpDate(response.headers.get("Last-Modified"));
+    if (modifiedAt === null)
+        return false;
+    return !isModifiedSince(modifiedAt, since);
+}
+/**
+ * Builds the `304` for a response whose body the client already has. Cancelling
+ * the original body lets a response piped from an upstream request release its
+ * connection immediately.
+ */
+async function notModified(response) {
+    let headers = new Headers();
+    for (let name of NOT_MODIFIED_HEADERS) {
+        let value = response.headers.get(name);
+        if (value !== null)
+            headers.set(name, value);
+    }
+    if (response.body !== null && !response.body.locked)
+        await response.body.cancel();
+    return new Response(null, { ...StatusCode.NotModified, headers });
+}
+/**
+ * Downgrades a response to a `304` when the request's validators still hold.
+ * Only a `GET` or `HEAD` answered with `200` is eligible, so this runs safely
+ * at the end of any handler, using `ETag` or `Last-Modified` set on the response.
+ *
+ * @param request - The incoming request, carrying the client's validators.
+ * @param response - The response the handler produced.
+ * @returns A `304` with no body, or the original response unchanged.
+ *
+ * @example
+ * return await conditional(request, html(body, { headers }));
+ * @example
+ * let response = await conditional(request, json(payload, { headers }));
+ * response.status; // 304 when the client's ETag still matches
+ */
+export async function conditional(request, response) {
+    if (!CONDITIONAL_METHODS.has(request.method.toUpperCase()))
+        return response;
+    if (response.status !== StatusCode.Ok.status)
+        return response;
+    if (!isCurrent(request, response))
+        return response;
+    return await notModified(response);
+}

package/dist/cache/etag.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Entity tag generation: a validator derived from the bytes of a response, so a
+ * client holding a current copy is answered with a `304` instead of the body.
+ * The digest comes from `@sdxc/crypto`, keeping the hash implementation shared.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { BinaryLike, CryptoError } from "@sdxc/crypto";
+import type { Result } from "@sdxc/result";
+/**
+ * How strictly the tag identifies the bytes it was built from.
+ */
+export interface EtagOptions {
+    /**
+     * Mark the tag weak (`W/"…"`), meaning it identifies content that is
+     * semantically equivalent, tolerating minor representation differences.
+     */
+    weak?: boolean;
+}
+/**
+ * Derives an entity tag from a payload by hashing it with SHA-256. The tag is
+ * base64url of the digest, quoted, so it changes whenever the bytes do — the
+ * property that makes an `ETag` a safe cache validator.
+ *
+ * @param body - The bytes the tag must identify; text is read as UTF-8.
+ * @param options - Set `weak: true` for content that varies insignificantly
+ * between renders, such as server-rendered HTML carrying a timestamp.
+ * @returns The quoted entity tag, or the digest failure from the runtime.
+ *
+ * @example
+ * let tag = await etag(body);
+ * if (isSuccess(tag)) headers.set("ETag", tag.data);
+ * @example
+ * let tag = await etag(html, { weak: true }); // W/"47DEQpj8HBSa…"
+ */
+export declare function etag(body: BinaryLike, options?: EtagOptions): Promise<Result<string, CryptoError>>;

package/dist/cache/etag.js

@@ -0,0 +1,33 @@
+/**
+ * Entity tag generation: a validator derived from the bytes of a response, so a
+ * client holding a current copy is answered with a `304` instead of the body.
+ * The digest comes from `@sdxc/crypto`, keeping the hash implementation shared.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Base64Url, sha256 } from "@sdxc/crypto";
+import { isFailure, success } from "@sdxc/result";
+/**
+ * Derives an entity tag from a payload by hashing it with SHA-256. The tag is
+ * base64url of the digest, quoted, so it changes whenever the bytes do — the
+ * property that makes an `ETag` a safe cache validator.
+ *
+ * @param body - The bytes the tag must identify; text is read as UTF-8.
+ * @param options - Set `weak: true` for content that varies insignificantly
+ * between renders, such as server-rendered HTML carrying a timestamp.
+ * @returns The quoted entity tag, or the digest failure from the runtime.
+ *
+ * @example
+ * let tag = await etag(body);
+ * if (isSuccess(tag)) headers.set("ETag", tag.data);
+ * @example
+ * let tag = await etag(html, { weak: true }); // W/"47DEQpj8HBSa…"
+ */
+export async function etag(body, options = {}) {
+    let digest = await sha256(body);
+    if (isFailure(digest))
+        return digest;
+    let tag = `"${Base64Url.encode(digest.data)}"`;
+    return success(options.weak ? `W/${tag}` : tag);
+}

package/dist/cache/http-date.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The HTTP-date format on both directions of the wire: producing the value a
+ * `Last-Modified` validator carries, and reading back the dates clients send in
+ * conditional requests. Only the fixed IMF-fixdate spelling is accepted.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Formats a modification time as the `Last-Modified` validator for a response.
+ *
+ * HTTP dates carry whole seconds, so sub-second writes within the same second
+ * share a validator; a content-derived `ETag` is the better one when available.
+ *
+ * @param date - Modification time, as a `Date` or epoch milliseconds.
+ * @returns The time as an HTTP-date.
+ *
+ * @example
+ * headers.set("Last-Modified", lastModified(article.updatedAt));
+ * @example
+ * lastModified(new Date("2015-10-21T07:28:00Z")); // "Wed, 21 Oct 2015 07:28:00 GMT"
+ */
+export declare function lastModified(date: Date | number): string;
+/**
+ * Parses an HTTP-date header value, such as the one `If-Modified-Since` carries.
+ *
+ * A missing header and an unparsable one both return `null`, so callers fall
+ * back to serving the full body instead of asserting freshness they cannot prove.
+ *
+ * @param value - Raw header value, or `null` when the header is absent.
+ * @returns The parsed date, or `null` when there is nothing valid to compare.
+ *
+ * @example
+ * parseHttpDate(request.headers.get("If-Modified-Since"));
+ * @example
+ * parseHttpDate("yesterday"); // null
+ */
+export declare function parseHttpDate(value: string | null): Date | null;

package/dist/cache/http-date.js

@@ -0,0 +1,56 @@
+/**
+ * The HTTP-date format on both directions of the wire: producing the value a
+ * `Last-Modified` validator carries, and reading back the dates clients send in
+ * conditional requests. Only the fixed IMF-fixdate spelling is accepted.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * The one date spelling this package reads: `"Wed, 21 Oct 2015 07:28:00 GMT"`.
+ *
+ * Obsolete RFC 850 and asctime forms fail the match, because a misread date
+ * silently turns into a `304` for content that changed.
+ */
+const HTTP_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/**
+ * Formats a modification time as the `Last-Modified` validator for a response.
+ *
+ * HTTP dates carry whole seconds, so sub-second writes within the same second
+ * share a validator; a content-derived `ETag` is the better one when available.
+ *
+ * @param date - Modification time, as a `Date` or epoch milliseconds.
+ * @returns The time as an HTTP-date.
+ *
+ * @example
+ * headers.set("Last-Modified", lastModified(article.updatedAt));
+ * @example
+ * lastModified(new Date("2015-10-21T07:28:00Z")); // "Wed, 21 Oct 2015 07:28:00 GMT"
+ */
+export function lastModified(date) {
+    return new Date(date).toUTCString();
+}
+/**
+ * Parses an HTTP-date header value, such as the one `If-Modified-Since` carries.
+ *
+ * A missing header and an unparsable one both return `null`, so callers fall
+ * back to serving the full body instead of asserting freshness they cannot prove.
+ *
+ * @param value - Raw header value, or `null` when the header is absent.
+ * @returns The parsed date, or `null` when there is nothing valid to compare.
+ *
+ * @example
+ * parseHttpDate(request.headers.get("If-Modified-Since"));
+ * @example
+ * parseHttpDate("yesterday"); // null
+ */
+export function parseHttpDate(value) {
+    if (value === null)
+        return null;
+    if (!HTTP_DATE_PATTERN.test(value))
+        return null;
+    let timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp))
+        return null;
+    return new Date(timestamp);
+}

package/dist/cache/if-modified-since.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `If-Modified-Since` side of conditional requests: reading the date a
+ * client claims its copy was made, and comparing it against a modification time
+ * at the second precision the header can express.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Reads the `If-Modified-Since` date from a request's headers.
+ *
+ * @param headers - Headers of the incoming request.
+ * @returns The date the client stored its copy, or `null` when the header is
+ * absent or not a valid HTTP-date.
+ *
+ * @example
+ * let since = ifModifiedSince(request.headers);
+ * if (since !== null && !isModifiedSince(article.updatedAt, since)) return notModified();
+ */
+export declare function ifModifiedSince(headers: Headers): Date | null;
+/**
+ * Whether a resource changed after the copy a client already holds.
+ *
+ * Both times are compared as whole seconds, so a modification in the same
+ * second as the client's copy counts as unmodified, keeping repeat requests cheap.
+ *
+ * @param modifiedAt - When the resource last changed.
+ * @param since - The date the client sent in `If-Modified-Since`.
+ * @returns `true` when the resource is newer and the full body must be sent.
+ *
+ * @example
+ * isModifiedSince(new Date("2015-10-21T07:28:01Z"), new Date("2015-10-21T07:28:00Z")); // true
+ * @example
+ * isModifiedSince(new Date("2015-10-21T07:28:00Z"), new Date("2015-10-21T07:28:00Z")); // false
+ */
+export declare function isModifiedSince(modifiedAt: Date | number, since: Date | number): boolean;

package/dist/cache/if-modified-since.js

@@ -0,0 +1,53 @@
+/**
+ * The `If-Modified-Since` side of conditional requests: reading the date a
+ * client claims its copy was made, and comparing it against a modification time
+ * at the second precision the header can express.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { parseHttpDate } from "./http-date.js";
+/** Milliseconds in the one second an HTTP-date can express. */
+const SECOND_MS = 1000;
+/**
+ * Truncates a time to whole seconds, the only precision an HTTP-date carries.
+ *
+ * Comparing raw milliseconds would flag a same-second write as modified,
+ * forcing a full body for a copy that is already byte-identical.
+ */
+function toWholeSeconds(value) {
+    let time = value instanceof Date ? value.getTime() : value;
+    return Math.floor(time / SECOND_MS);
+}
+/**
+ * Reads the `If-Modified-Since` date from a request's headers.
+ *
+ * @param headers - Headers of the incoming request.
+ * @returns The date the client stored its copy, or `null` when the header is
+ * absent or not a valid HTTP-date.
+ *
+ * @example
+ * let since = ifModifiedSince(request.headers);
+ * if (since !== null && !isModifiedSince(article.updatedAt, since)) return notModified();
+ */
+export function ifModifiedSince(headers) {
+    return parseHttpDate(headers.get("If-Modified-Since"));
+}
+/**
+ * Whether a resource changed after the copy a client already holds.
+ *
+ * Both times are compared as whole seconds, so a modification in the same
+ * second as the client's copy counts as unmodified, keeping repeat requests cheap.
+ *
+ * @param modifiedAt - When the resource last changed.
+ * @param since - The date the client sent in `If-Modified-Since`.
+ * @returns `true` when the resource is newer and the full body must be sent.
+ *
+ * @example
+ * isModifiedSince(new Date("2015-10-21T07:28:01Z"), new Date("2015-10-21T07:28:00Z")); // true
+ * @example
+ * isModifiedSince(new Date("2015-10-21T07:28:00Z"), new Date("2015-10-21T07:28:00Z")); // false
+ */
+export function isModifiedSince(modifiedAt, since) {
+    return toWholeSeconds(modifiedAt) > toWholeSeconds(since);
+}

package/dist/cache/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Public surface of the cache subpath: policies that decide who may store a
+ * response and for how long, validators that identify its content, and the
+ * conditional-request handling that turns a current client copy into a `304`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { EtagOptions } from "./etag.js";
+export type { PrivatePolicyOptions } from "./policies.js";
+export type { CacheVisibility, PolicyOptions } from "./policy.js";
+export type { PreconditionOptions } from "./precondition.js";
+export { conditional } from "./conditional.js";
+export { etag } from "./etag.js";
+export { lastModified } from "./http-date.js";
+export { ifModifiedSince, isModifiedSince } from "./if-modified-since.js";
+export { Policies } from "./policies.js";
+export { policy } from "./policy.js";
+export { precondition, PreconditionFailedError } from "./precondition.js";
+export { vary } from "./vary.js";

package/dist/cache/index.js

@@ -0,0 +1,16 @@
+/**
+ * Public surface of the cache subpath: policies that decide who may store a
+ * response and for how long, validators that identify its content, and the
+ * conditional-request handling that turns a current client copy into a `304`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { conditional } from "./conditional.js";
+export { etag } from "./etag.js";
+export { lastModified } from "./http-date.js";
+export { ifModifiedSince, isModifiedSince } from "./if-modified-since.js";
+export { Policies } from "./policies.js";
+export { policy } from "./policy.js";
+export { precondition, PreconditionFailedError } from "./precondition.js";
+export { vary } from "./vary.js";

package/dist/cache/policies.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The named policies that cover the recurring cases, so the safe answer is also
+ * the short one to write. Each one is a reviewable decision with a name rather
+ * than a set of directives assembled again in every route that serves content.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { CacheControl } from "remix/headers";
+/**
+ * Ages the `private` policy needs, kept as an object so the age is named at the
+ * call site instead of appearing as a bare positional argument.
+ */
+export interface PrivatePolicyOptions {
+    /** How long the client's own cache may reuse the response. */
+    maxAge: DurationInput;
+}
+/**
+ * The recurring cache policies, each named after the outcome it produces.
+ *
+ * Only the exceptional case, a response a shared cache may store, is written out
+ * with `policy({ visibility: "public", … })`; everything routine has a name here.
+ *
+ * @example
+ * headers.set("Cache-Control", Policies.immutable());
+ */
+export declare class Policies {
+    /**
+     * Nothing stores the response, anywhere.
+     *
+     * The right answer for one-time payloads and anything a cache holding a copy
+     * would turn into a security problem, such as a token exchange response.
+     *
+     * @returns `no-store`.
+     * @example
+     * Policies.noStore().toString(); // "no-store"
+     */
+    static noStore(): CacheControl;
+    /**
+     * Only the client that made the request may store the response.
+     *
+     * The age is required so a browser can't fall back to its own heuristic
+     * freshness for user-specific content.
+     *
+     * @param options - The client-side freshness lifetime.
+     * @returns `private, max-age=N`.
+     * @example
+     * Policies.private({ maxAge: "5 minutes" }).toString(); // "private, max-age=300"
+     */
+    static private(options: PrivatePolicyOptions): CacheControl;
+    /**
+     * Any cache may keep the response for a year without ever revalidating it.
+     *
+     * Correct only for URLs whose content never changes — meaning fingerprinted
+     * asset names — since any other URL risks caches serving a stale copy forever.
+     *
+     * @returns `public, max-age=31536000, immutable`.
+     * @example
+     * Policies.immutable().toString(); // "public, max-age=31536000, immutable"
+     */
+    static immutable(): CacheControl;
+    /**
+     * The response may be stored only by its own client, checked with the origin
+     * before every reuse, which is what makes validators worth generating.
+     * Pairing `private` with `no-cache` keeps a shared cache from storing it too.
+     *
+     * @returns `private, no-cache`.
+     * @example
+     * Policies.revalidate().toString(); // "private, no-cache"
+     */
+    static revalidate(): CacheControl;
+}

package/dist/cache/policies.js

@@ -0,0 +1,78 @@
+/**
+ * The named policies that cover the recurring cases, so the safe answer is also
+ * the short one to write. Each one is a reviewable decision with a name rather
+ * than a set of directives assembled again in every route that serves content.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { policy } from "./policy.js";
+/**
+ * Freshness lifetime for fingerprinted assets: one year, the longest value the
+ * caching specification asks caches to honor. Expressed in days because a year
+ * has no fixed length and durations only count fixed spans.
+ */
+const IMMUTABLE_MAX_AGE = "365 days";
+/**
+ * The recurring cache policies, each named after the outcome it produces.
+ *
+ * Only the exceptional case, a response a shared cache may store, is written out
+ * with `policy({ visibility: "public", … })`; everything routine has a name here.
+ *
+ * @example
+ * headers.set("Cache-Control", Policies.immutable());
+ */
+export class Policies {
+    /**
+     * Nothing stores the response, anywhere.
+     *
+     * The right answer for one-time payloads and anything a cache holding a copy
+     * would turn into a security problem, such as a token exchange response.
+     *
+     * @returns `no-store`.
+     * @example
+     * Policies.noStore().toString(); // "no-store"
+     */
+    static noStore() {
+        return policy({ noStore: true });
+    }
+    /**
+     * Only the client that made the request may store the response.
+     *
+     * The age is required so a browser can't fall back to its own heuristic
+     * freshness for user-specific content.
+     *
+     * @param options - The client-side freshness lifetime.
+     * @returns `private, max-age=N`.
+     * @example
+     * Policies.private({ maxAge: "5 minutes" }).toString(); // "private, max-age=300"
+     */
+    static private(options) {
+        return policy({ visibility: "private", maxAge: options.maxAge });
+    }
+    /**
+     * Any cache may keep the response for a year without ever revalidating it.
+     *
+     * Correct only for URLs whose content never changes — meaning fingerprinted
+     * asset names — since any other URL risks caches serving a stale copy forever.
+     *
+     * @returns `public, max-age=31536000, immutable`.
+     * @example
+     * Policies.immutable().toString(); // "public, max-age=31536000, immutable"
+     */
+    static immutable() {
+        return policy({ visibility: "public", maxAge: IMMUTABLE_MAX_AGE, immutable: true });
+    }
+    /**
+     * The response may be stored only by its own client, checked with the origin
+     * before every reuse, which is what makes validators worth generating.
+     * Pairing `private` with `no-cache` keeps a shared cache from storing it too.
+     *
+     * @returns `private, no-cache`.
+     * @example
+     * Policies.revalidate().toString(); // "private, no-cache"
+     */
+    static revalidate() {
+        return policy({ visibility: "private", noCache: true });
+    }
+}

package/dist/cache/policy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Builds `Cache-Control` values from a description of intent: who may store the
+ * response, and for how long, with every age written as a duration instead of a
+ * bare number of seconds. Serialization is left to the framework header class.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import { CacheControl } from "remix/headers";
+/**
+ * Who is allowed to store the response.
+ *
+ * An edge cache sitting in front of the origin can serve one client's body to
+ * another once `public` is set, so the call site always states it explicitly.
+ */
+export type CacheVisibility = "public" | "private";
+/**
+ * The policy description a response declares.
+ *
+ * Every age is a duration, so `"1 hour"` reads as an hour at the call site and
+ * converts once; a zero value emits its directive, omission emits none.
+ */
+export interface PolicyOptions {
+    /** Who may store the response; omitted means neither directive is emitted. */
+    visibility?: CacheVisibility;
+    /** How long any cache may reuse the response without revalidating. */
+    maxAge?: DurationInput;
+    /** How long a shared cache may reuse it, overriding `maxAge` for that cache. */
+    sMaxAge?: DurationInput;
+    /** How long a stale response may be served while it is revalidated in the background. */
+    staleWhileRevalidate?: DurationInput;
+    /** How long a stale response may be served after the origin errors. */
+    staleIfError?: DurationInput;
+    /** Store the response, but revalidate it with the origin before every reuse. */
+    noCache?: boolean;
+    /** Do not store the response anywhere, in any cache. */
+    noStore?: boolean;
+    /** Forbid intermediaries from transforming the payload (recompressing images, for example). */
+    noTransform?: boolean;
+    /** Once stale, the response must be revalidated before it can be reused again. */
+    mustRevalidate?: boolean;
+    /** Same as `mustRevalidate`, but binding on shared caches only. */
+    proxyRevalidate?: boolean;
+    /** The body will never change while fresh, so revalidation can be skipped entirely. */
+    immutable?: boolean;
+}
+/**
+ * Turns a policy description into a `Cache-Control` header value.
+ *
+ * The result is the framework's own type, so it can be handed to anything
+ * that accepts it, read back field by field, or serialized via `toString()`.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns A `CacheControl` carrying only the directives that were asked for.
+ *
+ * @example
+ * headers.set("Cache-Control", policy({ visibility: "public", maxAge: "1 hour" }));
+ * @example
+ * policy({ visibility: "public", maxAge: "1 hour", sMaxAge: "1 day" }).toString();
+ * // "public, max-age=3600, s-maxage=86400"
+ */
+export declare function policy(options?: PolicyOptions): CacheControl;

package/dist/cache/policy.js

@@ -0,0 +1,54 @@
+/**
+ * Builds `Cache-Control` values from a description of intent: who may store the
+ * response, and for how long, with every age written as a duration instead of a
+ * bare number of seconds. Serialization is left to the framework header class.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toSeconds } from "@sdxc/duration";
+import { CacheControl } from "remix/headers";
+/**
+ * Turns a policy description into a `Cache-Control` header value.
+ *
+ * The result is the framework's own type, so it can be handed to anything
+ * that accepts it, read back field by field, or serialized via `toString()`.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns A `CacheControl` carrying only the directives that were asked for.
+ *
+ * @example
+ * headers.set("Cache-Control", policy({ visibility: "public", maxAge: "1 hour" }));
+ * @example
+ * policy({ visibility: "public", maxAge: "1 hour", sMaxAge: "1 day" }).toString();
+ * // "public, max-age=3600, s-maxage=86400"
+ */
+export function policy(options = {}) {
+    let init = {};
+    if (options.visibility === "public")
+        init.public = true;
+    if (options.visibility === "private")
+        init.private = true;
+    if (options.maxAge !== undefined)
+        init.maxAge = toSeconds(options.maxAge);
+    if (options.sMaxAge !== undefined)
+        init.sMaxage = toSeconds(options.sMaxAge);
+    if (options.staleWhileRevalidate !== undefined) {
+        init.staleWhileRevalidate = toSeconds(options.staleWhileRevalidate);
+    }
+    if (options.staleIfError !== undefined)
+        init.staleIfError = toSeconds(options.staleIfError);
+    if (options.noCache)
+        init.noCache = true;
+    if (options.noStore)
+        init.noStore = true;
+    if (options.noTransform)
+        init.noTransform = true;
+    if (options.mustRevalidate)
+        init.mustRevalidate = true;
+    if (options.proxyRevalidate)
+        init.proxyRevalidate = true;
+    if (options.immutable)
+        init.immutable = true;
+    return new CacheControl(init);
+}