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