@utilix-tech/sdk 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.21.0
+- Add `calculatePercentageChange` (percentage-change-calculator): percentage change between two numbers, with absolute change, direction, and multiplier.
+- Add `resolveJsonPointer` (json-pointer-resolver): resolve an RFC 6901 JSON Pointer against a document, with ~0/~1 escaping and clear not-found reasons.
+
+## 0.20.0
+- Add `buildCacheControl` (cache-control-builder): assemble and explain a `Cache-Control` response header from directives, with warnings for combinations that cancel out.
+- Add `detectFillerWords` (filler-word-detector): scan text for filler words, hedge phrases, and clichés with per-phrase counts and a density score.
+
 ## 0.19.0
 - Add `detectRedos` (regex-redos-detector): statically flag catastrophic-backtracking risk (nested quantifiers, overlapping alternation, adjacent overlapping quantifiers).
 

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**553 developer utility functions for Node.js: runs locally, no API key required.**
+**558 developer utility functions for Node.js: runs locally, no API key required.**
 
 [![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
@@ -66,7 +66,7 @@ const { formatJson } = require("@utilix-tech/sdk/json");
 
 ```ts
 import { formatJson, minifyJson, diffJson, jsonToTypescript, validateJson,
-         evaluateJsonPath, jsonToCsv, yamlToJson, jsonToYaml, getJsonStats } from "@utilix-tech/sdk/json";
+         evaluateJsonPath, resolveJsonPointer, jsonToCsv, yamlToJson, jsonToYaml, getJsonStats } from "@utilix-tech/sdk/json";
 
 // Format with 2-space indent
 formatJson('{"name":"alice","age":30}', { indent: 2 });
@@ -80,6 +80,10 @@ jsonToTypescript('{"id":1,"name":"Alice"}', { rootName: "User" });
 // Query with JSONPath
 evaluateJsonPath(obj, "$.users[*].name");
 
+// Resolve an RFC 6901 JSON Pointer
+resolveJsonPointer('{"users":[{"name":"Alice"}]}', "/users/0/name");
+// { found: true, value: "Alice", tokens: ["users", "0", "name"] }
+
 // Convert JSON to CSV
 jsonToCsv('[{"a":1,"b":2}]');
 
@@ -132,7 +136,8 @@ generateHtpasswdFile([{ username: "alice", password: "secret" }]);
 
 ```ts
 import { convertCase, slugify, countWords, generateWords, generateParagraphs,
-         escapeString, htmlToMarkdown, applyOps, detectPassiveVoice, scoreReadability } from "@utilix-tech/sdk/text";
+         escapeString, htmlToMarkdown, applyOps, detectPassiveVoice, scoreReadability,
+         detectFillerWords } from "@utilix-tech/sdk/text";
 
 convertCase("hello world", "camelCase");   // "helloWorld"
 convertCase("hello world", "PascalCase");  // "HelloWorld"
@@ -157,6 +162,10 @@ detectPassiveVoice("The report was reviewed by the committee. They approved it."
 // Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog Index
 scoreReadability("The cat sat on the mat. It was a sunny day.");
 // { fleschReadingEase: 109, fleschKincaidGrade: -0.6, gunningFog: 2.2, readingLevel: "Very easy (5th grade)", ... }
+
+// Flag filler words, hedge phrases, and clichés with counts and density
+detectFillerWords("At the end of the day, I just really think we should circle back.");
+// { totalMatches: 4, fillerCount: 2, clicheCount: 2, density: 28.6, matches: [...] }
 ```
 
 ---
@@ -247,7 +256,7 @@ getNextRuns("*/5 * * * *", 5);  // next 5 run timestamps
 ### `/units`: Conversions
 
 ```ts
-import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue } from "@utilix-tech/sdk/units";
+import { convertBytes, pxToAll, convert, formatValue, validateCardNumber, validateIban, calculateLoan, validateBarcode, calculateTax, calculateCompoundInterest, validateIsbn, calculateTipSplit, calculateSimpleInterest, calculateTimeValue, calculatePercentageChange } from "@utilix-tech/sdk/units";
 
 // File sizes
 convertBytes(1073741824, "GB");  // 1
@@ -305,6 +314,10 @@ calculateSimpleInterest(1000, 5, 2);
 // Present / future value (time value of money), either direction
 calculateTimeValue(1000, 5, 10, "future");
 // { presentValue: 1000, futureValue: 1628.89, growthFactor: 1.628895, ... }
+
+// Percentage change between two numbers
+calculatePercentageChange(200, 250);
+// { percentChange: 25, absoluteChange: 50, direction: "increase", multiplier: 1.25 }
 ```
 
 ---
@@ -315,7 +328,7 @@ calculateTimeValue(1000, 5, 10, "future");
 import { getStatusCode, isValidIp, isValidIpv4, isValidIpv6,
          searchStatusCodes, buildGeoUrl, countryCodeToFlag,
          parseHar, validateSitemap, validateRobotsTxt,
-         parseUserAgent } from "@utilix-tech/sdk/network";
+         parseUserAgent, buildCacheControl } from "@utilix-tech/sdk/network";
 
 getStatusCode(404);
 // { code: 404, text: "Not Found", description: "...", category: "Client Error" }
@@ -345,6 +358,10 @@ validateSitemap('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><ur
 // Validate a robots.txt file: User-agent groups, rules, and syntax mistakes
 validateRobotsTxt("User-agent: *\nDisallow: /admin\nSitemap: https://example.com/sitemap.xml");
 // { groups: [...], sitemaps: [...], issues: [...], valid: true }
+
+// Build and explain a Cache-Control response header from directives
+buildCacheControl({ visibility: "public", maxAge: 3600, mustRevalidate: true });
+// { header: "public, max-age=3600, must-revalidate", directives: [...], warnings: [] }
 ```
 
 ---

package/dist/{chunk-F57WMKZO.js → chunk-2I4O5YCT.js}

@@ -20,6 +20,7 @@ __export(text_exports, {
   csvToHtml: () => csvToHtml,
   csvToMarkdown: () => csvToMarkdown,
   detectDelimiter: () => detectDelimiter,
+  detectFillerWords: () => detectFillerWords,
   detectPassiveVoice: () => detectPassiveVoice,
   diffLines: () => diffLines,
   diffLinesSimple: () => diffLinesSimple,
@@ -2457,5 +2458,103 @@ function scoreReadability(text) {
     readingLevel: readabilityGradeLabel(fleschReadingEase)
   };
 }
+var FILLER_WORDS = [
+  "very",
+  "really",
+  "just",
+  "actually",
+  "basically",
+  "literally",
+  "simply",
+  "totally",
+  "definitely",
+  "certainly",
+  "essentially",
+  "absolutely",
+  "completely",
+  "extremely",
+  "truly",
+  "honestly",
+  "seriously",
+  "obviously",
+  "clearly",
+  "quite",
+  "rather",
+  "somewhat",
+  "fairly",
+  "virtually"
+];
+var HEDGE_PHRASES = [
+  "maybe",
+  "perhaps",
+  "probably",
+  "possibly",
+  "arguably",
+  "kind of",
+  "sort of",
+  "a bit",
+  "a little",
+  "more or less",
+  "in my opinion",
+  "i think",
+  "i believe",
+  "to some extent"
+];
+var CLICHE_PHRASES = [
+  "at the end of the day",
+  "think outside the box",
+  "low-hanging fruit",
+  "move the needle",
+  "circle back",
+  "touch base",
+  "on the same page",
+  "hit the ground running",
+  "paradigm shift",
+  "win-win",
+  "game changer",
+  "best of both worlds",
+  "only time will tell",
+  "back to the drawing board",
+  "the tip of the iceberg",
+  "a perfect storm",
+  "needle in a haystack",
+  "raise the bar",
+  "push the envelope",
+  "the elephant in the room",
+  "boil the ocean",
+  "when it rains it pours"
+];
+var FILLER_DICTIONARY = [
+  ...FILLER_WORDS.map((phrase) => ({ phrase, category: "filler" })),
+  ...HEDGE_PHRASES.map((phrase) => ({ phrase, category: "hedge" })),
+  ...CLICHE_PHRASES.map((phrase) => ({ phrase, category: "cliche" }))
+];
+function _fillerRegex(phrase) {
+  const tokens = phrase.split(/\s+/).map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return new RegExp("\\b" + tokens.join("\\s+") + "\\b", "gi");
+}
+function detectFillerWords(text) {
+  const totalWords = (text.match(/[A-Za-z0-9']+/g) ?? []).length;
+  const matches = [];
+  for (const entry of FILLER_DICTIONARY) {
+    const re = _fillerRegex(entry.phrase);
+    const indices = [];
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      indices.push(m.index);
+      if (m.index === re.lastIndex) re.lastIndex++;
+    }
+    if (indices.length > 0) {
+      matches.push({ phrase: entry.phrase, category: entry.category, count: indices.length, indices });
+    }
+  }
+  matches.sort((a, b) => b.count - a.count || a.category.localeCompare(b.category) || a.phrase.localeCompare(b.phrase));
+  const fillerCount = matches.filter((x) => x.category === "filler").reduce((s, x) => s + x.count, 0);
+  const hedgeCount = matches.filter((x) => x.category === "hedge").reduce((s, x) => s + x.count, 0);
+  const clicheCount = matches.filter((x) => x.category === "cliche").reduce((s, x) => s + x.count, 0);
+  const totalMatches = fillerCount + hedgeCount + clicheCount;
+  const density = totalWords > 0 ? Math.round(totalMatches / totalWords * 1e3) / 10 : 0;
+  return { totalWords, totalMatches, fillerCount, hedgeCount, clicheCount, density, matches };
+}
 
-export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, detectPassiveVoice, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, scoreReadability, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };
+export { CASE_FORMATS, DEFAULT_CONVERT_OPTIONS, ESCAPE_MODES, LINE_OPS, MORSE_CODE, addBorder, analyzeText, applyOp, applyOps, centerText, convertAll, convertCase, countWords, csvToHtml, csvToMarkdown, detectDelimiter, detectFillerWords, detectPassiveVoice, diffLines, diffLinesSimple, diffStats, escapeAll, escapeString, extractHeadings, formatReadingTime, generate, generateDiff, generateHtmlTable, generateMarkdownTable, generateParagraphs, generateSentences, generateWords, getAvailableFonts, getMorseForChar, getMorseTiming, htmlToMarkdown, isValidMorse, markdownToHtml, morseToText, numberToOrdinal, numberToRoman, numberToWords, ordinalWords, parseDiff, parseTableData, readabilityScore, renderMarkdown, romanToNumber, scoreReadability, sentenceCount, slugify, slugifyAll, syllableCount, textToAscii, textToMorse, text_exports, unescapeString, wordFrequency };

package/dist/{chunk-U34B5XPK.js → chunk-TFNCFD3E.js}

@@ -20,6 +20,7 @@ __export(units_exports, {
   calcSubnet: () => calcSubnet,
   calculateCompoundInterest: () => calculateCompoundInterest,
   calculateLoan: () => calculateLoan,
+  calculatePercentageChange: () => calculatePercentageChange,
   calculateSimpleInterest: () => calculateSimpleInterest,
   calculateTax: () => calculateTax,
   calculateTimeValue: () => calculateTimeValue,
@@ -1337,5 +1338,28 @@ function calculateTimeValue(amount, annualRatePercent, years, direction, compoun
     interest: round22(futureValue - presentValue)
   };
 }
+function calculatePercentageChange(oldValue, newValue) {
+  if (!Number.isFinite(oldValue)) return { error: "Original value must be a finite number" };
+  if (!Number.isFinite(newValue)) return { error: "New value must be a finite number" };
+  if (oldValue === 0 && newValue !== 0) {
+    return { error: "Percentage change from zero is undefined (division by zero); use a nonzero original value" };
+  }
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const absoluteChange = newValue - oldValue;
+  const percentChange = oldValue === 0 ? 0 : absoluteChange / Math.abs(oldValue) * 100;
+  const multiplier = oldValue === 0 ? 1 : newValue / oldValue;
+  let direction;
+  if (absoluteChange > 0) direction = "increase";
+  else if (absoluteChange < 0) direction = "decrease";
+  else direction = "no change";
+  return {
+    oldValue,
+    newValue,
+    absoluteChange: round4(absoluteChange),
+    percentChange: round4(percentChange),
+    direction,
+    multiplier: round4(multiplier)
+  };
+}
 
-export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateCompoundInterest, calculateLoan, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, compareSemver, convert, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, viewportToPx };
+export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateCompoundInterest, calculateLoan, calculatePercentageChange, calculateSimpleInterest, calculateTax, calculateTimeValue, calculateTipSplit, compareSemver, convert, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, viewportToPx };

package/dist/{chunk-TSAGO3XP.js → chunk-WO3LJMVV.js}

@@ -24,6 +24,7 @@ __export(json_exports, {
   minifyJson: () => minifyJson,
   parseJson: () => parseJson,
   parseStructs: () => parseStructs,
+  resolveJsonPointer: () => resolveJsonPointer,
   toPascalCase: () => toPascalCase,
   toSnakeCase: () => toSnakeCase,
   validateJson: () => validateJson,
@@ -1249,5 +1250,57 @@ function jsonToZod(json, options) {
 
 export const ${rootName}Schema = ${schema}`;
 }
+function _unescapePointerToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveJsonPointer(json, pointer) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return { pointer, found: false, tokens: [], error: "Invalid JSON input" };
+  }
+  let ptr = pointer;
+  if (ptr.startsWith("#")) {
+    ptr = ptr.slice(1);
+    try {
+      ptr = decodeURIComponent(ptr);
+    } catch {
+      return { pointer, found: false, tokens: [], error: "Invalid percent-encoding in URI-fragment pointer" };
+    }
+  }
+  if (ptr === "") {
+    return { pointer, found: true, value: parsed, tokens: [] };
+  }
+  if (!ptr.startsWith("/")) {
+    return { pointer, found: false, tokens: [], error: "Pointer must be empty or start with '/' (RFC 6901)" };
+  }
+  const tokens = ptr.split("/").slice(1).map(_unescapePointerToken);
+  let current = parsed;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (token === "-") {
+        return { pointer, found: false, tokens, failedAt: token, reason: '"-" refers to the nonexistent element after the end of the array' };
+      }
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `"${token}" is not a valid array index` };
+      }
+      const idx = Number(token);
+      if (idx >= current.length) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `array index ${idx} is out of bounds (length ${current.length})` };
+      }
+      current = current[idx];
+    } else if (current !== null && typeof current === "object") {
+      const obj = current;
+      if (!Object.prototype.hasOwnProperty.call(obj, token)) {
+        return { pointer, found: false, tokens, failedAt: token, reason: `key "${token}" not found` };
+      }
+      current = obj[token];
+    } else {
+      return { pointer, found: false, tokens, failedAt: token, reason: `cannot descend into ${current === null ? "null" : typeof current} at "${token}"` };
+    }
+  }
+  return { pointer, found: true, value: current, tokens };
+}
 
-export { csvToJson, detectFormat, diffJson, evaluateJsonPath, formatDiffLine, formatJson, generateExample, getJsonStats, inferGoType, inferPythonType, inferType, jsonToCsv, jsonToGo, jsonToPython, jsonToTypescript, jsonToYaml, jsonToZod, json_exports, minifyJson, parseJson, parseStructs, toPascalCase, toSnakeCase, validateJson, validateJsonPath, validateJsonString, yamlToJson };
+export { csvToJson, detectFormat, diffJson, evaluateJsonPath, formatDiffLine, formatJson, generateExample, getJsonStats, inferGoType, inferPythonType, inferType, jsonToCsv, jsonToGo, jsonToPython, jsonToTypescript, jsonToYaml, jsonToZod, json_exports, minifyJson, parseJson, parseStructs, resolveJsonPointer, toPascalCase, toSnakeCase, validateJson, validateJsonPath, validateJsonString, yamlToJson };

package/dist/{chunk-3QMUUTBH.js → chunk-Y5OOP6WN.js}

@@ -6,6 +6,7 @@ __export(network_exports, {
   DNS_RECORD_TYPES: () => DNS_RECORD_TYPES,
   HTTP_HEADERS: () => HTTP_HEADERS,
   STATUS_CODES: () => STATUS_CODES,
+  buildCacheControl: () => buildCacheControl,
   buildDnsQueryUrl: () => buildDnsQueryUrl,
   buildGeoUrl: () => buildGeoUrl,
   buildMapUrl: () => buildMapUrl,
@@ -1721,5 +1722,97 @@ function parseUserAgent(ua) {
   const device = { type: _detectUaDeviceType(s) };
   return { browser, engine, os, device, raw: s };
 }
+var _CACHE_NUM_FIELDS = ["maxAge", "sMaxAge", "staleWhileRevalidate", "staleIfError"];
+function _humanizeSeconds(s) {
+  if (s === 0) return "0 seconds";
+  const units = [
+    [86400, "day"],
+    [3600, "hour"],
+    [60, "minute"],
+    [1, "second"]
+  ];
+  const parts = [];
+  let rem = s;
+  for (const [size, label] of units) {
+    if (rem >= size) {
+      const n = Math.floor(rem / size);
+      rem -= n * size;
+      parts.push(`${n} ${label}${n === 1 ? "" : "s"}`);
+    }
+  }
+  return parts.slice(0, 2).join(" ");
+}
+function buildCacheControl(options = {}) {
+  const nums = {
+    maxAge: null,
+    sMaxAge: null,
+    staleWhileRevalidate: null,
+    staleIfError: null
+  };
+  for (const field of _CACHE_NUM_FIELDS) {
+    const v = options[field];
+    if (v === void 0 || v === null) continue;
+    if (typeof v !== "number" || !Number.isFinite(v) || !Number.isInteger(v) || v < 0) {
+      return { error: `${field} must be a non-negative integer number of seconds` };
+    }
+    nums[field] = v;
+  }
+  const directives = [];
+  const warnings = [];
+  if (options.visibility === "public") {
+    directives.push({ name: "public", value: null, explanation: "Any cache, including shared caches and CDNs, may store this response." });
+  }
+  if (options.visibility === "private") {
+    directives.push({ name: "private", value: null, explanation: "Only the user's browser may cache this response; shared caches and CDNs must not." });
+  }
+  if (options.noCache) {
+    directives.push({ name: "no-cache", value: null, explanation: "A cache may store the response but must revalidate it with the origin before every reuse." });
+  }
+  if (options.noStore) {
+    directives.push({ name: "no-store", value: null, explanation: "No cache may store any part of this request or response." });
+  }
+  if (nums.maxAge !== null) {
+    directives.push({ name: "max-age", value: String(nums.maxAge), explanation: `Considered fresh for ${_humanizeSeconds(nums.maxAge)} (${nums.maxAge}s), after which it becomes stale.` });
+  }
+  if (nums.sMaxAge !== null) {
+    directives.push({ name: "s-maxage", value: String(nums.sMaxAge), explanation: `For shared caches (CDNs, proxies) it is fresh for ${_humanizeSeconds(nums.sMaxAge)} (${nums.sMaxAge}s), overriding max-age there.` });
+  }
+  if (options.mustRevalidate) {
+    directives.push({ name: "must-revalidate", value: null, explanation: "Once stale, a cache must revalidate with the origin and never serve the stale copy." });
+  }
+  if (options.proxyRevalidate) {
+    directives.push({ name: "proxy-revalidate", value: null, explanation: "Like must-revalidate, but the requirement applies only to shared caches." });
+  }
+  if (options.immutable) {
+    directives.push({ name: "immutable", value: null, explanation: "The body will not change while fresh, so browsers should not revalidate it on reload." });
+  }
+  if (options.noTransform) {
+    directives.push({ name: "no-transform", value: null, explanation: "Intermediaries must not modify the response body (for example, recompressing images)." });
+  }
+  if (nums.staleWhileRevalidate !== null) {
+    directives.push({ name: "stale-while-revalidate", value: String(nums.staleWhileRevalidate), explanation: `A cache may serve the stale response for up to ${_humanizeSeconds(nums.staleWhileRevalidate)} (${nums.staleWhileRevalidate}s) while it revalidates in the background.` });
+  }
+  if (nums.staleIfError !== null) {
+    directives.push({ name: "stale-if-error", value: String(nums.staleIfError), explanation: `A cache may serve the stale response for up to ${_humanizeSeconds(nums.staleIfError)} (${nums.staleIfError}s) if the origin returns an error.` });
+  }
+  if (options.mustUnderstand) {
+    directives.push({ name: "must-understand", value: null, explanation: "A cache should store the response only if it understands the caching requirements of the response's status code." });
+  }
+  if (options.noStore && directives.length > 1) {
+    warnings.push("no-store means nothing is cached, so the other directives have no effect.");
+  }
+  if (options.noCache && nums.maxAge !== null) {
+    warnings.push("no-cache forces revalidation on every use, so max-age has little practical effect alongside it.");
+  }
+  if (options.immutable && nums.maxAge === null) {
+    warnings.push("immutable only applies while the response is fresh \u2014 add a max-age so it has a freshness lifetime.");
+  }
+  if (directives.length === 0) {
+    warnings.push("No directives set \u2014 an empty Cache-Control header has no effect.");
+  }
+  const header = directives.map((d) => d.value === null ? d.name : `${d.name}=${d.value}`).join(", ");
+  const snippet = `Cache-Control: ${header}`;
+  return { header, headerName: "Cache-Control", snippet, directives, warnings };
+}
 
-export { DNS_RECORD_TYPES, HTTP_HEADERS, STATUS_CODES, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };
+export { DNS_RECORD_TYPES, HTTP_HEADERS, STATUS_CODES, buildCacheControl, buildDnsQueryUrl, buildGeoUrl, buildMapUrl, countryCodeToFlag, formatCoordinates, formatTtl, getByCategory, getHeader, getHeadersByCategory, getStatusByCategory, getStatusCode, isClientError, isServerError, isSuccess, isValidIp, isValidIpv4, isValidIpv6, network_exports, parseDnsResponse, parseGeoResponse, parseHar, parseUserAgent, searchHeaders, searchStatusCodes, statusCodeToText, typeNumberToLabel, validateDomain, validateHeaderName, validateHeaderValue, validateRobotsTxt, validateSitemap };