@sdxc/http 2026.10.24 → 2026.10.25

package/README.md

@@ -3,8 +3,8 @@
 Response builders, content negotiation, and HTTP caching for the Fetch API.
 
 Each concern is its own entry point — status codes, content types, response builders,
-`Accept` negotiation, `Cache-Control` and validators, and `HEAD` middleware — so a handler
-imports only the surface it uses.
+`Accept` negotiation, `Cache-Control` and validators, deprecation notices, and `HEAD`
+middleware — so a handler imports only the surface it uses.
 
 ## Installation
 
@@ -16,6 +16,8 @@ It installs alongside [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/resul
 `Result` that `etag` and `precondition` answer),
 [`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration) (cache ages),
 [`@sdxc/crypto`](https://www.npmjs.com/package/@sdxc/crypto),
+[`@sdxc/structured-fields`](https://www.npmjs.com/package/@sdxc/structured-fields),
+[`@sdxc/link-header`](https://www.npmjs.com/package/@sdxc/link-header) (deprecation notices),
 [`@sdxc/location`](https://www.npmjs.com/package/@sdxc/location) and
 [`remix`](https://www.npmjs.com/package/remix) (typed headers and the router).
 
@@ -242,6 +244,26 @@ Calls the handler for the most preferred type, then `default`, then answers
 `406 Not Acceptable`. `respond.Handlers` holds an optional `() => Response` per shorthand
 plus `default`.
 
+### `@sdxc/http/deprecation`
+
+#### `setDeprecation(headers: Headers, notice: DeprecationNotice): Result<void, DeprecationNoticeError>`
+
+Writes the RFC 9745 `Deprecation` and RFC 8594 `Sunset` fields and their `deprecation` and
+`sunset` links, keeping the response's other links. Fails for a sunset earlier than the
+deprecation.
+
+```typescript
+setDeprecation(response.headers, {
+	deprecation: new Date("2026-12-01T00:00:00Z"),
+	sunset: new Date("2027-06-01T00:00:00Z"),
+	deprecationLink: "https://example.com/changelog",
+});
+```
+
+#### `getDeprecation(headers: Headers): DeprecationNotice | null`
+
+Reads the notice back on the client, leaving out any field that does not parse.
+
 ### `@sdxc/http/cache`
 
 Built on the typed `CacheControl` header from `remix/headers`. Every age is a duration
@@ -260,6 +282,13 @@ policy({ visibility: "public", maxAge: "1 hour", sMaxAge: "1 day" }).toString();
 // "public, max-age=3600, s-maxage=86400"
 ```
 
+#### `targetedPolicy(options?: PolicyOptions): string` and `parseTargetedPolicy(value: string | null): CacheControl | null`
+
+Write and read [RFC 9213](https://www.rfc-editor.org/rfc/rfc9213) targeted fields such as
+`CDN-Cache-Control`, as Structured Field Dictionaries, to give an edge its own lifetime
+(`targetedPolicy({ maxAge: "1 day" })` is `"max-age=86400"`). The parser answers `null` for
+a field a cache ignores: absent, empty or invalid.
+
 #### `Policies`
 
 The recurring policies, each returning a `CacheControl`:

package/dist/cache/index.d.ts

@@ -2,6 +2,7 @@
  * 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`.
+ * Targeted fields give an edge cache its own lifetime apart from the browser's.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -17,4 +18,5 @@ 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 { parseTargetedPolicy, targetedPolicy } from "./targeted.js";
 export { vary } from "./vary.js";

package/dist/cache/index.js

@@ -2,6 +2,7 @@
  * 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`.
+ * Targeted fields give an edge cache its own lifetime apart from the browser's.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -13,4 +14,5 @@ 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 { parseTargetedPolicy, targetedPolicy } from "./targeted.js";
 export { vary } from "./vary.js";

package/dist/cache/targeted.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Writes and reads RFC 9213 targeted cache fields such as `CDN-Cache-Control`, which give one
+ * class of cache (a CDN, or one vendor's edge) its own lifetime apart from `Cache-Control`.
+ * They are Structured Field Dictionaries, so both directions go through that grammar.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { CacheControl } from "remix/headers";
+import type { PolicyOptions } from "./policy.js";
+/**
+ * Builds a targeted cache field value from the same description `policy()` takes, so an
+ * edge-only lifetime reads like any other. An empty description yields `""`, which caches
+ * ignore, leaving `Cache-Control` in charge.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns The Structured Field Dictionary text for `CDN-Cache-Control` and its kin.
+ * @example
+ * headers.set("CDN-Cache-Control", targetedPolicy({ maxAge: "1 day" })); // "max-age=86400"
+ */
+export declare function targetedPolicy(options?: PolicyOptions): string;
+/**
+ * Reads a targeted cache field. `null` means a cache ignores the field (absent, empty, or not a
+ * valid Dictionary) and falls back to the next one; any other result governs, even with no
+ * known directive. Parameters, unknown directives and ill-typed values are skipped.
+ *
+ * @param value - The field value, as `Headers#get` returns it.
+ * @returns The directives the field sets, or `null` when the field is ignored.
+ * @example
+ * parseTargetedPolicy(response.headers.get("CDN-Cache-Control"))?.maxAge; // 86400
+ */
+export declare function parseTargetedPolicy(value: string | null | undefined): CacheControl | null;

package/dist/cache/targeted.js

@@ -0,0 +1,112 @@
+/**
+ * Writes and reads RFC 9213 targeted cache fields such as `CDN-Cache-Control`, which give one
+ * class of cache (a CDN, or one vendor's edge) its own lifetime apart from `Cache-Control`.
+ * They are Structured Field Dictionaries, so both directions go through that grammar.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { parse, stringify } from "@sdxc/structured-fields";
+import { CacheControl } from "remix/headers";
+import { policy } from "./policy.js";
+/** Directives whose value is an Integer number of seconds, in the order they are written. */
+const AGE_DIRECTIVES = [
+    ["max-age", "maxAge"],
+    ["s-maxage", "sMaxage"],
+    ["stale-while-revalidate", "staleWhileRevalidate"],
+    ["stale-if-error", "staleIfError"],
+];
+/** Directives written as a bare key, in the order they are written. */
+const FLAG_DIRECTIVES = [
+    ["public", "public"],
+    ["private", "private"],
+    ["no-cache", "noCache"],
+    ["no-store", "noStore"],
+    ["no-transform", "noTransform"],
+    ["must-revalidate", "mustRevalidate"],
+    ["proxy-revalidate", "proxyRevalidate"],
+    ["must-understand", "mustUnderstand"],
+    ["immutable", "immutable"],
+];
+/**
+ * Directives that may instead carry a String listing field names. A cache reading one takes
+ * the unqualified directive, which withholds the whole response rather than some fields.
+ */
+const QUALIFIABLE_DIRECTIVES = new Set(["private", "no-cache"]);
+/** The largest Integer a Structured Field can carry. */
+const MAX_INTEGER = 999_999_999_999_999;
+/**
+ * Builds a targeted cache field value from the same description `policy()` takes, so an
+ * edge-only lifetime reads like any other. An empty description yields `""`, which caches
+ * ignore, leaving `Cache-Control` in charge.
+ *
+ * @param options - Visibility, ages, and directives to emit; all optional.
+ * @returns The Structured Field Dictionary text for `CDN-Cache-Control` and its kin.
+ * @example
+ * headers.set("CDN-Cache-Control", targetedPolicy({ maxAge: "1 day" })); // "max-age=86400"
+ */
+export function targetedPolicy(options = {}) {
+    let control = policy(options);
+    let dictionary = {};
+    for (let [name, key] of FLAG_DIRECTIVES)
+        if (control[key])
+            dictionary[name] = true;
+    for (let [name, key] of AGE_DIRECTIVES) {
+        let seconds = control[key];
+        if (seconds !== undefined)
+            dictionary[name] = Math.min(Math.max(seconds, 0), MAX_INTEGER);
+    }
+    let text = stringify(dictionary, "dictionary");
+    return isFailure(text) ? "" : text.data;
+}
+/**
+ * Reads a targeted cache field. `null` means a cache ignores the field (absent, empty, or not a
+ * valid Dictionary) and falls back to the next one; any other result governs, even with no
+ * known directive. Parameters, unknown directives and ill-typed values are skipped.
+ *
+ * @param value - The field value, as `Headers#get` returns it.
+ * @returns The directives the field sets, or `null` when the field is ignored.
+ * @example
+ * parseTargetedPolicy(response.headers.get("CDN-Cache-Control"))?.maxAge; // 86400
+ */
+export function parseTargetedPolicy(value) {
+    if (value === null || value === undefined)
+        return null;
+    let parsed = parse(value, "dictionary");
+    if (isFailure(parsed))
+        return null;
+    let members = Object.entries(parsed.data);
+    if (members.length === 0)
+        return null;
+    let init = {};
+    for (let [name, member] of members) {
+        if ("items" in member)
+            continue;
+        readDirective(init, name, member.value);
+    }
+    return new CacheControl(init);
+}
+/**
+ * Copies one directive into the init when its value has the type the directive allows: a
+ * non-negative Integer for an age, Boolean true for a flag, or a String for `private` and
+ * `no-cache`. Anything else is skipped, since coercing it would diverge from other caches.
+ *
+ * @param init - The directives read so far.
+ * @param name - The directive's key in the Dictionary.
+ * @param value - The member's bare value.
+ */
+function readDirective(init, name, value) {
+    let age = AGE_DIRECTIVES.find(([directive]) => directive === name);
+    if (age) {
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+            init[age[1]] = value;
+        return;
+    }
+    let flag = FLAG_DIRECTIVES.find(([directive]) => directive === name);
+    if (!flag)
+        return;
+    if (value === true || (QUALIFIABLE_DIRECTIVES.has(name) && typeof value === "string")) {
+        init[flag[1]] = true;
+    }
+}

package/dist/deprecation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Deprecation signalling on the Fetch API: the RFC 9745 `Deprecation` field, the RFC 8594
+ * `Sunset` field and their `deprecation` and `sunset` link relations, written by a server
+ * announcing a resource's retirement and read back by a client watching for one.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+/**
+ * What a response announces about its resource's retirement. Every member is optional:
+ * a resource may publish its deprecation policy link long before it names a date.
+ */
+export interface DeprecationNotice {
+    /** When the resource was deprecated, or will be when the date is in the future. */
+    deprecation?: Date;
+    /** When the resource is expected to stop answering; never earlier than `deprecation`. */
+    sunset?: Date;
+    /** Documentation of the deprecation and how to migrate, linked with `rel="deprecation"`. */
+    deprecationLink?: string;
+    /** Documentation of the retirement policy, linked with `rel="sunset"`. */
+    sunsetLink?: string;
+}
+/**
+ * A notice the fields cannot carry: an invalid `Date`, or a sunset earlier than the
+ * deprecation, which RFC 9745 forbids a server to send.
+ */
+export declare class DeprecationNoticeError extends Error {
+    name: "DeprecationNoticeError";
+}
+/**
+ * Writes a notice onto response headers, replacing any `Deprecation`, `Sunset` and
+ * `deprecation`/`sunset` links already there and keeping every other link. Dates are
+ * truncated to whole seconds, the precision both fields carry.
+ *
+ * @param headers - The response headers to write.
+ * @param notice - What to announce.
+ * @returns Success once written, or why the notice is invalid, leaving `headers` untouched.
+ * @example setDeprecation(response.headers, { deprecation: new Date("2026-12-01T00:00:00Z"), sunset: new Date("2027-06-01T00:00:00Z"), deprecationLink: "https://example.com/changelog" });
+ * @example setDeprecation(response.headers, { deprecationLink: "https://example.com/deprecation-policy" });
+ */
+export declare function setDeprecation(headers: Headers, notice: DeprecationNotice): Result<void, DeprecationNoticeError>;
+/**
+ * Reads the notice a response carries. Both fields are hints a client must work without,
+ * so an unreadable one is left out of the notice: a `Sunset` reads in any spelling
+ * `Date.parse` accepts, including the `UTC` zone RFC 9745's own example uses.
+ *
+ * @param headers - The response headers to read.
+ * @returns The notice, or `null` when the response announces nothing.
+ * @example
+ * let notice = getDeprecation(response.headers);
+ * if (notice?.deprecation) log.warn("Deprecated endpoint", { deprecation: notice.deprecation });
+ */
+export declare function getDeprecation(headers: Headers): DeprecationNotice | null;

package/dist/deprecation.js

@@ -0,0 +1,98 @@
+import { parse as parseLinks, serializeLink, stringify as stringifyLinks } from "@sdxc/link-header";
+import { failure, isFailure, success } from "@sdxc/result";
+import { getField, setField } from "@sdxc/structured-fields";
+/**
+ * A notice the fields cannot carry: an invalid `Date`, or a sunset earlier than the
+ * deprecation, which RFC 9745 forbids a server to send.
+ */
+export class DeprecationNoticeError extends Error {
+    name = "DeprecationNoticeError";
+}
+/** The relation types this module owns inside a `Link` field. */
+const RELATIONS = ["deprecation", "sunset"];
+/**
+ * Writes a notice onto response headers, replacing any `Deprecation`, `Sunset` and
+ * `deprecation`/`sunset` links already there and keeping every other link. Dates are
+ * truncated to whole seconds, the precision both fields carry.
+ *
+ * @param headers - The response headers to write.
+ * @param notice - What to announce.
+ * @returns Success once written, or why the notice is invalid, leaving `headers` untouched.
+ * @example setDeprecation(response.headers, { deprecation: new Date("2026-12-01T00:00:00Z"), sunset: new Date("2027-06-01T00:00:00Z"), deprecationLink: "https://example.com/changelog" });
+ * @example setDeprecation(response.headers, { deprecationLink: "https://example.com/deprecation-policy" });
+ */
+export function setDeprecation(headers, notice) {
+    let deprecation = notice.deprecation === undefined ? undefined : wholeSeconds(notice.deprecation);
+    let sunset = notice.sunset === undefined ? undefined : wholeSeconds(notice.sunset);
+    if (deprecation !== undefined && Number.isNaN(deprecation.getTime())) {
+        return failure(new DeprecationNoticeError("The deprecation date is invalid"));
+    }
+    if (sunset !== undefined && Number.isNaN(sunset.getTime())) {
+        return failure(new DeprecationNoticeError("The sunset date is invalid"));
+    }
+    if (deprecation !== undefined && sunset !== undefined && sunset < deprecation) {
+        return failure(new DeprecationNoticeError("The sunset date is earlier than the deprecation"));
+    }
+    headers.delete("Deprecation");
+    if (deprecation !== undefined) {
+        let written = setField(headers, "Deprecation", deprecation, "item");
+        if (isFailure(written))
+            return failure(new DeprecationNoticeError(written.error.message));
+    }
+    if (sunset === undefined)
+        headers.delete("Sunset");
+    else
+        headers.set("Sunset", sunset.toUTCString());
+    let links = [];
+    for (let link of parseLinks(headers.get("Link"))) {
+        if (!link.rels.some((rel) => RELATIONS.includes(rel))) {
+            links.push(link.raw);
+        }
+    }
+    if (notice.deprecationLink !== undefined) {
+        links.push(serializeLink(notice.deprecationLink, "deprecation"));
+    }
+    if (notice.sunsetLink !== undefined)
+        links.push(serializeLink(notice.sunsetLink, "sunset"));
+    let link = stringifyLinks(links);
+    if (link === null)
+        headers.delete("Link");
+    else
+        headers.set("Link", link);
+    return success(undefined);
+}
+/**
+ * Reads the notice a response carries. Both fields are hints a client must work without,
+ * so an unreadable one is left out of the notice: a `Sunset` reads in any spelling
+ * `Date.parse` accepts, including the `UTC` zone RFC 9745's own example uses.
+ *
+ * @param headers - The response headers to read.
+ * @returns The notice, or `null` when the response announces nothing.
+ * @example
+ * let notice = getDeprecation(response.headers);
+ * if (notice?.deprecation) log.warn("Deprecated endpoint", { deprecation: notice.deprecation });
+ */
+export function getDeprecation(headers) {
+    let notice = {};
+    let deprecation = getField(headers, "Deprecation", "item");
+    if (!isFailure(deprecation) && deprecation.data?.value instanceof Date) {
+        notice.deprecation = deprecation.data.value;
+    }
+    let sunset = headers.get("Sunset");
+    let sunsetTime = sunset === null ? Number.NaN : Date.parse(sunset);
+    if (!Number.isNaN(sunsetTime))
+        notice.sunset = new Date(sunsetTime);
+    for (let link of parseLinks(headers.get("Link"))) {
+        if (notice.deprecationLink === undefined && link.rels.includes("deprecation")) {
+            notice.deprecationLink = link.target;
+        }
+        if (notice.sunsetLink === undefined && link.rels.includes("sunset")) {
+            notice.sunsetLink = link.target;
+        }
+    }
+    return Object.keys(notice).length === 0 ? null : notice;
+}
+/** Drops the milliseconds an HTTP-date and an sf-date cannot represent. */
+function wholeSeconds(date) {
+    return new Date(Math.floor(date.getTime() / 1000) * 1000);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/http",
-	"version": "2026.10.24",
+	"version": "2026.10.25",
 	"description": "Response builders, content negotiation, and HTTP caching for the Fetch API",
 	"license": "MIT",
 	"type": "module",
@@ -11,19 +11,22 @@
 		"./response/json": "./dist/response/json.js",
 		"./response/html": "./dist/response/html.js",
 		"./negotiate": "./dist/negotiate.js",
+		"./deprecation": "./dist/deprecation.js",
 		"./cache": "./dist/cache/index.js",
 		"./middleware/head-requests": "./dist/middleware/head-requests.js"
 	},
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.23",
 		"@sdxc/duration": "2026.10.13",
+		"@sdxc/link-header": "2026.10.25",
 		"@sdxc/location": "2026.10.13",
-		"@sdxc/result": "2026.10.13"
+		"@sdxc/result": "2026.10.13",
+		"@sdxc/structured-fields": "2026.10.25"
 	},
 	"peerDependencies": {
 		"remix": "3.1.0"
 	},
-	"gitHead": "f9db0f8f1f51a256e74b94b0f4b1db4be9880370",
+	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
 	"publishConfig": {
 		"access": "public"
 	},