README.md (3374B)
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