vnfmarket/src/main/webapp/vnfmarket/node_modules/compression/README.md

   1 # compression
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Build Status][travis-image]][travis-url]
   6 [![Test Coverage][coveralls-image]][coveralls-url]
   7 [![Gratipay][gratipay-image]][gratipay-url]
   8
   9 Node.js compression middleware.
  10
  11 The following compression codings are supported:
  12
  13   - deflate
  14   - gzip
  15
  16 ## Install
  17
  18 ```bash
  19 $ npm install compression
  20 ```
  21
  22 ## API
  23
  24 ```js
  25 var compression = require('compression')
  26 ```
  27
  28 ### compression([options])
  29
  30 Returns the compression middleware using the given `options`.
  31
  32 #### Options
  33
  34 `compression()` accepts these properties in the options object. In addition to
  35 those listed below, [zlib](http://nodejs.org/api/zlib.html) options may be
  36 passed in to the options object.
  37
  38 ##### chunkSize
  39
  40 The default value is `zlib.Z_DEFAULT_CHUNK`, or `16384`.
  41
  42 See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
  43 regarding the usage.
  44
  45 ##### filter
  46
  47 A function to decide if the response should be considered for compression.
  48 This function is called as `filter(req, res)` and is expected to return
  49 `true` to consider the response for compression, or `false` to not compress
  50 the response.
  51
  52 The default filter function uses the [compressible](https://www.npmjs.com/package/compressible)
  53 module to determine if `res.getHeader('Content-Type')` is compressible.
  54
  55 ##### level
  56
  57 The level of zlib compression to apply to responses. A higher level will result
  58 in better compression, but will take longer to complete. A lower level will
  59 result in less compression, but will be much faster.
  60
  61 This is an integer in the range of `0` (no compression) to `9` (maximum
  62 compression). The special value `-1` can be used to mean the "default
  63 compression level", which is a default compromise between speed and
  64 compression (currently equivalent to level 6).
  65
  66   - `-1` Default compression level (also `zlib.Z_DEFAULT_COMPRESSION`).
  67   - `0` No compression (also `zlib.Z_NO_COMPRESSION`).
  68   - `1` Fastest compression (also `zlib.Z_BEST_SPEED`).
  69   - `2`
  70   - `3`
  71   - `4`
  72   - `5`
  73   - `6` (currently what `zlib.Z_DEFAULT_COMPRESSION` points to).
  74   - `7`
  75   - `8`
  76   - `9` Best compression (also `zlib.Z_BEST_COMPRESSION`).
  77
  78 The default value is `zlib.Z_DEFAULT_COMPRESSION`, or `-1`.
  79
  80 **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
  81
  82 ##### memLevel
  83
  84 This specifies how much memory should be allocated for the internal compression
  85 state and is an integer in the range of `1` (minimum level) and `9` (maximum
  86 level).
  87
  88 The default value is `zlib.Z_DEFAULT_MEMLEVEL`, or `8`.
  89
  90 See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
  91 regarding the usage.
  92
  93 ##### strategy
  94
  95 This is used to tune the compression algorithm. This value only affects the
  96 compression ratio, not the correctness of the compressed output, even if it
  97 is not set appropriately.
  98
  99   - `zlib.Z_DEFAULT_STRATEGY` Use for normal data.
 100   - `zlib.Z_FILTERED` Use for data produced by a filter (or predictor).
 101     Filtered data consists mostly of small values with a somewhat random
 102     distribution. In this case, the compression algorithm is tuned to
 103     compress them better. The effect is to force more Huffman coding and less
 104     string matching; it is somewhat intermediate between `zlib.Z_DEFAULT_STRATEGY`
 105     and `zlib.Z_HUFFMAN_ONLY`.
 106   - `zlib.Z_FIXED` Use to prevent the use of dynamic Huffman codes, allowing
 107     for a simpler decoder for special applications.
 108   - `zlib.Z_HUFFMAN_ONLY` Use to force Huffman encoding only (no string match).
 109   - `zlib.Z_RLE` Use to limit match distances to one (run-length encoding).
 110     This is designed to be almost as fast as `zlib.Z_HUFFMAN_ONLY`, but give
 111     better compression for PNG image data.
 112
 113 **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
 114
 115 ##### threshold
 116
 117 The byte threshold for the response body size before compression is considered
 118 for the response, defaults to `1kb`. This is a number of bytes, any string
 119 accepted by the [bytes](https://www.npmjs.com/package/bytes) module, or `false`.
 120
 121 **Note** this is only an advisory setting; if the response size cannot be determined
 122 at the time the response headers are written, then it is assumed the response is
 123 _over_ the threshold. To guarantee the response size can be determined, be sure
 124 set a `Content-Length` response header.
 125
 126 ##### windowBits
 127
 128 The default value is `zlib.Z_DEFAULT_WINDOWBITS`, or `15`.
 129
 130 See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
 131 regarding the usage.
 132
 133 #### .filter
 134
 135 The default `filter` function. This is used to construct a custom filter
 136 function that is an extension of the default function.
 137
 138 ```js
 139 app.use(compression({filter: shouldCompress}))
 140
 141 function shouldCompress(req, res) {
 142   if (req.headers['x-no-compression']) {
 143     // don't compress responses with this request header
 144     return false
 145   }
 146
 147   // fallback to standard filter function
 148   return compression.filter(req, res)
 149 }
 150 ```
 151
 152 ### res.flush
 153
 154 This module adds a `res.flush()` method to force the partially-compressed
 155 response to be flushed to the client.
 156
 157 ## Examples
 158
 159 ### express/connect
 160
 161 When using this module with express or connect, simply `app.use` the module as
 162 high as you like. Requests that pass through the middleware will be compressed.
 163
 164 ```js
 165 var compression = require('compression')
 166 var express = require('express')
 167
 168 var app = express()
 169
 170 // compress all requests
 171 app.use(compression())
 172
 173 // add all routes
 174 ```
 175
 176 ### Server-Sent Events
 177
 178 Because of the nature of compression this module does not work out of the box
 179 with server-sent events. To compress content, a window of the output needs to
 180 be buffered up in order to get good compression. Typically when using server-sent
 181 events, there are certain block of data that need to reach the client.
 182
 183 You can achieve this by calling `res.flush()` when you need the data written to
 184 actually make it to the client.
 185
 186 ```js
 187 var compression = require('compression')
 188 var express     = require('express')
 189
 190 var app = express()
 191
 192 // compress responses
 193 app.use(compression())
 194
 195 // server-sent event stream
 196 app.get('/events', function (req, res) {
 197   res.setHeader('Content-Type', 'text/event-stream')
 198   res.setHeader('Cache-Control', 'no-cache')
 199
 200   // send a ping approx every 2 seconds
 201   var timer = setInterval(function () {
 202     res.write('data: ping\n\n')
 203
 204     // !!! this is the important part
 205     res.flush()
 206   }, 2000)
 207
 208   res.on('close', function () {
 209     clearInterval(timer)
 210   })
 211 })
 212 ```
 213
 214 ## License
 215
 216 [MIT](LICENSE)
 217
 218 [npm-image]: https://img.shields.io/npm/v/compression.svg
 219 [npm-url]: https://npmjs.org/package/compression
 220 [travis-image]: https://img.shields.io/travis/expressjs/compression/master.svg
 221 [travis-url]: https://travis-ci.org/expressjs/compression
 222 [coveralls-image]: https://img.shields.io/coveralls/expressjs/compression/master.svg
 223 [coveralls-url]: https://coveralls.io/r/expressjs/compression?branch=master
 224 [downloads-image]: https://img.shields.io/npm/dm/compression.svg
 225 [downloads-url]: https://npmjs.org/package/compression
 226 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 227 [gratipay-url]: https://www.gratipay.com/dougwilson/