Table of Contents

• Table of Contents
• Installing
  • Node
  • Browser
  • Url Import
• Getting Started
  • Usage
• Understanding Wildcard Behavior
• License

Installing

Node

npm install http-vary # or yarn add http-vary

const { parse, compare } = require('http-vary');
import { parse, compare } from 'http-vary';

Browser

<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/http-vary@latest/dist/index.umd.js"
></script>

const { parse, compare } = window.httpVary;

Url Import

import { parse, compare } from 'https://cdn.skypack.dev/http-vary@latest';

Getting Started

This package is a parser and utility for the HTTP Vary header as defined in RFC 9110 Section 12.5.5. The Vary header indicates which request headers affect the response, enabling proper HTTP caching behavior. You can parse a Vary header string with parse() and compare request headers for cache equivalence with compare().

All needed documentation is available in form of TSDoc comments.

Usage

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)

Understanding Wildcard Behavior

Per RFC 9110, 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.

License

Licensed under the MIT. See LICENSE for more informations.