3 [![NPM Version][npm-image]][npm-url]
4 [![NPM Downloads][downloads-image]][downloads-url]
5 [![Node.js Version][node-version-image]][node-version-url]
6 [![Build Status][travis-image]][travis-url]
7 [![Test Coverage][coveralls-image]][coveralls-url]
9 HTTP response freshness testing
13 This is a [Node.js](https://nodejs.org/en/) module available through the
14 [npm registry](https://www.npmjs.com/). Installation is done using the
15 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
23 <!-- eslint-disable no-unused-vars -->
26 var fresh = require('fresh')
29 ### fresh(reqHeaders, resHeaders)
31 Check freshness of the response using request and response headers.
33 When the response is still "fresh" in the client's cache `true` is
34 returned, otherwise `false` is returned to indicate that the client
35 cache is now stale and the full response should be sent.
37 When a client sends the `Cache-Control: no-cache` request header to
38 indicate an end-to-end reload request, this module will return `false`
39 to make handling these requests transparent.
43 This module is designed to only follow the HTTP specifications, not
44 to work-around all kinda of client bugs (especially since this module
45 typically does not recieve enough information to understand what the
48 There is a known issue that in certain versions of Safari, Safari
49 will incorrectly make a request that allows this module to validate
50 freshness of the resource even when Safari does not have a
51 representation of the resource in the cache. The module
52 [jumanji](https://www.npmjs.com/package/jumanji) can be used in
53 an Express application to work-around this issue and also provides
54 links to further reading on this Safari bug.
60 <!-- eslint-disable no-redeclare, no-undef -->
63 var reqHeaders = { 'if-none-match': '"foo"' }
64 var resHeaders = { 'etag': '"bar"' }
65 fresh(reqHeaders, resHeaders)
68 var reqHeaders = { 'if-none-match': '"foo"' }
69 var resHeaders = { 'etag': '"foo"' }
70 fresh(reqHeaders, resHeaders)
74 ### Using with Node.js http server
77 var fresh = require('fresh')
78 var http = require('http')
80 var server = http.createServer(function (req, res) {
81 // perform server logic
82 // ... including adding ETag / Last-Modified response headers
84 if (isFresh(req, res)) {
85 // client has a fresh copy of resource
93 res.end('hello, world!')
96 function isFresh (req, res) {
97 return fresh(req.headers, {
98 'etag': res.getHeader('ETag'),
99 'last-modified': res.getHeader('Last-Modified')
110 [npm-image]: https://img.shields.io/npm/v/fresh.svg
111 [npm-url]: https://npmjs.org/package/fresh
112 [node-version-image]: https://img.shields.io/node/v/fresh.svg
113 [node-version-url]: https://nodejs.org/en/
114 [travis-image]: https://img.shields.io/travis/jshttp/fresh/master.svg
115 [travis-url]: https://travis-ci.org/jshttp/fresh
116 [coveralls-image]: https://img.shields.io/coveralls/jshttp/fresh/master.svg
117 [coveralls-url]: https://coveralls.io/r/jshttp/fresh?branch=master
118 [downloads-image]: https://img.shields.io/npm/dm/fresh.svg
119 [downloads-url]: https://npmjs.org/package/fresh