node_modules/etag/README.md

   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