{"id":11059,"library":"http-vary","title":"HTTP Vary Header Parser and Utility","description":"http-vary is a lightweight, RFC 9110 compliant utility designed for parsing and comparing HTTP Vary headers, which are crucial for ensuring correct HTTP caching behavior. It provides two primary functions: `parse()`, which normalizes a Vary header string into an array of lowercase header names (or a wildcard `'*'`), and `compare()`, used to determine if two sets of request headers are cache-equivalent based on a specified Vary header. The package is currently at version 1.0.3 and is part of the 'tinylibs' monorepo, suggesting a consistent, albeit independent, patch release cadence. Its core strength lies in its minimal footprint and strict adherence to RFC 9110, focusing exclusively on the Vary header without extraneous caching logic. This makes it ideal for environments demanding precise control over HTTP caching mechanisms. It also ships with comprehensive TypeScript types, enhancing developer experience and type safety.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/arthurfiorette/tinylibs","tags":["javascript","vary","http","header","headers","cache","caching","http-cache","vary-header","typescript"],"install":[{"cmd":"npm install http-vary","lang":"bash","label":"npm"},{"cmd":"yarn add http-vary","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-vary","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"http-vary primarily uses named exports. For CommonJS, destructure directly.","wrong":"const parse = require('http-vary').parse","symbol":"parse","correct":"import { parse } from 'http-vary'"},{"note":"There is no default export; symbols must be imported by name. CommonJS users should destructure from require().","wrong":"import httpVary from 'http-vary'; const compare = httpVary.compare;","symbol":"compare","correct":"import { compare } from 'http-vary'"},{"note":"When importing only types in TypeScript, use 'import type' for better tree-shaking and clarity.","wrong":"import { VaryHeader } from 'http-vary'","symbol":"VaryHeader (type)","correct":"import type { VaryHeader } from 'http-vary'"}],"quickstart":{"code":"import { parse, compare, VaryHeader } from 'http-vary';\n\n// Parse a Vary header string into a normalized array of header names.\nconst rawHeader: string = 'Accept-Encoding, User-Agent';\nconst vary: VaryHeader = parse(rawHeader);\nconsole.log('Parsed Vary header:', vary); // => ['accept-encoding', 'user-agent']\n\n// Handle the wildcard Vary header, which means the response varies by everything.\nconst wildcardVary: VaryHeader = parse('*');\nconsole.log('Parsed wildcard Vary header:', wildcardVary); // => '*'\n\n// Define two sets of request headers to compare for cache equivalence.\nconst headers1 = {\n  'Accept-Encoding': 'gzip',\n  'User-Agent': 'Chrome/120.0'\n};\n\nconst headers2 = {\n  'Accept-Encoding': 'gzip',\n  'User-Agent': 'Chrome/120.0',\n  'Cookie': 'session=abc' // This header should be ignored if not in the Vary list\n};\n\n// Compare headers for cache equivalence based on the parsed Vary header.\nconst isEquivalent1: boolean = compare(vary, headers1, headers2);\nconsole.log('Headers 1 and 2 are equivalent (Accept-Encoding, User-Agent):', isEquivalent1); // true\n\nconst headers3 = {\n  'Accept-Encoding': 'br',\n  'User-Agent': 'Firefox/120.0'\n};\n\nconst isEquivalent2: boolean = compare(vary, headers1, headers3);\nconsole.log('Headers 1 and 3 are equivalent (Accept-Encoding, User-Agent):', isEquivalent2); // false (different values)\n\nconst headers4 = {\n  'Accept-Encoding': 'gzip',\n  'User-Agent': 'Chrome/121.0'\n};\n\nconst isEquivalent3: boolean = compare(wildcardVary, headers1, headers4);\nconsole.log('Headers 1 and 4 are equivalent (*):', isEquivalent3); // false (wildcard makes even minor changes relevant)","lang":"typescript","description":"This quickstart demonstrates how to parse a Vary header string and use the `compare` function to check if two sets of request headers are cache-equivalent according to the Vary header, including handling the wildcard ('*') case."},"warnings":[{"fix":"Rely on `http-vary`'s internal normalization. Ensure input headers are consistent or processed before passing, if manual normalization is preferred outside of `compare`.","message":"The `compare` function implicitly normalizes header names to lowercase for comparison. While HTTP header names are case-insensitive, inconsistent casing in input headers provided to `compare` might lead to unexpected results if not handled by the library, though `http-vary` aims to mitigate this.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Understand that `Vary: *` implies a highly specific or uncacheable resource. If `compare()` is called with a wildcard Vary header, it will return `false` unless the two sets of headers are strictly identical. Avoid `Vary: *` unless absolutely necessary and its implications are fully understood.","message":"When the Vary header is `*` (wildcard), it signifies that the response varies by *any* request header not explicitly defined in RFC 9110 (such as `Authorization` or `Cookie`). This effectively makes the response uncacheable for shared caches and highly problematic for private caches, as even minor, irrelevant header changes will invalidate the cache.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure applications are compatible with the `1.0.0` API, which is stable. Minor patch releases have only included bug fixes and type improvements.","message":"The initial major release `http-vary@1.0.0` established the API. While there have been no subsequent breaking changes in `http-vary` itself, it's important to note that this marks the stable API baseline.","severity":"breaking","affected_versions":"=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use named imports for ESM (`import { parse, compare } from 'http-vary';`) or direct destructuring for CommonJS (`const { parse, compare } = require('http-vary');`).","cause":"Attempting to import `parse` or `compare` using a default import syntax, or incorrectly using CommonJS `require()` without destructuring.","error":"TypeError: (0 , http_vary__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function"},{"fix":"Verify the exact names of the exported functions (`parse`, `compare`) and types (`VaryHeader`). For types, use `import type { VaryHeader } from 'http-vary';`.","cause":"Trying to import a symbol that is not exported by the `http-vary` package, or a type/interface without `type` keyword.","error":"TS2305: Module '\"http-vary\"' has no exported member 'SomeNonExistentExport'."},{"fix":"Review the RFC 9110 specification for `Vary: *`. If `Vary: *` is present, `http-vary`'s `compare` function will return `false` if *any* header differs, which is correct behavior. Avoid `Vary: *` unless explicit uncacheability is desired for shared caches.","cause":"Misunderstanding the implications of a `Vary: *` header, which indicates that the response depends on virtually all request headers, rendering it practically uncacheable.","error":"Caching issues when using Vary: *"}],"ecosystem":"npm"}