http-vary 0.0.1

package/README.md

@@ -0,0 +1,156 @@
+<br />
+
+[![Issues](https://img.shields.io/github/issues/arthurfiorette/tinylibs?logo=github&label=Issues)](https://github.com/arthurfiorette/tinylibs/issues)
+[![Stars](https://img.shields.io/github/stars/arthurfiorette/tinylibs?logo=github&label=Stars)](https://github.com/arthurfiorette/tinylibs/stargazers)
+[![License](https://img.shields.io/github/license/arthurfiorette/tinylibs?logo=githu&label=License)](https://github.com/arthurfiorette/tinylibs/blob/main/LICENSE)
+[![Codecov](https://codecov.io/gh/arthurfiorette/tinylibs/branch/main/graph/badge.svg?token=ML0KGCU0VM)](https://codecov.io/gh/arthurfiorette/tinylibs)
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs?ref=badge_shield)
+[![Join the chat at https://gitter.im/tinylibs-js-org/community](https://badges.gitter.im/tinylibs-js-org/community.svg)](https://gitter.im/tinylibs-js-org/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Speed Blazing](https://img.shields.io/badge/speed-blazing%20%F0%9F%94%A5-brightgreen.svg)](https://twitter.com/acdlite/status/974390255393505280)
+
+[![Latest Version](https://img.shields.io/npm/v/http-vary)](https://www.npmjs.com/package/http-vary)
+[![Downloads](https://img.shields.io/npm/dw/http-vary)](https://www.npmjs.com/package/http-vary)
+[![JsDelivr](https://data.jsdelivr.com/v1/package/npm/http-vary/badge?style=rounded)](https://www.jsdelivr.com/package/npm/http-vary)
+[![Bundlephobia](https://img.shields.io/bundlephobia/minzip/http-vary/latest?style=flat)](https://bundlephobia.com/package/http-vary@latest)
+[![Packagephobia](https://packagephobia.com/badge?p=http-vary@latest)](https://packagephobia.com/result?p=http-vary@latest)
+
+<br />
+
+<div align="center">
+  <pre>
+  <h1>⌛<br />HTTP Vary</h1>
+  </pre>
+  <br />
+</div>
+
+<h3 align="center">
+  <code>HTTP Vary</code> is a minimal parser and utility for the <a href="https://www.rfc-editor.org/rfc/rfc9110.html#name-vary" target="_blank">Vary</a> header (RFC 9110).
+  <br />
+  <br />
+</h3>
+
+<br />
+
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Installing](#installing)
+  - [Node](#node)
+  - [Browser](#browser)
+  - [Url Import](#url-import)
+- [Getting Started](#getting-started)
+  - [Usage](#usage)
+- [Understanding Wildcard Behavior](#understanding-wildcard-behavior)
+- [License](#license)
+
+<br />
+
+## Installing
+
+### Node
+
+```sh
+npm install http-vary # or yarn add http-vary
+```
+
+```js
+const { parse, compare } = require('http-vary');
+import { parse, compare } from 'http-vary';
+```
+
+### Browser
+
+```html
+<script
+  crossorigin
+  src="https://cdn.jsdelivr.net/npm/http-vary@latest/dist/index.umd.js"
+></script>
+```
+
+```js
+const { parse, compare } = window.httpVary;
+```
+
+### Url Import
+
+```ts
+import { parse, compare } from 'https://cdn.skypack.dev/http-vary@latest';
+```
+
+<br />
+
+## Getting Started
+
+This package is a parser and utility for the HTTP Vary header as defined in
+[RFC 9110 Section 12.5.5](https://www.rfc-editor.org/rfc/rfc9110.html#name-vary). The Vary
+header indicates which request headers affect the response, enabling proper HTTP caching
+behavior. You can parse a Vary header string with [`parse()`](./src/parse.ts) and compare
+request headers for cache equivalence with [`compare()`](./src/compare.ts).
+
+All needed documentation is available in form of `TSDoc` comments.
+
+### Usage
+
+```ts
+import { parse, compare, VaryHeader } from 'http-vary';
+
+// Parse a Vary header
+const rawHeader = 'Accept-Encoding, User-Agent';
+
+const vary = parse(rawHeader);
+// => ['accept-encoding', 'user-agent']
+
+// Parse wildcard
+const wildcardVary = parse('*');
+// => '*'
+
+// Compare headers for cache equivalence
+const headers1 = {
+  'Accept-Encoding': 'gzip',
+  'User-Agent': 'Chrome'
+};
+
+const headers2 = {
+  'Accept-Encoding': 'gzip',
+  'User-Agent': 'Chrome',
+  Cookie: 'session=abc' // This header is ignored
+};
+
+const isEquivalent = compare(vary, headers1, headers2);
+// => true (headers match for the fields specified in Vary)
+
+// Case-insensitive header matching (per RFC 9110)
+const headers3 = {
+  'accept-encoding': 'gzip', // lowercase
+  'USER-AGENT': 'Chrome' // uppercase
+};
+
+const caseInsensitiveMatch = compare(vary, headers1, headers3);
+// => true (header names are matched case-insensitively)
+
+// Wildcard always returns false
+const wildcardMatch = compare('*', headers1, headers2);
+// => false (wildcard indicates response varies on aspects beyond headers)
+```
+
+<br />
+
+## Understanding Wildcard Behavior
+
+Per [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-vary), `Vary: *` signals
+that the response can vary based on **anything** about the request, including factors
+beyond headers (e.g., client IP, time, server load, A/B testing). Since we cannot
+determine if two requests would receive the same response, `compare()` always returns
+`false` for wildcard, preventing incorrect cache hits.
+
+**TL;DR**: `Vary: *` means "don't cache" - always consult the origin server.
+
+<br />
+
+## License
+
+Licensed under the **MIT**. See [`LICENSE`](LICENSE) for more informations.
+
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs.svg?type=small)](https://app.fossa.com/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs?ref=badge_small)
+
+<br />

package/dist/compare.d.ts

@@ -0,0 +1,37 @@
+import type { CompareHeaders, VaryHeader } from './types';
+/**
+ * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given
+ * Vary header, as per
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * This function determines if two requests would receive the same cached response based
+ * on the Vary header requirements.
+ *
+ * @remarks
+ * - Returns `false` for wildcard vary (`'*'`) as responses always differ
+ * - Header name matching is case-insensitive (per RFC 9110)
+ * - Missing headers are treated as `undefined`
+ * - String values are trimmed before comparison
+ * - Array values are converted to strings via `.toString()`
+ * - Uses loose equality (!=) for comparison
+ * - Empty strings are distinct from missing headers
+ *
+ * @example
+ *
+ * ```ts
+ * const vary = ['accept-encoding', 'user-agent'];
+ * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };
+ * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };
+ *
+ * compare(vary, headers1, headers2);
+ * // => true
+ * ```
+ *
+ * @param {VaryHeader} vary - The Vary header specifying which fields to compare
+ * @param {CompareHeaders} source - The first set of request headers
+ * @param {CompareHeaders} target - The second set of request headers
+ * @returns {boolean} `true` if the headers are equivalent for the given Vary header,
+ *   `false` otherwise
+ */
+export declare function compare(vary: VaryHeader, source: CompareHeaders, target: CompareHeaders): boolean;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,GACrB,OAAO,CAoCT"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './compare';
+export * from './parse';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+function r(r,e){(null==e||e>r.length)&&(e=r.length);for(var t=0,n=Array(e);t<e;t++)n[t]=r[t];return n}function e(e,t){var n="undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(n)return(n=n.call(e)).next.bind(n);if(Array.isArray(e)||(n=function(e,t){if(e){if("string"==typeof e)return r(e,t);var n={}.toString.call(e).slice(8,-1);return"Object"===n&&e.constructor&&(n=e.constructor.name),"Map"===n||"Set"===n?Array.from(e):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?r(e,t):void 0}}(e))||t&&e&&"number"==typeof e.length){n&&(e=n);var o=0;return function(){return o>=e.length?{done:!0}:{done:!1,value:e[o++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var t=/^[a-z0-9-]+$/i;exports.compare=function(r,t,n){if("*"===r)return!1;for(var o,a=Object.keys(t),i=Object.keys(n),l=e(r);!(o=l()).done;){for(var u,f=o.value,v=void 0,s=void 0,c=e(a);!(u=c()).done;){var d=u.value;if(d.toLowerCase()===f){var y;v=null==(y=t[d])||null==(y=y.toString())?void 0:y.trim();break}}for(var m,b=e(i);!(m=b()).done;){var g=m.value;if(g.toLowerCase()===f){var p;s=null==(p=n[g])||null==(p=p.toString())?void 0:p.trim();break}}if(v!=s)return!1}return!0},exports.parse=function(r,e){if(void 0===e&&(e=16),"string"!=typeof r)return null;if(r.includes("*"))return"*";for(var n=new Set,o=0;o<r.length;o++){var a=r[o];if(" "!==a&&"\t"!==a&&","!==a){for(var i=o;o<r.length&&","!==r[o];)o++;var l=r.slice(i,o).trim().toLowerCase();if(0!==l.length&&t.test(l)&&(n.add(l),n.size>=e))break}}return 0===n.size?null:Array.from(n)};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/parse.ts","../src/compare.ts"],"sourcesContent":["import type { VaryHeader } from './types';\n\nconst VALID_HEADER_NAME_REGEX = /^[a-z0-9-]+$/i;\n\n/**\n * Parses the Vary header as defined in\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * The Vary header indicates which request headers a server considers when selecting or\n * generating a response, enabling proper HTTP caching behavior.\n *\n * @remarks\n * - Header field names are normalized to lowercase\n * - Duplicate fields are automatically deduplicated\n * - Invalid header names (per RFC 9110) are silently skipped\n * - If the header contains `'*'`, the function returns `'*'` (wildcard)\n * - Returns `null` for invalid input or when no valid fields are found\n *\n * @example\n *\n * ```ts\n * parse('Accept-Encoding, User-Agent');\n * // => ['accept-encoding', 'user-agent']\n *\n * parse('*');\n * // => '*'\n *\n * parse('Invalid Header!');\n * // => null\n * ```\n *\n * @param {string} headerStr - The Vary header value to parse (e.g., \"Accept-Encoding,\n *   User-Agent\")\n * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS\n *   protection. Default is `16`\n * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field\n *   names, `'*'` for wildcard, or `null` if invalid.\n */\nexport function parse(headerStr?: string, maxLength = 16): VaryHeader | null {\n  // Invalid header name\n  if (typeof headerStr !== 'string') {\n    return null;\n  }\n\n  // RFC says only '*' is valid alone, but some servers may send invalid headers like '*, Accept-Encoding'\n  if (headerStr.includes('*')) {\n    return '*';\n  }\n\n  const values = new Set<string>();\n\n  for (let i = 0; i < headerStr.length; i++) {\n    const char = headerStr[i];\n\n    if (char === ' ' || char === '\\t' || char === ',') {\n      continue;\n    }\n\n    const start = i;\n\n    while (i < headerStr.length) {\n      const char = headerStr[i];\n\n      if (char === ',') {\n        break;\n      }\n\n      i++;\n    }\n\n    const headerName = headerStr.slice(start, i).trim().toLowerCase();\n\n    // Skip invalid header names\n    if (headerName.length === 0 || !VALID_HEADER_NAME_REGEX.test(headerName)) {\n      continue;\n    }\n\n    values.add(headerName);\n\n    // DOS protection to avoid overly large vary headers\n    if (values.size >= maxLength) {\n      break;\n    }\n  }\n\n  // Ensures no empty set is returned\n  if (values.size === 0) {\n    return null;\n  }\n\n  return Array.from(values);\n}\n","import type { CompareHeaders, VaryHeader } from './types';\n\n/**\n * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given\n * Vary header, as per\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * This function determines if two requests would receive the same cached response based\n * on the Vary header requirements.\n *\n * @remarks\n * - Returns `false` for wildcard vary (`'*'`) as responses always differ\n * - Header name matching is case-insensitive (per RFC 9110)\n * - Missing headers are treated as `undefined`\n * - String values are trimmed before comparison\n * - Array values are converted to strings via `.toString()`\n * - Uses loose equality (!=) for comparison\n * - Empty strings are distinct from missing headers\n *\n * @example\n *\n * ```ts\n * const vary = ['accept-encoding', 'user-agent'];\n * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n *\n * compare(vary, headers1, headers2);\n * // => true\n * ```\n *\n * @param {VaryHeader} vary - The Vary header specifying which fields to compare\n * @param {CompareHeaders} source - The first set of request headers\n * @param {CompareHeaders} target - The second set of request headers\n * @returns {boolean} `true` if the headers are equivalent for the given Vary header,\n *   `false` otherwise\n */\nexport function compare(\n  vary: VaryHeader,\n  source: CompareHeaders,\n  target: CompareHeaders\n): boolean {\n  // Wildcard always differs\n  if (vary === '*') {\n    return false;\n  }\n\n  const sourceKeys = Object.keys(source);\n  const targetKeys = Object.keys(target);\n\n  for (const field of vary) {\n    let sourceValue: string | undefined;\n    let targetValue: string | undefined;\n\n    // Case-insensitive header lookup in source\n    for (const key of sourceKeys) {\n      if (key.toLowerCase() === field) {\n        sourceValue = source[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // Case-insensitive header lookup in target\n    for (const key of targetKeys) {\n      if (key.toLowerCase() === field) {\n        targetValue = target[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // biome-ignore lint/suspicious/noDoubleEquals: Intentional loose comparison\n    if (sourceValue != targetValue) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"names":["VALID_HEADER_NAME_REGEX","vary","source","target","_step","sourceKeys","Object","keys","targetKeys","_iterator","_createForOfIteratorHelperLoose","done","_step2","field","value","sourceValue","targetValue","_iterator2","key","toLowerCase","_source$key","toString","trim","_step3","_iterator3","_target$_key","headerStr","maxLength","includes","values","Set","i","length","char","start","headerName","slice","test","add","size","Array","from"],"mappings":"oyBAEA,IAAMA,EAA0B,yCCmC9BC,EACAC,EACAC,GAGA,GAAa,MAATF,EACF,OACF,EAKA,IAHA,IAGwBG,EAHlBC,EAAaC,OAAOC,KAAKL,GACzBM,EAAaF,OAAOC,KAAKJ,GAE/BM,EAAAC,EAAoBT,KAAIG,EAAAK,KAAAE,MAAE,CAKxB,IALS,IAKmBC,EALnBC,EAAKT,EAAAU,MACVC,OAA+B,EAC/BC,OAGJ,EAAAC,EAAAP,EAAkBL,KAAUO,EAAAK,KAAAN,MAAE,CAAA,IAAnBO,EAAGN,EAAAE,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAA,IAAAO,EAC/BL,SAAWK,EAAGlB,EAAOgB,KAAgB,OAAZE,EAAXA,EAAaC,iBAAU,EAAvBD,EAAyBE,OACvC,KACF,CACF,CAGA,IAAA,IAA4BC,EAA5BC,EAAAd,EAAkBF,KAAUe,EAAAC,KAAAb,MAAE,CAAnB,IAAAO,EAAGK,EAAAT,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAAY,IAAAA,EAC/BT,EAAyBS,OAAdA,EAAGtB,EAAOe,KAAPO,OAAWA,EAAXA,EAAaJ,iBAAbI,EAAAA,EAAyBH,OACvC,KACF,CACF,CAGA,GAAIP,GAAeC,EACjB,OACF,CACF,CAEA,OACF,CAAA,yBDtCsBU,EAAoBC,GAExC,YAFwCA,IAAAA,EAAY,IAE3B,iBAAdD,EACT,OACF,KAGA,GAAIA,EAAUE,SAAS,KACrB,MAAO,IAKT,IAFA,IAAMC,EAAS,IAAIC,IAEVC,EAAI,EAAGA,EAAIL,EAAUM,OAAQD,IAAK,CACzC,IAAME,EAAOP,EAAUK,GAEvB,GAAa,MAATE,GAAyB,OAATA,GAA0B,MAATA,EAArC,CAMA,IAFA,IAAMC,EAAQH,EAEPA,EAAIL,EAAUM,QAGN,MAFAN,EAAUK,IAMvBA,IAGF,IAAMI,EAAaT,EAAUU,MAAMF,EAAOH,GAAGT,OAAOH,cAGpD,GAA0B,IAAtBgB,EAAWH,QAAiBhC,EAAwBqC,KAAKF,KAI7DN,EAAOS,IAAIH,GAGPN,EAAOU,MAAQZ,GACjB,KAzBF,CA2BF,CAGA,OAAoB,IAAhBE,EAAOU,KACF,KAGFC,MAAMC,KAAKZ,EACpB"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+function r(r,e){(null==e||e>r.length)&&(e=r.length);for(var t=0,n=Array(e);t<e;t++)n[t]=r[t];return n}function e(e,t){var n="undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(n)return(n=n.call(e)).next.bind(n);if(Array.isArray(e)||(n=function(e,t){if(e){if("string"==typeof e)return r(e,t);var n={}.toString.call(e).slice(8,-1);return"Object"===n&&e.constructor&&(n=e.constructor.name),"Map"===n||"Set"===n?Array.from(e):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?r(e,t):void 0}}(e))||t&&e&&"number"==typeof e.length){n&&(e=n);var o=0;return function(){return o>=e.length?{done:!0}:{done:!1,value:e[o++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function t(r,t,n){if("*"===r)return!1;for(var o,a=Object.keys(t),i=Object.keys(n),l=e(r);!(o=l()).done;){for(var u,f=o.value,v=void 0,d=void 0,s=e(a);!(u=s()).done;){var c=u.value;if(c.toLowerCase()===f){var y;v=null==(y=t[c])||null==(y=y.toString())?void 0:y.trim();break}}for(var b,m=e(i);!(b=m()).done;){var g=b.value;if(g.toLowerCase()===f){var h;d=null==(h=n[g])||null==(h=h.toString())?void 0:h.trim();break}}if(v!=d)return!1}return!0}var n=/^[a-z0-9-]+$/i;function o(r,e){if(void 0===e&&(e=16),"string"!=typeof r)return null;if(r.includes("*"))return"*";for(var t=new Set,o=0;o<r.length;o++){var a=r[o];if(" "!==a&&"\t"!==a&&","!==a){for(var i=o;o<r.length&&","!==r[o];)o++;var l=r.slice(i,o).trim().toLowerCase();if(0!==l.length&&n.test(l)&&(t.add(l),t.size>=e))break}}return 0===t.size?null:Array.from(t)}export{t as compare,o as parse};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/compare.ts","../src/parse.ts"],"sourcesContent":["import type { CompareHeaders, VaryHeader } from './types';\n\n/**\n * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given\n * Vary header, as per\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * This function determines if two requests would receive the same cached response based\n * on the Vary header requirements.\n *\n * @remarks\n * - Returns `false` for wildcard vary (`'*'`) as responses always differ\n * - Header name matching is case-insensitive (per RFC 9110)\n * - Missing headers are treated as `undefined`\n * - String values are trimmed before comparison\n * - Array values are converted to strings via `.toString()`\n * - Uses loose equality (!=) for comparison\n * - Empty strings are distinct from missing headers\n *\n * @example\n *\n * ```ts\n * const vary = ['accept-encoding', 'user-agent'];\n * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n *\n * compare(vary, headers1, headers2);\n * // => true\n * ```\n *\n * @param {VaryHeader} vary - The Vary header specifying which fields to compare\n * @param {CompareHeaders} source - The first set of request headers\n * @param {CompareHeaders} target - The second set of request headers\n * @returns {boolean} `true` if the headers are equivalent for the given Vary header,\n *   `false` otherwise\n */\nexport function compare(\n  vary: VaryHeader,\n  source: CompareHeaders,\n  target: CompareHeaders\n): boolean {\n  // Wildcard always differs\n  if (vary === '*') {\n    return false;\n  }\n\n  const sourceKeys = Object.keys(source);\n  const targetKeys = Object.keys(target);\n\n  for (const field of vary) {\n    let sourceValue: string | undefined;\n    let targetValue: string | undefined;\n\n    // Case-insensitive header lookup in source\n    for (const key of sourceKeys) {\n      if (key.toLowerCase() === field) {\n        sourceValue = source[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // Case-insensitive header lookup in target\n    for (const key of targetKeys) {\n      if (key.toLowerCase() === field) {\n        targetValue = target[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // biome-ignore lint/suspicious/noDoubleEquals: Intentional loose comparison\n    if (sourceValue != targetValue) {\n      return false;\n    }\n  }\n\n  return true;\n}\n","import type { VaryHeader } from './types';\n\nconst VALID_HEADER_NAME_REGEX = /^[a-z0-9-]+$/i;\n\n/**\n * Parses the Vary header as defined in\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * The Vary header indicates which request headers a server considers when selecting or\n * generating a response, enabling proper HTTP caching behavior.\n *\n * @remarks\n * - Header field names are normalized to lowercase\n * - Duplicate fields are automatically deduplicated\n * - Invalid header names (per RFC 9110) are silently skipped\n * - If the header contains `'*'`, the function returns `'*'` (wildcard)\n * - Returns `null` for invalid input or when no valid fields are found\n *\n * @example\n *\n * ```ts\n * parse('Accept-Encoding, User-Agent');\n * // => ['accept-encoding', 'user-agent']\n *\n * parse('*');\n * // => '*'\n *\n * parse('Invalid Header!');\n * // => null\n * ```\n *\n * @param {string} headerStr - The Vary header value to parse (e.g., \"Accept-Encoding,\n *   User-Agent\")\n * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS\n *   protection. Default is `16`\n * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field\n *   names, `'*'` for wildcard, or `null` if invalid.\n */\nexport function parse(headerStr?: string, maxLength = 16): VaryHeader | null {\n  // Invalid header name\n  if (typeof headerStr !== 'string') {\n    return null;\n  }\n\n  // RFC says only '*' is valid alone, but some servers may send invalid headers like '*, Accept-Encoding'\n  if (headerStr.includes('*')) {\n    return '*';\n  }\n\n  const values = new Set<string>();\n\n  for (let i = 0; i < headerStr.length; i++) {\n    const char = headerStr[i];\n\n    if (char === ' ' || char === '\\t' || char === ',') {\n      continue;\n    }\n\n    const start = i;\n\n    while (i < headerStr.length) {\n      const char = headerStr[i];\n\n      if (char === ',') {\n        break;\n      }\n\n      i++;\n    }\n\n    const headerName = headerStr.slice(start, i).trim().toLowerCase();\n\n    // Skip invalid header names\n    if (headerName.length === 0 || !VALID_HEADER_NAME_REGEX.test(headerName)) {\n      continue;\n    }\n\n    values.add(headerName);\n\n    // DOS protection to avoid overly large vary headers\n    if (values.size >= maxLength) {\n      break;\n    }\n  }\n\n  // Ensures no empty set is returned\n  if (values.size === 0) {\n    return null;\n  }\n\n  return Array.from(values);\n}\n"],"names":["compare","vary","source","target","_step","sourceKeys","Object","keys","targetKeys","_iterator","_createForOfIteratorHelperLoose","done","_step2","field","value","sourceValue","targetValue","_iterator2","key","toLowerCase","_source$key","toString","trim","_step3","_iterator3","_target$_key","VALID_HEADER_NAME_REGEX","parse","headerStr","maxLength","includes","values","Set","i","length","char","start","headerName","slice","test","add","size","Array","from"],"mappings":"6yBAoCgBA,EACdC,EACAC,EACAC,GAGA,GAAa,MAATF,EACF,OACF,EAKA,IAHA,IAGwBG,EAHlBC,EAAaC,OAAOC,KAAKL,GACzBM,EAAaF,OAAOC,KAAKJ,GAE/BM,EAAAC,EAAoBT,KAAIG,EAAAK,KAAAE,MAAE,CAKxB,IALS,IAKmBC,EALnBC,EAAKT,EAAAU,MACVC,OAA+B,EAC/BC,OAGJ,EAAAC,EAAAP,EAAkBL,KAAUO,EAAAK,KAAAN,MAAE,CAAA,IAAnBO,EAAGN,EAAAE,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAA,IAAAO,EAC/BL,SAAWK,EAAGlB,EAAOgB,KAAgB,OAAZE,EAAXA,EAAaC,iBAAU,EAAvBD,EAAyBE,OACvC,KACF,CACF,CAGA,IAAA,IAA4BC,EAA5BC,EAAAd,EAAkBF,KAAUe,EAAAC,KAAAb,MAAE,CAAnB,IAAAO,EAAGK,EAAAT,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAAY,IAAAA,EAC/BT,EAAyBS,OAAdA,EAAGtB,EAAOe,KAAPO,OAAWA,EAAXA,EAAaJ,iBAAbI,EAAAA,EAAyBH,OACvC,KACF,CACF,CAGA,GAAIP,GAAeC,EACjB,OACF,CACF,CAEA,OACF,CAAA,CC1EA,IAAMU,EAA0B,yBAoChBC,EAAMC,EAAoBC,GAExC,YAFwCA,IAAAA,EAAY,IAE3B,iBAAdD,EACT,OACF,KAGA,GAAIA,EAAUE,SAAS,KACrB,MAAO,IAKT,IAFA,IAAMC,EAAS,IAAIC,IAEVC,EAAI,EAAGA,EAAIL,EAAUM,OAAQD,IAAK,CACzC,IAAME,EAAOP,EAAUK,GAEvB,GAAa,MAATE,GAAyB,OAATA,GAA0B,MAATA,EAArC,CAMA,IAFA,IAAMC,EAAQH,EAEPA,EAAIL,EAAUM,QAGN,MAFAN,EAAUK,IAMvBA,IAGF,IAAMI,EAAaT,EAAUU,MAAMF,EAAOH,GAAGX,OAAOH,cAGpD,GAA0B,IAAtBkB,EAAWH,QAAiBR,EAAwBa,KAAKF,KAI7DN,EAAOS,IAAIH,GAGPN,EAAOU,MAAQZ,GACjB,KAzBF,CA2BF,CAGA,OAAoB,IAAhBE,EAAOU,KACF,KAGFC,MAAMC,KAAKZ,EACpB"}

package/dist/index.modern.mjs

@@ -0,0 +1,2 @@
+function t(t,n,r){if("*"===t)return!1;const e=Object.keys(n),o=Object.keys(r);for(const s of t){let t,l;for(const r of e)if(r.toLowerCase()===s){var i;t=null==(i=n[r])||null==(i=i.toString())?void 0:i.trim();break}for(const t of o)if(t.toLowerCase()===s){var f;l=null==(f=r[t])||null==(f=f.toString())?void 0:f.trim();break}if(t!=l)return!1}return!0}const n=/^[a-z0-9-]+$/i;function r(t,r=16){if("string"!=typeof t)return null;if(t.includes("*"))return"*";const e=new Set;for(let o=0;o<t.length;o++){const i=t[o];if(" "===i||"\t"===i||","===i)continue;const f=o;for(;o<t.length&&","!==t[o];)o++;const s=t.slice(f,o).trim().toLowerCase();if(0!==s.length&&n.test(s)&&(e.add(s),e.size>=r))break}return 0===e.size?null:Array.from(e)}export{t as compare,r as parse};
+//# sourceMappingURL=index.modern.mjs.map

package/dist/index.modern.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.modern.mjs","sources":["../src/compare.ts","../src/parse.ts"],"sourcesContent":["import type { CompareHeaders, VaryHeader } from './types';\n\n/**\n * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given\n * Vary header, as per\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * This function determines if two requests would receive the same cached response based\n * on the Vary header requirements.\n *\n * @remarks\n * - Returns `false` for wildcard vary (`'*'`) as responses always differ\n * - Header name matching is case-insensitive (per RFC 9110)\n * - Missing headers are treated as `undefined`\n * - String values are trimmed before comparison\n * - Array values are converted to strings via `.toString()`\n * - Uses loose equality (!=) for comparison\n * - Empty strings are distinct from missing headers\n *\n * @example\n *\n * ```ts\n * const vary = ['accept-encoding', 'user-agent'];\n * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n *\n * compare(vary, headers1, headers2);\n * // => true\n * ```\n *\n * @param {VaryHeader} vary - The Vary header specifying which fields to compare\n * @param {CompareHeaders} source - The first set of request headers\n * @param {CompareHeaders} target - The second set of request headers\n * @returns {boolean} `true` if the headers are equivalent for the given Vary header,\n *   `false` otherwise\n */\nexport function compare(\n  vary: VaryHeader,\n  source: CompareHeaders,\n  target: CompareHeaders\n): boolean {\n  // Wildcard always differs\n  if (vary === '*') {\n    return false;\n  }\n\n  const sourceKeys = Object.keys(source);\n  const targetKeys = Object.keys(target);\n\n  for (const field of vary) {\n    let sourceValue: string | undefined;\n    let targetValue: string | undefined;\n\n    // Case-insensitive header lookup in source\n    for (const key of sourceKeys) {\n      if (key.toLowerCase() === field) {\n        sourceValue = source[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // Case-insensitive header lookup in target\n    for (const key of targetKeys) {\n      if (key.toLowerCase() === field) {\n        targetValue = target[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // biome-ignore lint/suspicious/noDoubleEquals: Intentional loose comparison\n    if (sourceValue != targetValue) {\n      return false;\n    }\n  }\n\n  return true;\n}\n","import type { VaryHeader } from './types';\n\nconst VALID_HEADER_NAME_REGEX = /^[a-z0-9-]+$/i;\n\n/**\n * Parses the Vary header as defined in\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * The Vary header indicates which request headers a server considers when selecting or\n * generating a response, enabling proper HTTP caching behavior.\n *\n * @remarks\n * - Header field names are normalized to lowercase\n * - Duplicate fields are automatically deduplicated\n * - Invalid header names (per RFC 9110) are silently skipped\n * - If the header contains `'*'`, the function returns `'*'` (wildcard)\n * - Returns `null` for invalid input or when no valid fields are found\n *\n * @example\n *\n * ```ts\n * parse('Accept-Encoding, User-Agent');\n * // => ['accept-encoding', 'user-agent']\n *\n * parse('*');\n * // => '*'\n *\n * parse('Invalid Header!');\n * // => null\n * ```\n *\n * @param {string} headerStr - The Vary header value to parse (e.g., \"Accept-Encoding,\n *   User-Agent\")\n * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS\n *   protection. Default is `16`\n * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field\n *   names, `'*'` for wildcard, or `null` if invalid.\n */\nexport function parse(headerStr?: string, maxLength = 16): VaryHeader | null {\n  // Invalid header name\n  if (typeof headerStr !== 'string') {\n    return null;\n  }\n\n  // RFC says only '*' is valid alone, but some servers may send invalid headers like '*, Accept-Encoding'\n  if (headerStr.includes('*')) {\n    return '*';\n  }\n\n  const values = new Set<string>();\n\n  for (let i = 0; i < headerStr.length; i++) {\n    const char = headerStr[i];\n\n    if (char === ' ' || char === '\\t' || char === ',') {\n      continue;\n    }\n\n    const start = i;\n\n    while (i < headerStr.length) {\n      const char = headerStr[i];\n\n      if (char === ',') {\n        break;\n      }\n\n      i++;\n    }\n\n    const headerName = headerStr.slice(start, i).trim().toLowerCase();\n\n    // Skip invalid header names\n    if (headerName.length === 0 || !VALID_HEADER_NAME_REGEX.test(headerName)) {\n      continue;\n    }\n\n    values.add(headerName);\n\n    // DOS protection to avoid overly large vary headers\n    if (values.size >= maxLength) {\n      break;\n    }\n  }\n\n  // Ensures no empty set is returned\n  if (values.size === 0) {\n    return null;\n  }\n\n  return Array.from(values);\n}\n"],"names":["compare","vary","source","target","sourceKeys","Object","keys","targetKeys","field","sourceValue","targetValue","key","toLowerCase","_source$key","toString","trim","_target$key","VALID_HEADER_NAME_REGEX","parse","headerStr","maxLength","includes","values","Set","i","length","char","start","headerName","slice","test","add","size","Array","from"],"mappings":"SAoCgBA,EACdC,EACAC,EACAC,GAGA,GAAa,MAATF,EACF,OAAO,EAGT,MAAMG,EAAaC,OAAOC,KAAKJ,GACzBK,EAAaF,OAAOC,KAAKH,GAE/B,IAAK,MAAMK,KAASP,EAAM,CACxB,IAAIQ,EACAC,EAGJ,IAAK,MAAMC,KAAOP,EAChB,GAAIO,EAAIC,gBAAkBJ,EAAO,CAAAK,IAAAA,EAC/BJ,EAAyB,OAAdI,EAAGX,EAAOS,KAAgB,OAAZE,EAAXA,EAAaC,iBAAU,EAAvBD,EAAyBE,OACvC,KACF,CAIF,IAAK,MAAMJ,KAAOJ,EAChB,GAAII,EAAIC,gBAAkBJ,EAAO,CAAAQ,IAAAA,EAC/BN,EAAyB,OAAdM,EAAGb,EAAOQ,KAAPK,OAAWA,EAAXA,EAAaF,iBAAbE,EAAAA,EAAyBD,OACvC,KACF,CAIF,GAAIN,GAAeC,EACjB,QAEJ,CAEA,OACF,CAAA,CC1EA,MAAMO,EAA0B,yBAoChBC,EAAMC,EAAoBC,EAAY,IAEpD,GAAyB,iBAAdD,EACT,YAIF,GAAIA,EAAUE,SAAS,KACrB,MAAO,IAGT,MAAMC,EAAS,IAAIC,IAEnB,IAAK,IAAIC,EAAI,EAAGA,EAAIL,EAAUM,OAAQD,IAAK,CACzC,MAAME,EAAOP,EAAUK,GAEvB,GAAa,MAATE,GAAyB,OAATA,GAA0B,MAATA,EACnC,SAGF,MAAMC,EAAQH,EAEd,KAAOA,EAAIL,EAAUM,QAGN,MAFAN,EAAUK,IAMvBA,IAGF,MAAMI,EAAaT,EAAUU,MAAMF,EAAOH,GAAGT,OAAOH,cAGpD,GAA0B,IAAtBgB,EAAWH,QAAiBR,EAAwBa,KAAKF,KAI7DN,EAAOS,IAAIH,GAGPN,EAAOU,MAAQZ,GACjB,KAEJ,CAGA,OAAoB,IAAhBE,EAAOU,KACF,KAGFC,MAAMC,KAAKZ,EACpB"}

package/dist/index.umd.js

@@ -0,0 +1,2 @@
+!function(e,r){"object"==typeof exports&&"undefined"!=typeof module?r(exports):"function"==typeof define&&define.amd?define(["exports"],r):r((e||self).httpVary={})}(this,function(e){function r(e,r){(null==r||r>e.length)&&(r=e.length);for(var t=0,n=Array(r);t<r;t++)n[t]=e[t];return n}function t(e,t){var n="undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(n)return(n=n.call(e)).next.bind(n);if(Array.isArray(e)||(n=function(e,t){if(e){if("string"==typeof e)return r(e,t);var n={}.toString.call(e).slice(8,-1);return"Object"===n&&e.constructor&&(n=e.constructor.name),"Map"===n||"Set"===n?Array.from(e):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?r(e,t):void 0}}(e))||t&&e&&"number"==typeof e.length){n&&(e=n);var o=0;return function(){return o>=e.length?{done:!0}:{done:!1,value:e[o++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var n=/^[a-z0-9-]+$/i;e.compare=function(e,r,n){if("*"===e)return!1;for(var o,i=Object.keys(r),a=Object.keys(n),l=t(e);!(o=l()).done;){for(var f,u=o.value,d=void 0,s=void 0,v=t(i);!(f=v()).done;){var c=f.value;if(c.toLowerCase()===u){var y;d=null==(y=r[c])||null==(y=y.toString())?void 0:y.trim();break}}for(var b,m=t(a);!(b=m()).done;){var p=b.value;if(p.toLowerCase()===u){var g;s=null==(g=n[p])||null==(g=g.toString())?void 0:g.trim();break}}if(d!=s)return!1}return!0},e.parse=function(e,r){if(void 0===r&&(r=16),"string"!=typeof e)return null;if(e.includes("*"))return"*";for(var t=new Set,o=0;o<e.length;o++){var i=e[o];if(" "!==i&&"\t"!==i&&","!==i){for(var a=o;o<e.length&&","!==e[o];)o++;var l=e.slice(a,o).trim().toLowerCase();if(0!==l.length&&n.test(l)&&(t.add(l),t.size>=r))break}}return 0===t.size?null:Array.from(t)}});
+//# sourceMappingURL=index.umd.js.map

package/dist/index.umd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.umd.js","sources":["../src/parse.ts","../src/compare.ts"],"sourcesContent":["import type { VaryHeader } from './types';\n\nconst VALID_HEADER_NAME_REGEX = /^[a-z0-9-]+$/i;\n\n/**\n * Parses the Vary header as defined in\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * The Vary header indicates which request headers a server considers when selecting or\n * generating a response, enabling proper HTTP caching behavior.\n *\n * @remarks\n * - Header field names are normalized to lowercase\n * - Duplicate fields are automatically deduplicated\n * - Invalid header names (per RFC 9110) are silently skipped\n * - If the header contains `'*'`, the function returns `'*'` (wildcard)\n * - Returns `null` for invalid input or when no valid fields are found\n *\n * @example\n *\n * ```ts\n * parse('Accept-Encoding, User-Agent');\n * // => ['accept-encoding', 'user-agent']\n *\n * parse('*');\n * // => '*'\n *\n * parse('Invalid Header!');\n * // => null\n * ```\n *\n * @param {string} headerStr - The Vary header value to parse (e.g., \"Accept-Encoding,\n *   User-Agent\")\n * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS\n *   protection. Default is `16`\n * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field\n *   names, `'*'` for wildcard, or `null` if invalid.\n */\nexport function parse(headerStr?: string, maxLength = 16): VaryHeader | null {\n  // Invalid header name\n  if (typeof headerStr !== 'string') {\n    return null;\n  }\n\n  // RFC says only '*' is valid alone, but some servers may send invalid headers like '*, Accept-Encoding'\n  if (headerStr.includes('*')) {\n    return '*';\n  }\n\n  const values = new Set<string>();\n\n  for (let i = 0; i < headerStr.length; i++) {\n    const char = headerStr[i];\n\n    if (char === ' ' || char === '\\t' || char === ',') {\n      continue;\n    }\n\n    const start = i;\n\n    while (i < headerStr.length) {\n      const char = headerStr[i];\n\n      if (char === ',') {\n        break;\n      }\n\n      i++;\n    }\n\n    const headerName = headerStr.slice(start, i).trim().toLowerCase();\n\n    // Skip invalid header names\n    if (headerName.length === 0 || !VALID_HEADER_NAME_REGEX.test(headerName)) {\n      continue;\n    }\n\n    values.add(headerName);\n\n    // DOS protection to avoid overly large vary headers\n    if (values.size >= maxLength) {\n      break;\n    }\n  }\n\n  // Ensures no empty set is returned\n  if (values.size === 0) {\n    return null;\n  }\n\n  return Array.from(values);\n}\n","import type { CompareHeaders, VaryHeader } from './types';\n\n/**\n * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given\n * Vary header, as per\n * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.\n *\n * This function determines if two requests would receive the same cached response based\n * on the Vary header requirements.\n *\n * @remarks\n * - Returns `false` for wildcard vary (`'*'`) as responses always differ\n * - Header name matching is case-insensitive (per RFC 9110)\n * - Missing headers are treated as `undefined`\n * - String values are trimmed before comparison\n * - Array values are converted to strings via `.toString()`\n * - Uses loose equality (!=) for comparison\n * - Empty strings are distinct from missing headers\n *\n * @example\n *\n * ```ts\n * const vary = ['accept-encoding', 'user-agent'];\n * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };\n *\n * compare(vary, headers1, headers2);\n * // => true\n * ```\n *\n * @param {VaryHeader} vary - The Vary header specifying which fields to compare\n * @param {CompareHeaders} source - The first set of request headers\n * @param {CompareHeaders} target - The second set of request headers\n * @returns {boolean} `true` if the headers are equivalent for the given Vary header,\n *   `false` otherwise\n */\nexport function compare(\n  vary: VaryHeader,\n  source: CompareHeaders,\n  target: CompareHeaders\n): boolean {\n  // Wildcard always differs\n  if (vary === '*') {\n    return false;\n  }\n\n  const sourceKeys = Object.keys(source);\n  const targetKeys = Object.keys(target);\n\n  for (const field of vary) {\n    let sourceValue: string | undefined;\n    let targetValue: string | undefined;\n\n    // Case-insensitive header lookup in source\n    for (const key of sourceKeys) {\n      if (key.toLowerCase() === field) {\n        sourceValue = source[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // Case-insensitive header lookup in target\n    for (const key of targetKeys) {\n      if (key.toLowerCase() === field) {\n        targetValue = target[key]?.toString()?.trim();\n        break;\n      }\n    }\n\n    // biome-ignore lint/suspicious/noDoubleEquals: Intentional loose comparison\n    if (sourceValue != targetValue) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"names":["VALID_HEADER_NAME_REGEX","vary","source","target","_step","sourceKeys","Object","keys","targetKeys","_iterator","_createForOfIteratorHelperLoose","done","_step2","field","value","sourceValue","targetValue","_iterator2","key","toLowerCase","_source$key","toString","trim","_step3","_iterator3","_target$_key","headerStr","maxLength","includes","values","Set","i","length","char","start","headerName","slice","test","add","size","Array","from"],"mappings":"sgCAEA,IAAMA,EAA0B,mCCmC9BC,EACAC,EACAC,GAGA,GAAa,MAATF,EACF,OACF,EAKA,IAHA,IAGwBG,EAHlBC,EAAaC,OAAOC,KAAKL,GACzBM,EAAaF,OAAOC,KAAKJ,GAE/BM,EAAAC,EAAoBT,KAAIG,EAAAK,KAAAE,MAAE,CAKxB,IALS,IAKmBC,EALnBC,EAAKT,EAAAU,MACVC,OAA+B,EAC/BC,OAGJ,EAAAC,EAAAP,EAAkBL,KAAUO,EAAAK,KAAAN,MAAE,CAAA,IAAnBO,EAAGN,EAAAE,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAA,IAAAO,EAC/BL,SAAWK,EAAGlB,EAAOgB,KAAgB,OAAZE,EAAXA,EAAaC,iBAAU,EAAvBD,EAAyBE,OACvC,KACF,CACF,CAGA,IAAA,IAA4BC,EAA5BC,EAAAd,EAAkBF,KAAUe,EAAAC,KAAAb,MAAE,CAAnB,IAAAO,EAAGK,EAAAT,MACZ,GAAII,EAAIC,gBAAkBN,EAAO,CAAAY,IAAAA,EAC/BT,EAAyBS,OAAdA,EAAGtB,EAAOe,KAAPO,OAAWA,EAAXA,EAAaJ,iBAAbI,EAAAA,EAAyBH,OACvC,KACF,CACF,CAGA,GAAIP,GAAeC,EACjB,OACF,CACF,CAEA,OACF,CAAA,mBDtCsBU,EAAoBC,GAExC,YAFwCA,IAAAA,EAAY,IAE3B,iBAAdD,EACT,OACF,KAGA,GAAIA,EAAUE,SAAS,KACrB,MAAO,IAKT,IAFA,IAAMC,EAAS,IAAIC,IAEVC,EAAI,EAAGA,EAAIL,EAAUM,OAAQD,IAAK,CACzC,IAAME,EAAOP,EAAUK,GAEvB,GAAa,MAATE,GAAyB,OAATA,GAA0B,MAATA,EAArC,CAMA,IAFA,IAAMC,EAAQH,EAEPA,EAAIL,EAAUM,QAGN,MAFAN,EAAUK,IAMvBA,IAGF,IAAMI,EAAaT,EAAUU,MAAMF,EAAOH,GAAGT,OAAOH,cAGpD,GAA0B,IAAtBgB,EAAWH,QAAiBhC,EAAwBqC,KAAKF,KAI7DN,EAAOS,IAAIH,GAGPN,EAAOU,MAAQZ,GACjB,KAzBF,CA2BF,CAGA,OAAoB,IAAhBE,EAAOU,KACF,KAGFC,MAAMC,KAAKZ,EACpB"}

package/dist/parse.d.ts

@@ -0,0 +1,37 @@
+import type { VaryHeader } from './types';
+/**
+ * Parses the Vary header as defined in
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * The Vary header indicates which request headers a server considers when selecting or
+ * generating a response, enabling proper HTTP caching behavior.
+ *
+ * @remarks
+ * - Header field names are normalized to lowercase
+ * - Duplicate fields are automatically deduplicated
+ * - Invalid header names (per RFC 9110) are silently skipped
+ * - If the header contains `'*'`, the function returns `'*'` (wildcard)
+ * - Returns `null` for invalid input or when no valid fields are found
+ *
+ * @example
+ *
+ * ```ts
+ * parse('Accept-Encoding, User-Agent');
+ * // => ['accept-encoding', 'user-agent']
+ *
+ * parse('*');
+ * // => '*'
+ *
+ * parse('Invalid Header!');
+ * // => null
+ * ```
+ *
+ * @param {string} headerStr - The Vary header value to parse (e.g., "Accept-Encoding,
+ *   User-Agent")
+ * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS
+ *   protection. Default is `16`
+ * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field
+ *   names, `'*'` for wildcard, or `null` if invalid.
+ */
+export declare function parse(headerStr?: string, maxLength?: number): VaryHeader | null;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,UAAU,GAAG,IAAI,CAqD3E"}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Type representing the Vary header as defined in
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * The Vary header field indicates which request headers affect the response, enabling
+ * proper cache key generation.
+ *
+ * - `'*'` - Wildcard indicating the response varies on aspects beyond headers
+ * - `string[]` - Array of lowercase header field names that affect the response
+ *
+ * @remarks
+ * The array is never empty and all header names are normalized to lowercase.
+ */
+export type VaryHeader = string[] | '*';
+/**
+ * Type representing HTTP headers. Header values can be strings, arrays of strings, or
+ * undefined.
+ */
+export type HttpHeaders = Record<string, string | string[] | undefined>;
+/**
+ * Type representing HTTP headers for comparison. Values must be strings or arrays (no
+ * undefined).
+ */
+export type CompareHeaders = Record<string, string | string[]>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "http-vary",
+  "version": "0.0.1",
+  "description": "A minimal parser and utility for the HTTP Vary header.",
+  "keywords": [
+    "vary",
+    "http",
+    "header",
+    "headers",
+    "cache",
+    "caching",
+    "http-cache",
+    "vary-header",
+    "rfc9110",
+    "rfc9111",
+    "cache-key",
+    "parser"
+  ],
+  "homepage": "https://tinylibs.js.org/packages/http-vary",
+  "bugs": "https://github.com/arthurfiorette/tinylibs/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arthurfiorette/tinylibs.git",
+    "directory": "packages/http-vary"
+  },
+  "license": "MIT",
+  "author": "Arthur Fiorette <npm@arthur.place>",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "umd:main": "dist/index.umd.js",
+  "unpkg": "dist/index.umd.js",
+  "module": "dist/index.mjs",
+  "source": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "microbundle --tsconfig tsconfig.build.json",
+    "test": "jest --coverage"
+  },
+  "devDependencies": {
+    "microbundle": "catalog:bundle"
+  }
+}

package/src/compare.ts

@@ -0,0 +1,77 @@
+import type { CompareHeaders, VaryHeader } from './types';
+
+/**
+ * Checks if {@linkcode source} and {@linkcode target} headers are equivalent for the given
+ * Vary header, as per
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * This function determines if two requests would receive the same cached response based
+ * on the Vary header requirements.
+ *
+ * @remarks
+ * - Returns `false` for wildcard vary (`'*'`) as responses always differ
+ * - Header name matching is case-insensitive (per RFC 9110)
+ * - Missing headers are treated as `undefined`
+ * - String values are trimmed before comparison
+ * - Array values are converted to strings via `.toString()`
+ * - Uses loose equality (!=) for comparison
+ * - Empty strings are distinct from missing headers
+ *
+ * @example
+ *
+ * ```ts
+ * const vary = ['accept-encoding', 'user-agent'];
+ * const headers1 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };
+ * const headers2 = { 'Accept-Encoding': 'gzip', 'User-Agent': 'Chrome' };
+ *
+ * compare(vary, headers1, headers2);
+ * // => true
+ * ```
+ *
+ * @param {VaryHeader} vary - The Vary header specifying which fields to compare
+ * @param {CompareHeaders} source - The first set of request headers
+ * @param {CompareHeaders} target - The second set of request headers
+ * @returns {boolean} `true` if the headers are equivalent for the given Vary header,
+ *   `false` otherwise
+ */
+export function compare(
+  vary: VaryHeader,
+  source: CompareHeaders,
+  target: CompareHeaders
+): boolean {
+  // Wildcard always differs
+  if (vary === '*') {
+    return false;
+  }
+
+  const sourceKeys = Object.keys(source);
+  const targetKeys = Object.keys(target);
+
+  for (const field of vary) {
+    let sourceValue: string | undefined;
+    let targetValue: string | undefined;
+
+    // Case-insensitive header lookup in source
+    for (const key of sourceKeys) {
+      if (key.toLowerCase() === field) {
+        sourceValue = source[key]?.toString()?.trim();
+        break;
+      }
+    }
+
+    // Case-insensitive header lookup in target
+    for (const key of targetKeys) {
+      if (key.toLowerCase() === field) {
+        targetValue = target[key]?.toString()?.trim();
+        break;
+      }
+    }
+
+    // biome-ignore lint/suspicious/noDoubleEquals: Intentional loose comparison
+    if (sourceValue != targetValue) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './compare';
+export * from './parse';
+export * from './types';

package/src/parse.ts

@@ -0,0 +1,92 @@
+import type { VaryHeader } from './types';
+
+const VALID_HEADER_NAME_REGEX = /^[a-z0-9-]+$/i;
+
+/**
+ * Parses the Vary header as defined in
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * The Vary header indicates which request headers a server considers when selecting or
+ * generating a response, enabling proper HTTP caching behavior.
+ *
+ * @remarks
+ * - Header field names are normalized to lowercase
+ * - Duplicate fields are automatically deduplicated
+ * - Invalid header names (per RFC 9110) are silently skipped
+ * - If the header contains `'*'`, the function returns `'*'` (wildcard)
+ * - Returns `null` for invalid input or when no valid fields are found
+ *
+ * @example
+ *
+ * ```ts
+ * parse('Accept-Encoding, User-Agent');
+ * // => ['accept-encoding', 'user-agent']
+ *
+ * parse('*');
+ * // => '*'
+ *
+ * parse('Invalid Header!');
+ * // => null
+ * ```
+ *
+ * @param {string} headerStr - The Vary header value to parse (e.g., "Accept-Encoding,
+ *   User-Agent")
+ * @param {number} [maxLength=16] - Maximum number of header fields to parse for DoS
+ *   protection. Default is `16`
+ * @returns {VaryHeader | null} The parsed Vary header as an array of lowercase field
+ *   names, `'*'` for wildcard, or `null` if invalid.
+ */
+export function parse(headerStr?: string, maxLength = 16): VaryHeader | null {
+  // Invalid header name
+  if (typeof headerStr !== 'string') {
+    return null;
+  }
+
+  // RFC says only '*' is valid alone, but some servers may send invalid headers like '*, Accept-Encoding'
+  if (headerStr.includes('*')) {
+    return '*';
+  }
+
+  const values = new Set<string>();
+
+  for (let i = 0; i < headerStr.length; i++) {
+    const char = headerStr[i];
+
+    if (char === ' ' || char === '\t' || char === ',') {
+      continue;
+    }
+
+    const start = i;
+
+    while (i < headerStr.length) {
+      const char = headerStr[i];
+
+      if (char === ',') {
+        break;
+      }
+
+      i++;
+    }
+
+    const headerName = headerStr.slice(start, i).trim().toLowerCase();
+
+    // Skip invalid header names
+    if (headerName.length === 0 || !VALID_HEADER_NAME_REGEX.test(headerName)) {
+      continue;
+    }
+
+    values.add(headerName);
+
+    // DOS protection to avoid overly large vary headers
+    if (values.size >= maxLength) {
+      break;
+    }
+  }
+
+  // Ensures no empty set is returned
+  if (values.size === 0) {
+    return null;
+  }
+
+  return Array.from(values);
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Type representing the Vary header as defined in
+ * {@link https://www.rfc-editor.org/rfc/rfc9110.html#name-vary RFC 9110 Section 12.5.5}.
+ *
+ * The Vary header field indicates which request headers affect the response, enabling
+ * proper cache key generation.
+ *
+ * - `'*'` - Wildcard indicating the response varies on aspects beyond headers
+ * - `string[]` - Array of lowercase header field names that affect the response
+ *
+ * @remarks
+ * The array is never empty and all header names are normalized to lowercase.
+ */
+export type VaryHeader = string[] | '*';
+
+/**
+ * Type representing HTTP headers. Header values can be strings, arrays of strings, or
+ * undefined.
+ */
+export type HttpHeaders = Record<string, string | string[] | undefined>;
+
+/**
+ * Type representing HTTP headers for comparison. Values must be strings or arrays (no
+ * undefined).
+ */
+export type CompareHeaders = Record<string, string | string[]>;