source: trip-planner-front/node_modules/compression/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

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