README.md

   1 # fresh
   2
   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]
   8
   9 HTTP response freshness testing
  10
  11 ## Installation
  12
  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):
  16
  17 ```
  18 $ npm install fresh
  19 ```
  20
  21 ## API
  22
  23 <!-- eslint-disable no-unused-vars -->
  24
  25 ```js
  26 var fresh = require('fresh')
  27 ```
  28
  29 ### fresh(reqHeaders, resHeaders)
  30
  31 Check freshness of the response using request and response headers.
  32
  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.
  36
  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.
  40
  41 ## Known Issues
  42
  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
  46 client actually is).
  47
  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.
  55
  56 ## Example
  57
  58 ### API usage
  59
  60 <!-- eslint-disable no-redeclare, no-undef -->
  61
  62 ```js
  63 var reqHeaders = { 'if-none-match': '"foo"' }
  64 var resHeaders = { 'etag': '"bar"' }
  65 fresh(reqHeaders, resHeaders)
  66 // => false
  67
  68 var reqHeaders = { 'if-none-match': '"foo"' }
  69 var resHeaders = { 'etag': '"foo"' }
  70 fresh(reqHeaders, resHeaders)
  71 // => true
  72 ```
  73
  74 ### Using with Node.js http server
  75
  76 ```js
  77 var fresh = require('fresh')
  78 var http = require('http')
  79
  80 var server = http.createServer(function (req, res) {
  81   // perform server logic
  82   // ... including adding ETag / Last-Modified response headers
  83
  84   if (isFresh(req, res)) {
  85     // client has a fresh copy of resource
  86     res.statusCode = 304
  87     res.end()
  88     return
  89   }
  90
  91   // send the resource
  92   res.statusCode = 200
  93   res.end('hello, world!')
  94 })
  95
  96 function isFresh (req, res) {
  97   return fresh(req.headers, {
  98     'etag': res.getHeader('ETag'),
  99     'last-modified': res.getHeader('Last-Modified')
 100   })
 101 }
 102
 103 server.listen(3000)
 104 ```
 105
 106 ## License
 107
 108 [MIT](LICENSE)
 109
 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