itty-compression

!Lint Status
!Test Status
!GitHub issues

A work-in-progress, proof-of-concept compression middleware to provide Response Compression for use
in itty-router projects.

Probably compatible with a variety of other routers.

Not recommended for production use.

Features

$3

itty-compression includes:

| Middleware | Algorithm(s) |
|-------------------------|----------------------------|
| brotliCompression | brotli (br) only |
| deflateCompression | deflate only |
| gzipCompression | gzip only |
| negotiatedCompression | brotli (br), gzip, deflate |

#### What is negotiatedCompression?

negotiatedCompression compares the client's Accept-Encoding header against the list of supported encodings (see
table) and uses the first algorithm both the client and itty-compression can agree on. The priority is as follows:

1. brotli (br)
2. gzip
3. deflate
4. no compression

If the client doesn't accept any supported algorithm, the middleware will add the Vary header with the
value Accept-Encoding (or append the value if the header already exists) to inform the client of this capability.

As with the other middlewares, the original request object is needed to read the client's Accept-Encoding header. If
the request is not provided, the Accept-Encoding header isn't set, or no mutually supported algorithm could be
determined, this middleware will function as a no-op instead, returning the input with only the Vary: Accept-Encoding
header added.

$3

itty-compression won't attempt to compress already compressed
Responses again, be it from other routing steps/middleware or from accidentally duplicating it in the route handling.

$3

While not in the same ballpark as itty-router itself, the middlewares are kept as small as possible, with further
optimisations always on the table.

Current sizes are:

| middleware | size |
|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| brotliCompression |  |
| deflateCompression |  |
| gzipCompression |  |
| negotiatedCompression |  |

$3

itty-compression is entirely written in TypeScript, so it comes with types automatically.

$3

- brotli (br)
- gzip
- deflate

$3

itty-compression will always set the Vary header to include Accept-Encoding, even if the response was not
compressed.

How to use

itty-compression directly depends on Node's zlib via importing node:zlib.

Install with npm install @major-tanya/itty-compression (or your favoured alternative to npm).

Once installed, pick your compression algorithm, or use the flexible negotiatedCompression middleware
(Your Choice of Algorithm).

$3

The freshly released v5 of itty-router includes some more batteries-included routers that allow for some more concise
syntax when using itty-compression. Example based on the
v5 AutoRouter documentation.

Example: negotiatedCompression (replace with your middleware of choice)

``typescript
import { negotiatedCompression } from 'itty-compression';
import { AutoRouter } from 'itty-router';

const router = AutoRouter({ // using batteries-included AutoRouter
finally: [negotiatedCompression],
});
// const router = Router({ // using the medium Router
// // do not forget to add the json handler for the medium Router before the compression middleware
// finally: [json, negotiatedCompression],
// });

// AutoRouter's integrated json formatter handles this automatically
router.get('/dogs/toto', (request) => ({
name: 'Toto',
breed: 'Cairn Terrier',
color: 'black',
}));

export default router;
`

$3

Example: negotiatedCompression (replace with your middleware of choice)

`typescript
import { negotiatedCompression } from 'itty-compression';
import { error, IttyRouter, json } from 'itty-router';

// const router = Router(); // only itty-router v4
const router = IttyRouter(); // only itty-router v5

// downstream json middleware handles stringifying
router.get('/dogs/toto', (request) => ({
name: 'Toto',
breed: 'Cairn Terrier',
color: 'black',
}));

export default {
fetch: (request, ...args) => router
// .handle(...args) // only itty-router v4
.fetch(...args) // only itty-router v5
.then(json) // <-- do not forget an appropriate handler here or you may encounter problems with itty-compression
.then((response) => negotiatedCompression(response, request)) // <-- add the compression handler downstream
.catch(error),
};
`

Note: It's important to add the original request in order for itty-compression to be able to respect the
client's Accept-Encoding header. If the request (or the header) is not provided, the compression middleware will
function as a no-op, returning the input with only the Vary header added.

Compatibility & Testing

Known compatible with

- itty-router v4 & v5 (see How to use)

Theoretically compatible with any framework/library/router that allows for access to the client request and the
in-progress response before it is sent to the client and also supports async middleware.

Goals

- Provide compression for itty-router` similar to the middleware provided
by compression for Express

TODO

- [ ] More library/framework compatibility data?
- [ ] Code golfing
- [ ] More robust approach to suboptimal inputs

Thanks

- kwhitley for the creation of the ittiest router I've ever seen.