http-cache-semantics

What is http-cache-semantics?

The http-cache-semantics package is designed to provide a way to interpret HTTP caching headers and make decisions based on them. It helps in implementing HTTP caching compliant with the RFC 7234 standard. The package can be used to parse cache headers, compute cache freshness, and determine the correct caching behavior for requests and responses.

What are http-cache-semantics's main functionalities?

Parsing Cache Headers

This feature allows you to parse the cache-related headers from HTTP requests and responses. It creates a new CachePolicy object that can be used to determine various caching behaviors.

{"const CachePolicy = require('http-cache-semantics');\nconst policy = new CachePolicy(requestHeaders, responseHeaders);\nconst ttl = policy.timeToLive();"}

Computing Cache Freshness

This feature is used to compute whether a cached response is still fresh or if it needs revalidation. It helps in deciding whether to serve the cached response or to make a new request to the origin server.

{"const CachePolicy = require('http-cache-semantics');\nconst policy = new CachePolicy(requestHeaders, responseHeaders);\nconst isFresh = policy.satisfiesWithoutRevalidation(requestHeaders);"}

Updating Cached Responses

This feature is used to update the cache policy object with new response headers, which is useful when a cached response has been revalidated with the origin server.

{"const CachePolicy = require('http-cache-semantics');\nconst policy = new CachePolicy(requestHeaders, responseHeaders);\nconst updatedPolicy = policy.revalidatedPolicy(requestHeaders, newResponseHeaders);"}

Other packages similar to http-cache-semantics

cache-control

The cache-control package is similar to http-cache-semantics in that it provides utilities for parsing and manipulating the Cache-Control HTTP header. However, it does not offer the full range of caching decision logic that http-cache-semantics provides.

keyv

Keyv is a simple key-value storage with support for multiple backends. It can be used for caching but is more general-purpose and does not specifically interpret HTTP cache headers or follow the RFC 7234 standard.

README

HTTP cache semantics

CachePolicy object that computes properties of a HTTP response, such as whether it's fresh or stale, and how long it can be cached for. Based on RFC 7234.

Usage

const cache = new CachePolicy(request, response, options);

// Age counts from the time response has been created
const secondsFresh = cache.maxAge();
const secondsOld = cache.age();

// Current state
const outOfDate = cache.stale();

Cacheability of response depends on how it was requested, so both request and response are required. Both are objects with headers property that is an object with lowercased header names as keys, e.g.

const request = {
    method: 'GET',
    headers: {
        'accept': '*/*',
    },
};

const response = {
    status: 200,
    headers: {
        'cache-control': 'public, max-age=7234',
    },
};

const options = {
    shared: true,
};

If options.shared is true (default), then response is evaluated from perspective of a shared cache (i.e. private is not cacheable and s-maxage is respected). If options.shared is false, then response is evaluated from perspective of a single-user cache (i.e. private is cacheable and s-maxage is ignored).

stale()

Returns true if the response is stale (i.e. not fresh).

It generally means the response can't be used any more without revalidation with the server. However, there are exceptions, e.g. client can explicitly allow stale responses. A fresh response still may not be used if other conditions—such as Vary—are not satisfied.

cacheKey()

Returns a string that is a combination of method, URL, and headers selected with Vary.

Note that Vary: * never matches any request, so matching of cache keys alone is not sufficient to satisfy a request.

Implemented

• Expires with check for bad clocks
• Cache-Control response header
• Pragma response header
• Age response header
• Default cacheability of statuses and methods
• Basic support for Vary

Unimplemented

• No support for revalidation and stale responses