Skip to content

Commit

Permalink
fix(docs): improve readme (#209)
Browse files Browse the repository at this point in the history 
* docs: improve readme

* funding?

* some work

* remove some things
  • Loading branch information
@bjohansebas
bjohansebas authored Jan 10, 2025
1 parent d272132 commit 0cf7d3f
Showing 1 changed file with 89 additions and 31 deletions.
120 changes: 89 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]
[![Funding][funding-image]][funding-url]


Node.js compression middleware.

Expand Down Expand Up @@ -50,13 +52,16 @@ passed in to the options object or

##### chunkSize

The default value is `zlib.Z_DEFAULT_CHUNK`, or `16384`.
Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_CHUNK`, or `16384`.

See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
regarding the usage.

##### filter

Type: `Function`

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
Expand All @@ -67,6 +72,9 @@ module to determine if `res.getHeader('Content-Type')` is compressible.

##### level

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_COMPRESSION`, or `-1`

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.
Expand All @@ -76,64 +84,71 @@ 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`).
- `-1` Default compression level (also `zlib.constants.Z_DEFAULT_COMPRESSION`).
- `0` No compression (also `zlib.constants.Z_NO_COMPRESSION`).
- `1` Fastest compression (also `zlib.constants.Z_BEST_SPEED`).
- `2`
- `3`
- `4`
- `5`
- `6` (currently what `zlib.Z_DEFAULT_COMPRESSION` points to).
- `6` (currently what `zlib.constants.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`.
- `9` Best compression (also `zlib.constants.Z_BEST_COMPRESSION`).

**Note** in the list above, `zlib` is from `zlib = require('zlib')`.

##### memLevel

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_MEMLEVEL`, or `8`

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.

##### brotli

Type: `Object`

This specifies the options for configuring Brotli. See [Node.js documentation](https://nodejs.org/api/zlib.html#class-brotlioptions) for a complete list of available options.


##### strategy

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_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).
- `zlib.constants.Z_DEFAULT_STRATEGY` Use for normal data.
- `zlib.constants.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
string matching; it is somewhat intermediate between `zlib.constants.Z_DEFAULT_STRATEGY`
and `zlib.constants.Z_HUFFMAN_ONLY`.
- `zlib.constants.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
- `zlib.constants.Z_HUFFMAN_ONLY` Use to force Huffman encoding only (no string match).
- `zlib.constants.Z_RLE` Use to limit match distances to one (run-length encoding).
This is designed to be almost as fast as `zlib.constants.Z_HUFFMAN_ONLY`, but give
better compression for PNG image data.

**Note** in the list above, `zlib` is from `zlib = require('zlib')`.

##### threshold

Type: `Number` or `String`<br>
Default: `1kb`

The byte threshold for the response body size before compression is considered
for the response, defaults to `1kb`. This is a number of bytes or any string
for the response. This is a number of bytes or any string
accepted by the [bytes](https://www.npmjs.com/package/bytes) module.

**Note** this is only an advisory setting; if the response size cannot be determined
Expand All @@ -143,16 +158,18 @@ set a `Content-Length` response header.

##### windowBits

The default value is `zlib.Z_DEFAULT_WINDOWBITS`, or `15`.
Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_WINDOWBITS`, or `15`

See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
regarding the usage.

##### enforceEncoding

This is the default encoding to use when the client does not specify an encoding in the request's [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header.
Type: `String`<br>
Default: `identity`

The default value is `identity`.
This is the default encoding to use when the client does not specify an encoding in the request's [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header.

#### .filter

Expand All @@ -164,6 +181,7 @@ var compression = require('compression')
var express = require('express')

var app = express()

app.use(compression({ filter: shouldCompress }))

function shouldCompress (req, res) {
Expand All @@ -184,9 +202,9 @@ response to be flushed to the client.

## Examples

### express/connect
### express

When using this module with express or connect, simply `app.use` the module as
When using this module with express, simply `app.use` the module as
high as you like. Requests that pass through the middleware will be compressed.

```js
Expand All @@ -201,6 +219,36 @@ app.use(compression())
// add all routes
```

### Node.js HTTP server

```js
var compression = require('compression')({ threshold: 0 })
var http = require('http')

function createServer (fn) {
return http.createServer(function (req, res) {
compression(req, res, function (err) {
if (err) {
res.statusCode = err.status || 500
res.end(err.message)
return
}

fn(req, res)
})
})
}

var server = createServer(function (req, res) {
res.setHeader('Content-Type', 'text/plain')
res.end('hello world!')
})

server.listen(3000, () => {
console.log('> Listening at http://localhost:3000')
})
```

### Server-Sent Events

Because of the nature of compression this module does not work out of the box
Expand Down Expand Up @@ -239,15 +287,25 @@ app.get('/events', function (req, res) {
})
```

## Contributing

The Express.js project welcomes all constructive contributions. Contributions take many forms,
from code for bug fixes and enhancements, to additions and fixes to documentation, additional
tests, triaging incoming pull requests and issues, and more!

See the [Contributing Guide](https://github.com/expressjs/express/blob/master/Contributing.md) for more technical details on contributing.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/compression.svg
[npm-image]: https://badgen.net/npm/v/compression
[npm-url]: https://npmjs.org/package/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
[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/compression/master?label=ci
[downloads-image]: https://badgen.net/npm/dm/compression
[downloads-url]: https://npmcharts.com/compare/compression?minimal=true
[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/compression/master?label=CI
[github-actions-ci-url]: https://github.com/expressjs/compression/actions?query=workflow%3Aci
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/compression/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/compression
[funding-url]: https://opencollective.com/express
[funding-image]: https://badgen.net/badge/icon/sponsor/pink?icon=github&label=Open%20Collective

0 comments on commit 0cf7d3f

Please sign in to comment.