[](https://github.com/arthurfiorette/tinylibs/issues)
[](https://github.com/arthurfiorette/tinylibs/stargazers)
[](https://github.com/arthurfiorette/tinylibs/blob/main/LICENSE)
[](https://codecov.io/gh/arthurfiorette/tinylibs)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs?ref=badge_shield)
[](https://gitter.im/tinylibs-js-org/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://twitter.com/acdlite/status/974390255393505280)
[](https://www.npmjs.com/package/http-vary)
[](https://www.npmjs.com/package/http-vary)
[](https://www.jsdelivr.com/package/npm/http-vary)
[](https://bundlephobia.com/package/http-vary@latest)
[](https://packagephobia.com/result?p=http-vary@latest)
HTTP Vary is a minimal parser and utility for the Vary header (RFC 9110).
## 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)
## 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
```
```js
const { parse, compare } = window.httpVary;
```
### Url Import
```ts
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](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)
```
## 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.
## License
Licensed under the **MIT**. See [`LICENSE`](LICENSE) for more informations.
[](https://app.fossa.com/projects/git%2Bgithub.com%2Farthurfiorette%2Ftinylibs?ref=badge_small)