or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vary

Manipulate the HTTP Vary header

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vary@1.1.x

To install, run

npx @tessl/cli install tessl/npm-vary@1.1.0

index.mddocs/

Vary

Vary is a Node.js utility library for manipulating HTTP Vary headers. It enables web applications to properly indicate which request headers affect the response content for HTTP caching and content negotiation. The library provides functions to set Vary headers on HTTP response objects and build Vary header strings programmatically.

Package Information

  • Package Name: vary
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install vary

Core Imports

const vary = require('vary');

ESM:

import vary from 'vary';
// Named imports not supported - use default import

Basic Usage

const http = require('http');
const vary = require('vary');

http.createServer(function onRequest (req, res) {
  // Mark that response content varies based on User-Agent
  vary(res, 'User-Agent');
  
  const ua = req.headers['user-agent'] || '';
  const isMobile = /mobi|android|touch|mini/i.test(ua);
  
  res.setHeader('Content-Type', 'text/html');
  res.end('You are (probably) ' + (isMobile ? '' : 'not ') + 'a mobile user');
});

Architecture

The vary library implements HTTP Vary header manipulation through two key components:

  • Main Function (vary): Modifies HTTP response objects directly by reading existing Vary headers and appending new field names while preserving case and preventing duplicates
  • Utility Function (vary.append): Provides string manipulation for Vary header values without requiring an HTTP response object, enabling middleware and programmatic header construction
  • Field Parsing: Internal comma-separated value parser handles RFC 7230 compliant field name extraction and validation
  • Case Preservation: Maintains original case of field names while performing case-insensitive duplicate detection
  • Wildcard Handling: Special logic for the "*" field value that indicates response varies on all possible headers

Capabilities

Set Vary Header on Response

Adds header field(s) to the Vary response header of an HTTP response object, ensuring proper cache control for content that depends on specific request headers.

/**
 * Mark that a request is varied on a header field
 * @param {Object} res - HTTP response object with getHeader/setHeader methods
 * @param {String|Array} field - Header field name(s) to add to Vary header
 * @throws {TypeError} If res is invalid or field contains invalid header names
 */
function vary(res, field);

Usage Examples:

const http = require('http');
const vary = require('vary');

// Single header field
vary(res, 'Origin');

// Multiple header fields as array
vary(res, ['Accept', 'User-Agent']);

// Multiple header fields as comma-separated string
vary(res, 'Accept, User-Agent');

// Wildcard - indicates response varies on all headers
vary(res, '*');

Behavior:

  • Appends field if not already listed, preserves existing location if already present
  • Performs case-insensitive comparison but preserves original case
  • Special handling for wildcard (*) - overrides all other fields
  • Validates field names against RFC 7230 specification
  • Works with any object having getHeader() and setHeader() methods

Build Vary Header String

Creates or appends to a Vary header string without modifying an HTTP response object. Useful for programmatic header construction and middleware that needs to build headers before setting them.

/**
 * Append a field to a vary header string
 * @param {String} header - Existing Vary header value
 * @param {String|Array} field - Header field name(s) to append
 * @returns {String} Updated header value
 * @throws {TypeError} If header is not string or field contains invalid header names
 */
vary.append = function append(header, field);

Usage Examples:

const vary = require('vary');

// Build from empty header
const header1 = vary.append('', 'Origin');
// Result: "Origin"

// Append to existing header
const header2 = vary.append('Accept', 'User-Agent');
// Result: "Accept, User-Agent"

// Append multiple fields
const header3 = vary.append('Accept', ['Origin', 'User-Agent']);
// Result: "Accept, Origin, User-Agent"

// Wildcard handling
const header4 = vary.append('Accept, Origin', '*');
// Result: "*"

Behavior:

  • Returns new header string with field(s) appended
  • Handles case-insensitive deduplication while preserving case
  • Supports wildcard (*) behavior - returns * when wildcard is present
  • Validates field names using RFC 7230 compliant regex
  • Processes comma-separated field strings and arrays identically

Error Handling

Both functions throw TypeError for invalid arguments:

// Invalid response object
vary({}, 'Origin'); // TypeError: res argument is required

// Invalid header argument
vary.append(42, 'Origin'); // TypeError: header argument is required

// Missing field argument
vary(res); // TypeError: field argument is required
vary.append('Accept'); // TypeError: field argument is required

// Invalid field names (violate RFC 7230)
vary(res, 'invalid:header'); // TypeError: field argument contains an invalid header name
vary(res, 'invalid header'); // TypeError: field argument contains an invalid header name
vary.append('', 'invalid\nheader'); // TypeError: field argument contains an invalid header name

Types

// HTTP Response-like object (Node.js http.ServerResponse or compatible)
interface ResponseLike {
  getHeader(name: string): string | string[] | undefined;
  setHeader(name: string, value: string): void;
}

// Field specification types
type FieldSpec = string | string[];

// Header field name validation
const FIELD_NAME_REGEXP = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;