Functional and local options (#122)

* Refactor to use functional and local options.

Passes eslint. Passes the existing tests.

* Added tests for functional and local options.

* Added the super argument.

* Updated docs.

* Updated versions:

- Node to still supported: 20, 22, 24
  - See https://endoflife.date/nodejs
- Actions: to v4
- Syntax
  - Yes, it has changed.

* Codecov is deprecated.

* Updates of non-working dependencies:

- All harness/utilities copied from koajs/koa
- Removed unused dependencies.
- The rest is upgraded to the latest version.

* Removed unused file.

* Added standard exceptions to accommodate `jest`.

* Removed empty lines at the beginning flagged by `standard`.

Author: uhop

.eslintrc

@@ -2,9 +2,11 @@ name: Node.js CI
 
 on:
   push:
-    branch: master
+    branches:
+      - '*'
   pull_request:
-    branch: master
+    branches:
+      - master
 
 jobs:
   build:
@@ -13,15 +15,18 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x]
+        node-version: [20, 22, 24]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm ci
-    - run: npm run eslint
-    - run: npm run test -- --coverage
-    - run: npx codecov
+    - run: npm run lint
+    - run: npm run test:coverage
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/node.js.yml

@@ -45,17 +45,19 @@ function (mimeType: string): Boolean {
 An optional function that checks the response content type to decide whether to compress.
 By default, it uses [compressible](https://github.com/jshttp/compressible).
 
-### options.threshold\<String|Number\>
+### options.threshold\<String|Number|Function\>
 
-Minimum response size in bytes to compress.
+Minimum response size in bytes to compress or a function that returns such response (see below).
 Default `1024` bytes or `1kb`.
 
-### options[encoding]\<Object\>
+### options[encoding]\<Object|Function\>
 
 The current encodings are, in order of preference: `br`, `gzip`, `deflate`.
 Setting `options[encoding] = {}` will pass those options to the encoding function.
 Setting `options[encoding] = false` will disable that encoding.
 
+It can be a function that returns options (see below).
+
 #### options<span></span>.br
 
 [Brotli compression](https://en.wikipedia.org/wiki/Brotli) is supported in node v11.7.0+, which includes it natively.
@@ -83,3 +85,33 @@ app.use((ctx, next) => {
   ctx.body = fs.createReadStream(file)
 })
 ```
+
+`ctx.compress` can be an object similar to `options` above, whose properties (`threshold` and encoding options)
+override the global `options` for this response and bypass the filter check.
+
+## Functional properties
+
+Certain properties (`threshold` and encoding options) can be specified as functions. Such functions will be called
+for every response with three arguments:
+
+* `type` &mdash; the same as `ctx.response.type` (provided for convenience)
+* `size` &mdash; the same as `ctx.response.length` (provided for convenience)
+* `ctx` &mdash; the whole context object, if you want to do something unique
+
+It should return a valid value for that property. It is possible to return a function of the same shape,
+which will be used to calculate the actual property.
+
+Example:
+
+```js
+app.use((ctx, next) => {
+  // ...
+  ctx.compress = (type, size, ctx) => ({
+    br:   size && size >= 65536,
+    gzip: size && size <  65536
+  })
+  ctx.body = payload
+})
+```
+
+Read all about `ctx` in https://koajs.com/#context and `ctx.response` in https://koajs.com/#response

README.md

@@ -1,4 +1,3 @@
-
 const assert = require('assert')
 const zlib = require('zlib')
 

__tests__/.eslintrc

@@ -1,4 +1,3 @@
-
 const assert = require('assert')
 
 const Encodings = require('../lib/encodings')

__tests__/defaults.js

@@ -387,4 +387,124 @@ describe('Compress', () => {
     assert.strictEqual(res.headers.vary, 'Accept-Encoding')
     assert.strictEqual(res.headers['content-encoding'], 'gzip')
   })
+
+  it('functional threshold: should not compress', (done) => {
+    const app = new Koa()
+
+    app.use(compress({
+      threshold: () => '1mb'
+    }))
+    app.use(sendString)
+    server = app.listen()
+
+    request(server)
+      .get('/')
+      .expect(200)
+      .end((err, res) => {
+        if (err) { return done(err) }
+
+        assert.equal(res.headers['content-length'], '2048')
+        assert.equal(res.headers.vary, 'Accept-Encoding')
+        assert(!res.headers['content-encoding'])
+        assert(!res.headers['transfer-encoding'])
+        assert.equal(res.text, string)
+
+        done()
+      })
+  })
+
+  it('functional compressors: should not compress', (done) => {
+    const app = new Koa()
+
+    app.use(compress({ br: false, gzip: (type, size) => /^text\//i.test(type) && size > 1000000 }))
+    app.use(sendBuffer)
+    server = app.listen()
+
+    request(server)
+      .get('/')
+      .set('Accept-Encoding', 'br, gzip')
+      .expect(200)
+      .end((err, res) => {
+        if (err) { return done(err) }
+
+        assert.equal(res.headers.vary, 'Accept-Encoding')
+        assert(!res.headers['content-encoding'])
+
+        done()
+      })
+  })
+
+  it('functional compressors: should compress with gzip', (done) => {
+    const app = new Koa()
+
+    app.use(compress({ br: false, gzip: false }))
+    app.use((ctx) => {
+      ctx.compress = { gzip: (type, size) => size < 1000000 }
+      ctx.body = string
+    })
+    server = app.listen()
+
+    request(server)
+      .get('/')
+      .set('Accept-Encoding', 'br, gzip')
+      .expect(200)
+      .end((err, res) => {
+        if (err) { return done(err) }
+
+        assert.equal(res.headers.vary, 'Accept-Encoding')
+        assert.equal(res.headers['content-encoding'], 'gzip')
+
+        done()
+      })
+  })
+
+  it('functional compressors: should NOT compress with gzip', (done) => {
+    const app = new Koa()
+
+    app.use(compress({ br: false, gzip: false }))
+    app.use((ctx) => {
+      ctx.compress = { gzip: (type, size) => size < 100 }
+      ctx.body = string
+    })
+    server = app.listen()
+
+    request(server)
+      .get('/')
+      .set('Accept-Encoding', 'br, gzip')
+      .expect(200)
+      .end((err, res) => {
+        if (err) { return done(err) }
+
+        assert.equal(res.headers.vary, 'Accept-Encoding')
+        assert(!res.headers['content-encoding'])
+
+        done()
+      })
+  })
+
+  it('functional compressors: should compress with br', (done) => {
+    if (!process.versions.brotli) return done()
+
+    const app = new Koa()
+
+    app.use(compress({ br: false, gzip: false }))
+    app.use((ctx) => {
+      ctx.compress = { gzip: () => false, br: () => true }
+      ctx.body = string
+    })
+    server = app.listen()
+
+    request(server)
+      .get('/')
+      .set('Accept-Encoding', 'br, gzip')
+      .expect(200)
+      .end((err, res) => {
+        if (err) { return done(err) }
+
+        assert.equal(res.headers.vary, 'Accept-Encoding')
+        assert.equal(res.headers['content-encoding'], 'br')
+
+        done()
+      })
+  })
 })

__tests__/encodings.js

@@ -1,4 +1,3 @@
-
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
 const errors = require('http-errors')
 const zlib = require('zlib')

__tests__/index.js

@@ -56,6 +56,7 @@ module.exports = (options = {}) => {
     await next()
 
     let { body } = ctx
+    const { type, length: size } = ctx.response
     if (
       // early exit if there's no content body or the body is already encoded
       !body ||
@@ -65,15 +66,30 @@ module.exports = (options = {}) => {
       emptyBodyStatues.has(+ctx.response.status) ||
       ctx.response.get('Content-Encoding') ||
       // forced compression or implied
-      !(ctx.compress === true || filter(ctx.response.type)) ||
+      !(ctx.compress === true || filter(type)) ||
       // don't compress for Cache-Control: no-transform
       // https://tools.ietf.org/html/rfc7234#section-5.2.1.6
-      NO_TRANSFORM_REGEX.test(ctx.response.get('Cache-Control')) ||
-      // don't compress if the current response is below the threshold
-      (threshold && ctx.response.length < threshold)
+      NO_TRANSFORM_REGEX.test(ctx.response.get('Cache-Control'))
     ) return
 
+    // calculate "local" compression options
+    const responseOptions = { ...options, ...ctx.compress }
+    let { threshold = 1024 } = responseOptions
+    while (typeof threshold === 'function') threshold = threshold(type, size, ctx)
+    if (typeof threshold === 'string') threshold = bytes(threshold)
+
+    // don't compress if the current response is below the threshold
+    if (threshold && size < threshold) return
+
     // get the preferred content encoding
+    Encodings.preferredEncodings.forEach((encoding) => {
+      // calculate compressor options, if any
+      if (!(encoding in responseOptions)) return
+      let compressor = responseOptions[encoding]
+      while (typeof compressor === 'function') compressor = compressor(type, size, ctx)
+      responseOptions[encoding] = compressor
+    })
+    const preferredEncodings = Encodings.preferredEncodings.filter((encoding) => responseOptions[encoding] !== false && responseOptions[encoding] !== null)
     const encodings = new Encodings({ preferredEncodings })
     encodings.parseAcceptEncoding(ctx.request.headers['accept-encoding'] || defaultEncoding)
     const encoding = encodings.getPreferredContentEncoding()
@@ -90,7 +106,7 @@ module.exports = (options = {}) => {
     ctx.res.removeHeader('Content-Length')
 
     const compress = Encodings.encodingMethods[encoding]
-    const stream = ctx.body = compress(encodingOptions[encoding])
+    const stream = ctx.body = compress(responseOptions[encoding])
 
     if (body instanceof Stream) return body.pipe(stream)
     stream.end(body)