Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

fresh

jshttp99.6mMIT0.5.2TypeScript support: definitely-typed

HTTP response freshness testing

fresh, http, conditional, cache

readme

fresh

NPM Version NPM Downloads Node.js Version Build Status Test Coverage

HTTP response freshness testing

Installation

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

$ npm install fresh

API

var fresh = require('fresh')

fresh(reqHeaders, resHeaders)

Check freshness of the response using request and response headers.

When the response is still "fresh" in the client's cache true is returned, otherwise false is returned to indicate that the client cache is now stale and the full response should be sent.

When a client sends the Cache-Control: no-cache request header to indicate an end-to-end reload request, this module will return false to make handling these requests transparent.

Known Issues

This module is designed to only follow the HTTP specifications, not to work-around all kinda of client bugs (especially since this module typically does not recieve enough information to understand what the client actually is).

There is a known issue that in certain versions of Safari, Safari will incorrectly make a request that allows this module to validate freshness of the resource even when Safari does not have a representation of the resource in the cache. The module jumanji can be used in an Express application to work-around this issue and also provides links to further reading on this Safari bug.

Example

API usage

var reqHeaders = { 'if-none-match': '"foo"' }
var resHeaders = { 'etag': '"bar"' }
fresh(reqHeaders, resHeaders)
// => false

var reqHeaders = { 'if-none-match': '"foo"' }
var resHeaders = { 'etag': '"foo"' }
fresh(reqHeaders, resHeaders)
// => true

Using with Node.js http server

var fresh = require('fresh')
var http = require('http')

var server = http.createServer(function (req, res) {
  // perform server logic
  // ... including adding ETag / Last-Modified response headers

  if (isFresh(req, res)) {
    // client has a fresh copy of resource
    res.statusCode = 304
    res.end()
    return
  }

  // send the resource
  res.statusCode = 200
  res.end('hello, world!')
})

function isFresh (req, res) {
  return fresh(req.headers, {
    'etag': res.getHeader('ETag'),
    'last-modified': res.getHeader('Last-Modified')
  })
}

server.listen(3000)

License

MIT

changelog

0.5.2 / 2017-09-13

  • Fix regression matching multiple ETags in If-None-Match
  • perf: improve If-None-Match token parsing

0.5.1 / 2017-09-11

  • Fix handling of modified headers with invalid dates
  • perf: improve ETag match loop

0.5.0 / 2017-02-21

  • Fix incorrect result when If-None-Match has both * and ETags
  • Fix weak ETag matching to match spec
  • perf: delay reading header values until needed
  • perf: skip checking modified time if ETag check failed
  • perf: skip parsing If-None-Match when no ETag header
  • perf: use Date.parse instead of new Date

0.4.0 / 2017-02-05

  • Fix false detection of no-cache request directive
  • perf: enable strict mode
  • perf: hoist regular expressions
  • perf: remove duplicate conditional
  • perf: remove unnecessary boolean coercions

0.3.0 / 2015-05-12

  • Add weak ETag matching support

0.2.4 / 2014-09-07

  • Support Node.js 0.6

0.2.3 / 2014-09-07

  • Move repository to jshttp

0.2.2 / 2014-02-19

  • Revert "Fix for blank page on Safari reload"

0.2.1 / 2014-01-29

  • Fix for blank page on Safari reload

0.2.0 / 2013-08-11

  • Return stale for Cache-Control: no-cache

0.1.0 / 2012-06-15

  • Add If-None-Match: * support

0.0.1 / 2012-06-10

  • Initial release