# compression
  
  [![NPM Version][npm-image]][npm-url]
  [![NPM Downloads][downloads-image]][downloads-url]
  [![Build Status][travis-image]][travis-url]
  [![Test Coverage][coveralls-image]][coveralls-url]
  [![Gratipay][gratipay-image]][gratipay-url]
  
  Node.js compression middleware.
  
  The following compression codings are supported:
  
    - deflate
    - gzip
  
  ## Install
  
  ```bash
  $ npm install compression
  ```
  
  ## API
  
  ```js
  var compression = require('compression')
  ```
  
  ### compression([options])
  
  Returns the compression middleware using the given `options`. The middleware
  will attempt to compress response bodies for all request that traverse through
  the middleware, based on the given `options`.
  
  This middleware will never compress responses that include a `Cache-Control`
  header with the [`no-transform` directive](https://tools.ietf.org/html/rfc7234#section-5.2.2.4),
  as compressing will transform the body.
  
  #### Options
  
  `compression()` accepts these properties in the options object. In addition to
  those listed below, [zlib](http://nodejs.org/api/zlib.html) options may be
  passed in to the options object.
  
  ##### chunkSize
  
  The default value is `zlib.Z_DEFAULT_CHUNK`, or `16384`.
  
  See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
  regarding the usage.
  
  ##### filter
  
  A function to decide if the response should be considered for compression.
  This function is called as `filter(req, res)` and is expected to return
  `true` to consider the response for compression, or `false` to not compress
  the response.
  
  The default filter function uses the [compressible](https://www.npmjs.com/package/compressible)
  module to determine if `res.getHeader('Content-Type')` is compressible.
  
  ##### level
  
  The level of zlib compression to apply to responses. A higher level will result
  in better compression, but will take longer to complete. A lower level will
  result in less compression, but will be much faster.
  
  This is an integer in the range of `0` (no compression) to `9` (maximum
  compression). The special value `-1` can be used to mean the "default
  compression level", which is a default compromise between speed and
  compression (currently equivalent to level 6).
  
    - `-1` Default compression level (also `zlib.Z_DEFAULT_COMPRESSION`).
    - `0` No compression (also `zlib.Z_NO_COMPRESSION`).
    - `1` Fastest compression (also `zlib.Z_BEST_SPEED`).
    - `2`
    - `3`
    - `4`
    - `5`
    - `6` (currently what `zlib.Z_DEFAULT_COMPRESSION` points to).
    - `7`
    - `8`
    - `9` Best compression (also `zlib.Z_BEST_COMPRESSION`).
  
  The default value is `zlib.Z_DEFAULT_COMPRESSION`, or `-1`.
  
  **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
  
  ##### memLevel
  
  This specifies how much memory should be allocated for the internal compression
  state and is an integer in the range of `1` (minimum level) and `9` (maximum
  level).
  
  The default value is `zlib.Z_DEFAULT_MEMLEVEL`, or `8`.
  
  See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
  regarding the usage.
  
  ##### strategy
  
  This is used to tune the compression algorithm. This value only affects the
  compression ratio, not the correctness of the compressed output, even if it
  is not set appropriately.
  
    - `zlib.Z_DEFAULT_STRATEGY` Use for normal data.
    - `zlib.Z_FILTERED` Use for data produced by a filter (or predictor).
      Filtered data consists mostly of small values with a somewhat random
      distribution. In this case, the compression algorithm is tuned to
      compress them better. The effect is to force more Huffman coding and less
      string matching; it is somewhat intermediate between `zlib.Z_DEFAULT_STRATEGY`
      and `zlib.Z_HUFFMAN_ONLY`.
    - `zlib.Z_FIXED` Use to prevent the use of dynamic Huffman codes, allowing
      for a simpler decoder for special applications.
    - `zlib.Z_HUFFMAN_ONLY` Use to force Huffman encoding only (no string match).
    - `zlib.Z_RLE` Use to limit match distances to one (run-length encoding).
      This is designed to be almost as fast as `zlib.Z_HUFFMAN_ONLY`, but give
      better compression for PNG image data.
  
  **Note** in the list above, `zlib` is from `zlib = require('zlib')`.
  
  ##### threshold
  
  The byte threshold for the response body size before compression is considered
  for the response, defaults to `1kb`. This is a number of bytes, any string
  accepted by the [bytes](https://www.npmjs.com/package/bytes) module, or `false`.
  
  **Note** this is only an advisory setting; if the response size cannot be determined
  at the time the response headers are written, then it is assumed the response is
  _over_ the threshold. To guarantee the response size can be determined, be sure
  set a `Content-Length` response header.
  
  ##### windowBits
  
  The default value is `zlib.Z_DEFAULT_WINDOWBITS`, or `15`.
  
  See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
  regarding the usage.
  
  #### .filter
  
  The default `filter` function. This is used to construct a custom filter
  function that is an extension of the default function.
  
  ```js
  app.use(compression({filter: shouldCompress}))
  
  function shouldCompress(req, res) {
    if (req.headers['x-no-compression']) {
      // don't compress responses with this request header
      return false
    }
  
    // fallback to standard filter function
    return compression.filter(req, res)
  }
  ```
  
  ### res.flush
  
  This module adds a `res.flush()` method to force the partially-compressed
  response to be flushed to the client.
  
  ## Examples
  
  ### express/connect
  
  When using this module with express or connect, simply `app.use` the module as
  high as you like. Requests that pass through the middleware will be compressed.
  
  ```js
  var compression = require('compression')
  var express = require('express')
  
  var app = express()
  
  // compress all requests
  app.use(compression())
  
  // add all routes
  ```
  
  ### Server-Sent Events
  
  Because of the nature of compression this module does not work out of the box
  with server-sent events. To compress content, a window of the output needs to
  be buffered up in order to get good compression. Typically when using server-sent
  events, there are certain block of data that need to reach the client.
  
  You can achieve this by calling `res.flush()` when you need the data written to
  actually make it to the client.
  
  ```js
  var compression = require('compression')
  var express     = require('express')
  
  var app = express()
  
  // compress responses
  app.use(compression())
  
  // server-sent event stream
  app.get('/events', function (req, res) {
    res.setHeader('Content-Type', 'text/event-stream')
    res.setHeader('Cache-Control', 'no-cache')
  
    // send a ping approx every 2 seconds
    var timer = setInterval(function () {
      res.write('data: ping
  
  ')
  
      // !!! this is the important part
      res.flush()
    }, 2000)
  
    res.on('close', function () {
      clearInterval(timer)
    })
  })
  ```
  
  ## License
  
  [MIT](LICENSE)
  
  [npm-image]: https://img.shields.io/npm/v/compression.svg
  [npm-url]: https://npmjs.org/package/compression
  [travis-image]: https://img.shields.io/travis/expressjs/compression/master.svg
  [travis-url]: https://travis-ci.org/expressjs/compression
  [coveralls-image]: https://img.shields.io/coveralls/expressjs/compression/master.svg
  [coveralls-url]: https://coveralls.io/r/expressjs/compression?branch=master
  [downloads-image]: https://img.shields.io/npm/dm/compression.svg
  [downloads-url]: https://npmjs.org/package/compression
  [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
  [gratipay-url]: https://www.gratipay.com/dougwilson/