Biscuitcompress

Biscuitcompress is a lightweight, customizable Node.js middleware for handling HTTP response compression. It supports Brotli and Gzip compression, allowing you to compress response data based on the Accept-Encoding header in the request. It provides options for compression levels and thresholds, as well as MIME type filtering to determine which responses should be compressed.

Installation

To use Biscuitcompress in your Node.js project, you need to install it via npm or yarn.

npm install biscuitsjar-compress

or

yarn add biscuitsjar-compress

Usage

To use Biscuitcompress in your application, require it and add it as middleware to your server or routes.

Example:

const http = require('http');
const Biscuitcompress = require('biscuitcompress'); // Import the Biscuitcompress module

const server = http.createServer((req, res) => {
  const compressMiddleware = Biscuitcompress({
    threshold: 1024,  // Compression threshold in bytes (default is 1024)
    level: 9,         // Compression level (default is -1, which uses the default level)
    brotli: true,     // Enable Brotli compression (default is false)
    gzip: true,       // Enable Gzip compression (default is true)
    mimes: /text|javascript|\/json|xml/i // MIME types to apply compression (default is a regex for text, javascript, json, and xml)
  });

  compressMiddleware(req, res, () => {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify({ message: 'Hello, world!' }));
  });
});

server.listen(3000, () => {
  console.log('Server is running on port 3000');
});

In this example:

Brotli and Gzip compression are enabled.

Responses with Content-Type matching the provided MIME regex will be compressed.

Compression will only be applied if the response size exceeds the threshold of 1024 bytes.

Options

The Biscuitcompress function accepts the following options:

threshold (default: 1024)

The minimum size in bytes that a response must be in order to be compressed. If the response size is smaller than this threshold, compression will not be applied.

level (default: -1)

The compression level for Brotli and Gzip. A value from 0 (no compression) to 11 (maximum compression) can be set for Brotli. For Gzip, the level is between 1 (fastest) and 9 (best compression). If -1 is used, it defaults to default compression.

brotli (default: false)

Set this option to true or provide an object with custom Brotli options to enable Brotli compression.

gzip (default: true)

Set this option to false to disable Gzip compression.

mimes (default: /text|javascript|/json|xml/i)

A regular expression used to filter the MIME types that should be compressed. The default matches common text-based formats like JSON, JavaScript, and XML.

How It Works

1. Accept-Encoding Header:

The middleware checks the Accept-Encoding header in the incoming request to determine whether the client supports Brotli, Gzip, or neither.

2. Compression Decision:

The middleware decides whether to apply compression based on the response size and the MIME type. If the response is large enough (based on the threshold option) and the MIME type matches the mimes filter, compression will be applied.

3. Compression Stream:

The middleware creates a compression stream (either Brotli or Gzip) and pipes the response data through it. This is done asynchronously to avoid blocking the main event loop.

4. Error Handling:

Any compression stream errors will cause the response to be destroyed, returning an error to the client.

Customization

You can customize the compression behavior by passing in custom options to the middleware, such as:

Adjusting the compression level (default or custom).

Enabling/disabling Brotli and Gzip.

Defining a custom MIME filter for the types of responses to compress.

License

MIT License. See the LICENSE file for more details.