HTTP Vary Header Parser and Utility

Common errors

• TypeError: (0 , http_vary__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function

  cause Attempting to import `parse` or `compare` using a default import syntax, or incorrectly using CommonJS `require()` without destructuring.
  fix Use named imports for ESM (`import { parse, compare } from 'http-vary';`) or direct destructuring for CommonJS (`const { parse, compare } = require('http-vary');`).

• TS2305: Module '"http-vary"' has no exported member 'SomeNonExistentExport'.

  cause Trying to import a symbol that is not exported by the `http-vary` package, or a type/interface without `type` keyword.
  fix Verify the exact names of the exported functions (`parse`, `compare`) and types (`VaryHeader`). For types, use `import type { VaryHeader } from 'http-vary';`.

• Caching issues when using Vary: *

  cause Misunderstanding the implications of a `Vary: *` header, which indicates that the response depends on virtually all request headers, rendering it practically uncacheable.
  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.

Warnings

• gotcha 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.
  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`.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install http-vary npm
• yarn add http-vary yarn
• pnpm add http-vary pnpm

Imports

• parse
  wrong:

  const parse = require('http-vary').parse

  correct:

  import { parse } from 'http-vary'

  http-vary primarily uses named exports. For CommonJS, destructure directly.
• compare
  wrong:

  import httpVary from 'http-vary'; const compare = httpVary.compare;

  correct:

  import { compare } from 'http-vary'

  There is no default export; symbols must be imported by name. CommonJS users should destructure from require().
• VaryHeader (type)
  wrong:

  import { VaryHeader } from 'http-vary'

  correct:

  import type { VaryHeader } from 'http-vary'

  When importing only types in TypeScript, use 'import type' for better tree-shaking and clarity.

Quickstart

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.

import { parse, compare, VaryHeader } from 'http-vary';

// Parse a Vary header string into a normalized array of header names.
const rawHeader: string = 'Accept-Encoding, User-Agent';
const vary: VaryHeader = parse(rawHeader);
console.log('Parsed Vary header:', vary); // => ['accept-encoding', 'user-agent']

// Handle the wildcard Vary header, which means the response varies by everything.
const wildcardVary: VaryHeader = parse('*');
console.log('Parsed wildcard Vary header:', wildcardVary); // => '*'

// Define two sets of request headers to compare for cache equivalence.
const headers1 = {
  'Accept-Encoding': 'gzip',
  'User-Agent': 'Chrome/120.0'
};

const headers2 = {
  'Accept-Encoding': 'gzip',
  'User-Agent': 'Chrome/120.0',
  'Cookie': 'session=abc' // This header should be ignored if not in the Vary list
};

// Compare headers for cache equivalence based on the parsed Vary header.
const isEquivalent1: boolean = compare(vary, headers1, headers2);
console.log('Headers 1 and 2 are equivalent (Accept-Encoding, User-Agent):', isEquivalent1); // true

const headers3 = {
  'Accept-Encoding': 'br',
  'User-Agent': 'Firefox/120.0'
};

const isEquivalent2: boolean = compare(vary, headers1, headers3);
console.log('Headers 1 and 3 are equivalent (Accept-Encoding, User-Agent):', isEquivalent2); // false (different values)

const headers4 = {
  'Accept-Encoding': 'gzip',
  'User-Agent': 'Chrome/121.0'
};

const isEquivalent3: boolean = compare(wildcardVary, headers1, headers4);
console.log('Headers 1 and 4 are equivalent (*):', isEquivalent3); // false (wildcard makes even minor changes relevant)