Favicon added
[josuexyz/.git] / node_modules / fresh / 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