tinylibs
⌛
HTTP Vary
HTTP Vary is a minimal parser and utility for the Vary header (RFC 9110).
Table of Contents
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.
