| 1 | # etag
|
|---|
| 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 | Create simple HTTP ETags
|
|---|
| 10 |
|
|---|
| 11 | This module generates HTTP ETags (as defined in RFC 7232) for use in
|
|---|
| 12 | HTTP responses.
|
|---|
| 13 |
|
|---|
| 14 | ## Installation
|
|---|
| 15 |
|
|---|
| 16 | This is a [Node.js](https://nodejs.org/en/) module available through the
|
|---|
| 17 | [npm registry](https://www.npmjs.com/). Installation is done using the
|
|---|
| 18 | [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
|---|
| 19 |
|
|---|
| 20 | ```sh
|
|---|
| 21 | $ npm install etag
|
|---|
| 22 | ```
|
|---|
| 23 |
|
|---|
| 24 | ## API
|
|---|
| 25 |
|
|---|
| 26 | <!-- eslint-disable no-unused-vars -->
|
|---|
| 27 |
|
|---|
| 28 | ```js
|
|---|
| 29 | var etag = require('etag')
|
|---|
| 30 | ```
|
|---|
| 31 |
|
|---|
| 32 | ### etag(entity, [options])
|
|---|
| 33 |
|
|---|
| 34 | Generate a strong ETag for the given entity. This should be the complete
|
|---|
| 35 | body of the entity. Strings, `Buffer`s, and `fs.Stats` are accepted. By
|
|---|
| 36 | default, a strong ETag is generated except for `fs.Stats`, which will
|
|---|
| 37 | generate a weak ETag (this can be overwritten by `options.weak`).
|
|---|
| 38 |
|
|---|
| 39 | <!-- eslint-disable no-undef -->
|
|---|
| 40 |
|
|---|
| 41 | ```js
|
|---|
| 42 | res.setHeader('ETag', etag(body))
|
|---|
| 43 | ```
|
|---|
| 44 |
|
|---|
| 45 | #### Options
|
|---|
| 46 |
|
|---|
| 47 | `etag` accepts these properties in the options object.
|
|---|
| 48 |
|
|---|
| 49 | ##### weak
|
|---|
| 50 |
|
|---|
| 51 | Specifies if the generated ETag will include the weak validator mark (that
|
|---|
| 52 | is, the leading `W/`). The actual entity tag is the same. The default value
|
|---|
| 53 | is `false`, unless the `entity` is `fs.Stats`, in which case it is `true`.
|
|---|
| 54 |
|
|---|
| 55 | ## Testing
|
|---|
| 56 |
|
|---|
| 57 | ```sh
|
|---|
| 58 | $ npm test
|
|---|
| 59 | ```
|
|---|
| 60 |
|
|---|
| 61 | ## Benchmark
|
|---|
| 62 |
|
|---|
| 63 | ```bash
|
|---|
| 64 | $ npm run-script bench
|
|---|
| 65 |
|
|---|
| 66 | > etag@1.8.1 bench nodejs-etag
|
|---|
| 67 | > node benchmark/index.js
|
|---|
| 68 |
|
|---|
| 69 | http_parser@2.7.0
|
|---|
| 70 | node@6.11.1
|
|---|
| 71 | v8@5.1.281.103
|
|---|
| 72 | uv@1.11.0
|
|---|
| 73 | zlib@1.2.11
|
|---|
| 74 | ares@1.10.1-DEV
|
|---|
| 75 | icu@58.2
|
|---|
| 76 | modules@48
|
|---|
| 77 | openssl@1.0.2k
|
|---|
| 78 |
|
|---|
| 79 | > node benchmark/body0-100b.js
|
|---|
| 80 |
|
|---|
| 81 | 100B body
|
|---|
| 82 |
|
|---|
| 83 | 4 tests completed.
|
|---|
| 84 |
|
|---|
| 85 | buffer - strong x 258,647 ops/sec ±1.07% (180 runs sampled)
|
|---|
| 86 | buffer - weak x 263,812 ops/sec ±0.61% (184 runs sampled)
|
|---|
| 87 | string - strong x 259,955 ops/sec ±1.19% (185 runs sampled)
|
|---|
| 88 | string - weak x 264,356 ops/sec ±1.09% (184 runs sampled)
|
|---|
| 89 |
|
|---|
| 90 | > node benchmark/body1-1kb.js
|
|---|
| 91 |
|
|---|
| 92 | 1KB body
|
|---|
| 93 |
|
|---|
| 94 | 4 tests completed.
|
|---|
| 95 |
|
|---|
| 96 | buffer - strong x 189,018 ops/sec ±1.12% (182 runs sampled)
|
|---|
| 97 | buffer - weak x 190,586 ops/sec ±0.81% (186 runs sampled)
|
|---|
| 98 | string - strong x 144,272 ops/sec ±0.96% (188 runs sampled)
|
|---|
| 99 | string - weak x 145,380 ops/sec ±1.43% (187 runs sampled)
|
|---|
| 100 |
|
|---|
| 101 | > node benchmark/body2-5kb.js
|
|---|
| 102 |
|
|---|
| 103 | 5KB body
|
|---|
| 104 |
|
|---|
| 105 | 4 tests completed.
|
|---|
| 106 |
|
|---|
| 107 | buffer - strong x 92,435 ops/sec ±0.42% (188 runs sampled)
|
|---|
| 108 | buffer - weak x 92,373 ops/sec ±0.58% (189 runs sampled)
|
|---|
| 109 | string - strong x 48,850 ops/sec ±0.56% (186 runs sampled)
|
|---|
| 110 | string - weak x 49,380 ops/sec ±0.56% (190 runs sampled)
|
|---|
| 111 |
|
|---|
| 112 | > node benchmark/body3-10kb.js
|
|---|
| 113 |
|
|---|
| 114 | 10KB body
|
|---|
| 115 |
|
|---|
| 116 | 4 tests completed.
|
|---|
| 117 |
|
|---|
| 118 | buffer - strong x 55,989 ops/sec ±0.93% (188 runs sampled)
|
|---|
| 119 | buffer - weak x 56,148 ops/sec ±0.55% (190 runs sampled)
|
|---|
| 120 | string - strong x 27,345 ops/sec ±0.43% (188 runs sampled)
|
|---|
| 121 | string - weak x 27,496 ops/sec ±0.45% (190 runs sampled)
|
|---|
| 122 |
|
|---|
| 123 | > node benchmark/body4-100kb.js
|
|---|
| 124 |
|
|---|
| 125 | 100KB body
|
|---|
| 126 |
|
|---|
| 127 | 4 tests completed.
|
|---|
| 128 |
|
|---|
| 129 | buffer - strong x 7,083 ops/sec ±0.22% (190 runs sampled)
|
|---|
| 130 | buffer - weak x 7,115 ops/sec ±0.26% (191 runs sampled)
|
|---|
| 131 | string - strong x 3,068 ops/sec ±0.34% (190 runs sampled)
|
|---|
| 132 | string - weak x 3,096 ops/sec ±0.35% (190 runs sampled)
|
|---|
| 133 |
|
|---|
| 134 | > node benchmark/stats.js
|
|---|
| 135 |
|
|---|
| 136 | stat
|
|---|
| 137 |
|
|---|
| 138 | 4 tests completed.
|
|---|
| 139 |
|
|---|
| 140 | real - strong x 871,642 ops/sec ±0.34% (189 runs sampled)
|
|---|
| 141 | real - weak x 867,613 ops/sec ±0.39% (190 runs sampled)
|
|---|
| 142 | fake - strong x 401,051 ops/sec ±0.40% (189 runs sampled)
|
|---|
| 143 | fake - weak x 400,100 ops/sec ±0.47% (188 runs sampled)
|
|---|
| 144 | ```
|
|---|
| 145 |
|
|---|
| 146 | ## License
|
|---|
| 147 |
|
|---|
| 148 | [MIT](LICENSE)
|
|---|
| 149 |
|
|---|
| 150 | [npm-image]: https://img.shields.io/npm/v/etag.svg
|
|---|
| 151 | [npm-url]: https://npmjs.org/package/etag
|
|---|
| 152 | [node-version-image]: https://img.shields.io/node/v/etag.svg
|
|---|
| 153 | [node-version-url]: https://nodejs.org/en/download/
|
|---|
| 154 | [travis-image]: https://img.shields.io/travis/jshttp/etag/master.svg
|
|---|
| 155 | [travis-url]: https://travis-ci.org/jshttp/etag
|
|---|
| 156 | [coveralls-image]: https://img.shields.io/coveralls/jshttp/etag/master.svg
|
|---|
| 157 | [coveralls-url]: https://coveralls.io/r/jshttp/etag?branch=master
|
|---|
| 158 | [downloads-image]: https://img.shields.io/npm/dm/etag.svg
|
|---|
| 159 | [downloads-url]: https://npmjs.org/package/etag
|
|---|
