koa-compress 5.1.1 → 5.2.0

package/HISTORY.md

@@ -1,5 +1,36 @@
 SEE https://github.com/koajs/compress/releases
 
+5.2.0 / 2026-02-10
+==================
+
+* add functional and local options
+* updated dependencies
+* copied the project setup from Koa
+* add zstd
+* use `negotiator` for content negotiation
+* add TypeScript typings and tests
+
+5.1.1 / 2023-04-08
+==================
+
+* minor refactoring + updated dependencies
+
+5.1.0 / 2021-08-17
+==================
+
+* change brotli defaults (compression level to 4)
+* updated dependencies
+
+5.0.1 / 2020-07-06
+==================
+
+* updated to accomodate Node changes: zlib constants were moved to a different namespace
+
+5.0.0 / 2020-07-05
+==================
+
+ * add `defaultEncoding`
+
 4.0.1 / 2020-04-29
 ==================
 

package/README.md

@@ -8,23 +8,28 @@ Compress middleware for Koa
 ## Example
 
 ```js
-const compress = require('koa-compress')
-const Koa = require('koa')
-
-const app = new Koa()
-app.use(compress({
-  filter (content_type) {
-  	return /text/i.test(content_type)
-  },
-  threshold: 2048,
-  gzip: {
-    flush: require('zlib').constants.Z_SYNC_FLUSH
-  },
-  deflate: {
-    flush: require('zlib').constants.Z_SYNC_FLUSH,
-  },
-  br: false // disable brotli
-}))
+const compress = require("koa-compress");
+const Koa = require("koa");
+
+const app = new Koa();
+app.use(
+  compress({
+    filter(content_type) {
+      return /text/i.test(content_type);
+    },
+    threshold: 2048,
+    gzip: {
+      flush: require("zlib").constants.Z_SYNC_FLUSH,
+    },
+    deflate: {
+      flush: require("zlib").constants.Z_SYNC_FLUSH,
+    },
+    zstd: {
+      flush: require("zlib").constants.Z_SYNC_FLUSH,
+    },
+    br: false, // disable brotli
+  }),
+);
 ```
 
 ## Maintainers
@@ -45,22 +50,28 @@ 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`.
+The current encodings are, in order of preference: `br`, `zstd`, `gzip`, `deflate`.
 Setting `options[encoding] = {}` will pass those options to the encoding function.
 Setting `options[encoding] = false` will disable that encoding.
 
-#### options<span></span>.br
+It can be a function that returns options (see below).
+
+#### options.br
 
 [Brotli compression](https://en.wikipedia.org/wiki/Brotli) is supported in node v11.7.0+, which includes it natively.
 As of v5.1.0, the default quality level is 4 for performance reasons.
 
+#### options.zstd
+
+[Zstandard compression](https://en.wikipedia.org/wiki/Zstandard) is natively supported in the Node.js API. Minimum supported version: `v22.15.0` (LTS); also available on the Current line starting from `v23.8.0+`. This middleware performs runtime feature detection for `zlib.createZstdCompress`; if present, Zstd is enabled, otherwise it is skipped—no version configuration required.
+
 ### options.defaultEncoding\<String\>
 
 An optional string, which specifies what encoders to use for requests without
@@ -79,7 +90,37 @@ This bypasses the filter check.
 
 ```js
 app.use((ctx, next) => {
-  ctx.compress = true
-  ctx.body = fs.createReadStream(file)
-})
+  ctx.compress = true;
+  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

package/lib/index.d.ts

@@ -0,0 +1,137 @@
+import type { BrotliOptions, ZlibOptions, ZstdOptions } from "node:zlib";
+import type Koa = require("koa");
+
+/**
+ * Function to calculate a threshold value dynamically from a MIME type,
+ * an existing size and the current context.
+ */
+export type ThresholdFunction = (
+  /** MIME type of the response */
+  type: string,
+  /** Size of the response in bytes */
+  size: number,
+  /** Context of the request */
+  ctx: Koa.Context,
+) => number | string | ThresholdFunction;
+
+/**
+ * Function to calculate compression parameters for `deflate` and `gzip` from a MIME type,
+ * an exisiting size and the current context.
+ */
+export type ZlibOptionsFunction = (
+  /** MIME type of the response */
+  type: string,
+  /** Size of the response in bytes */
+  size: number,
+  /** Context of the request */
+  ctx: Koa.Context,
+) => boolean | null | ZlibOptions | ZlibOptionsFunction;
+
+/**
+ * Function to calculate compression parameters for `brotli` from a MIME type,
+ * an exisiting size and the current context.
+ */
+export type BrotliOptionsFunction = (
+  /** MIME type of the response */
+  type: string,
+  /** Size of the response in bytes */
+  size: number,
+  /** Context of the request */
+  ctx: Koa.Context,
+) => boolean | null | BrotliOptions | BrotliOptionsFunction;
+
+/**
+ * Function to calculate compression parameters for `zstd` from a MIME type,
+ * an exisiting size and the current context.
+ */
+export type ZstdOptionsFunction = (
+  /** MIME type of the response */
+  type: string,
+  /** Size of the response in bytes */
+  size: number,
+  /** Context of the request */
+  ctx: Koa.Context,
+) => boolean | null | ZstdOptions | ZstdOptionsFunction;
+
+/**
+ * Compression options that govern how `koa/compress` handles responses.
+ */
+export type CompressOptions = {
+  /**
+   * Function to determine if compression should be applied.
+   * Default: `compressible()`.
+   * @param type MIME type of the response
+   * @returns `true` if compression should be applied, `false` otherwise
+   */
+  filter?: (type: string) => boolean;
+  /**
+   * Lower limit to apply compression to content. If it is a number, it is size in bytes,
+   * if it is a string, it is a human-readable size accepted by `bytes()`, e.g., `"1mb"`,
+   * or a `ThresholdFunction` that can calculate that value. Default: `1024`.
+   */
+  threshold?: number | string | ThresholdFunction;
+  /**
+   * Default value for `Accept-Encoding` header, if it is not supplied by the client.
+   * Default: `"identity"`.
+   */
+  defaultEncoding?: string;
+  /**
+   * What `Accept-Encoding` value should be assumed if it is set to `"*"`. Default: `"gzip"`.
+   */
+  wildcardAcceptEncoding?: string;
+  /**
+   * An array of compression types, which should be used when we have multiple choices
+   * with the same weight. An item with a lower index has higher priority.
+   * Default: `['zstd', 'br', 'gzip', 'deflate']`.
+   */
+  encodingPreference?: string[];
+  /**
+   * Options to use when compressing with `deflate()`.
+   * If it is `false` or `null` this compression should be disabled.
+   * It can be a function used to calculate such values.
+   * Default: `{}`.
+   */
+  deflate?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+  /**
+   * Options to use when compressing with `gzip()`.
+   * If it is `false` or `null` this compression should be disabled.
+   * It can be a function used to calculate such values.
+   * Default: `{}`.
+   */
+  gzip?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+  /**
+   * Options to use when compressing with `br()`.
+   * If it is `false` or `null` this compression should be disabled.
+   * It can be a function used to calculate such values.
+   * Default: `{[zlib.constants.BROTLI_PARAM_QUALITY]: 4}`.
+   */
+  br?: boolean | null | BrotliOptions | BrotliOptionsFunction;
+  /**
+   * Options to use when compressing with `zstd()`.
+   * If it is `false` or `null` this compression should be disabled.
+   * It can be a function used to calculate such values.
+   * Default: `{}`.
+   */
+  zstd?: boolean | null | ZstdOptions | ZstdOptionsFunction;
+};
+
+/**
+ * The main function that constructs a middleware for compressing responses.
+ * @param options sets the default way to handle compression.
+ * @returns a middleware function that compresses responses.
+ */
+declare function compress(options: CompressOptions = {}): Koa.Middleware;
+
+declare module "koa" {
+  interface DefaultContext {
+    /**
+     * Context property used to handle individual responses.
+     * If it is set to `false`, the compression is disabled.
+     * If it is an object, it is mixed with the default options overriding
+     * its properties for this request.
+     */
+    compress?: boolean | CompressOptions;
+  }
+}
+
+export = compress;

package/lib/index.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./index.d.ts"
+
 'use strict'
 
 /**
@@ -7,13 +9,37 @@
 const compressible = require('compressible')
 const isJSON = require('koa-is-json')
 const Stream = require('stream')
+const zlib = require('zlib')
 const bytes = require('bytes')
+const Negotiator = require('negotiator')
+
+const encodingMethods = {
+  zstd: zlib.createZstdCompress,
+  br: zlib.createBrotliCompress,
+  gzip: zlib.createGzip,
+  deflate: zlib.createDeflate
+}
+
+const encodingDefaultPreference = ['zstd', 'br', 'gzip', 'deflate', 'identity']
+
+const preferredEncodings = encodingDefaultPreference.filter(
+  (encoding) => encodingMethods[encoding] || encoding === 'identity'
+)
 
-const Encodings = require('./encodings')
+const encodingMethodDefaultOptions = {
+  gzip: {},
+  deflate: {},
+  br: {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: 4
+    }
+  },
+  zstd: {}
+}
 
 /**
-* Regex to match no-transform directive in a cache-control header
-*/
+ * Regex to match no-transform directive in a cache-control header
+ */
 const NO_TRANSFORM_REGEX = /(?:^|,)\s*?no-transform\s*?(?:,|$)/
 
 /**
@@ -30,18 +56,31 @@ const emptyBodyStatues = new Set([204, 205, 304])
  */
 
 module.exports = (options = {}) => {
-  let { filter = compressible, threshold = 1024, defaultEncoding = 'identity' } = options
+  let {
+    filter = compressible,
+    threshold = 1024,
+    defaultEncoding,
+    wildcardAcceptEncoding,
+    encodingPreference = encodingDefaultPreference
+  } = options
   if (typeof threshold === 'string') threshold = bytes(threshold)
+  if (!wildcardAcceptEncoding || wildcardAcceptEncoding === '*') {
+    wildcardAcceptEncoding = 'gzip'
+  }
+  defaultEncoding =
+    defaultEncoding === '*'
+      ? wildcardAcceptEncoding
+      : !defaultEncoding
+          ? 'identity'
+          : defaultEncoding
 
-  // `options.br = false` would remove it as a preferred encoding
-  const preferredEncodings = Encodings.preferredEncodings.filter((encoding) => options[encoding] !== false && options[encoding] !== null)
   const encodingOptions = {}
-  preferredEncodings.forEach((encoding) => {
+  for (const encoding of preferredEncodings) {
     encodingOptions[encoding] = {
-      ...Encodings.encodingMethodDefaultOptions[encoding],
-      ...(options[encoding] || {})
+      ...encodingMethodDefaultOptions[encoding],
+      ...options[encoding]
     }
-  })
+  }
 
   Object.assign(compressMiddleware, {
     preferredEncodings,
@@ -56,27 +95,66 @@ 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 ||
-      ctx.res.headersSent || !ctx.writable ||
+      ctx.res.headersSent ||
+      !ctx.writable ||
       ctx.compress === false ||
       ctx.request.method === 'HEAD' ||
       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)
-    ) return
+      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
-    const encodings = new Encodings({ preferredEncodings })
-    encodings.parseAcceptEncoding(ctx.request.headers['accept-encoding'] || defaultEncoding)
-    const encoding = encodings.getPreferredContentEncoding()
+    for (const encoding of compressMiddleware.preferredEncodings) {
+      // calculate compressor options, if any
+      if (!(encoding in responseOptions)) continue
+      let compressor = responseOptions[encoding]
+      while (typeof compressor === 'function') {
+        compressor = compressor(type, size, ctx)
+      }
+      responseOptions[encoding] = compressor
+    }
+
+    const finalEncodings = compressMiddleware.preferredEncodings.filter(
+      (encoding) =>
+        responseOptions[encoding] !== false &&
+        responseOptions[encoding] !== null
+    )
+
+    const acceptEncoding = ctx.request.headers['accept-encoding']
+    let request = ctx.request
+    if (acceptEncoding === '*') {
+      request = { headers: { 'accept-encoding': wildcardAcceptEncoding } }
+    } else if (!acceptEncoding) {
+      request = { headers: { 'accept-encoding': defaultEncoding } }
+    }
+
+    const negotiator = new Negotiator(request)
+    // if no encodings are supported, negotiator returns 'identity'
+    const encoding = negotiator.encoding(finalEncodings, {
+      preferred: encodingPreference
+    })
 
     // identity === no compression
     if (encoding === 'identity') return
@@ -89,8 +167,8 @@ module.exports = (options = {}) => {
     ctx.set('Content-Encoding', encoding)
     ctx.res.removeHeader('Content-Length')
 
-    const compress = Encodings.encodingMethods[encoding]
-    const stream = ctx.body = compress(encodingOptions[encoding])
+    const compress = encodingMethods[encoding]
+    const stream = (ctx.body = compress(responseOptions[encoding]))
 
     if (body instanceof Stream) return body.pipe(stream)
     stream.end(body)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "koa-compress",
   "description": "Compress middleware for koa",
-  "version": "5.1.1",
+  "version": "5.2.0",
+  "type": "commonjs",
   "author": {
     "name": "Jonathan Ong",
     "email": "me@jongleberry.com",
@@ -13,6 +14,11 @@
       "name": "Imed Jaberi",
       "email": "imed-jaberi@outlook.com",
       "url": "https://www.3imed-jaberi.com/"
+    },
+    {
+      "name": "Eugene Lazutkin",
+      "email": "eugene.lazutkin@gmail.com",
+      "url": "https://www.lazutkin.com/"
     }
   ],
   "license": "MIT",
@@ -20,23 +26,29 @@
   "dependencies": {
     "bytes": "^3.1.2",
     "compressible": "^2.0.18",
-    "http-errors": "^1.8.1",
-    "koa-is-json": "^1.0.0"
+    "http-errors": "^2.0.1",
+    "koa-is-json": "^1.0.0",
+    "negotiator": "^1.0.0"
   },
   "devDependencies": {
-    "eslint": "^7.32.0",
-    "eslint-config-standard": "^16.0.3",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^5.2.0",
-    "eslint-plugin-standard": "^5.0.0",
-    "jest": "^27.5.1",
-    "koa": "^2.13.4",
-    "supertest": "^6.2.4"
+    "@types/koa": "^3.0.1",
+    "@types/node": "^25.2.2",
+    "c8": "^10.1.3",
+    "jest": "^30.2.0",
+    "koa": "^3.1.1",
+    "snazzy": "^9.0.0",
+    "standard": "^17.1.2",
+    "supertest": "^7.2.2",
+    "typescript": "^5.9.3"
   },
   "scripts": {
-    "eslint": "eslint --ignore-path .gitignore .",
-    "test": "jest"
+    "test": "jest",
+    "test:coverage": "c8 --reporter=lcov --reporter=text-summary jest --coverage",
+    "lint": "standard",
+    "lint:fix": "standard --fix",
+    "lint:pretty": "standard | snazzy",
+    "ts-check": "tsc --noEmit",
+    "authors": "git log --format='%aN <%aE>' | sort -u > AUTHORS"
   },
   "files": [
     "lib",
@@ -44,7 +56,21 @@
     "HISTORY.md"
   ],
   "main": "lib",
+  "types": "lib/index.d.ts",
   "engines": {
     "node": ">= 12"
+  },
+  "standard": {
+    "globals": [
+      "afterAll",
+      "beforeAll",
+      "afterEach",
+      "jasmine",
+      "describe",
+      "test",
+      "jest",
+      "expect",
+      "it"
+    ]
   }
 }

package/lib/encodings.js

@@ -1,104 +0,0 @@
-
-// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
-const errors = require('http-errors')
-const zlib = require('zlib')
-
-class Encodings {
-  constructor (options = {}) {
-    this.wildcardAcceptEncoding = options.wildcardAcceptEncoding || Encodings.wildcardAcceptEncoding
-    this.preferredEncodings = options.preferredEncodings || Encodings.preferredEncodings
-    this.reDirective = options.reDirective || Encodings.reDirective
-
-    this.encodingWeights = new Map()
-  }
-
-  parseAcceptEncoding (acceptEncoding = '*') {
-    const { encodingWeights, reDirective } = this
-
-    acceptEncoding.split(',').forEach((directive) => {
-      const match = reDirective.exec(directive)
-      if (!match) return // not a supported encoding above
-
-      const encoding = match[1]
-
-      // weight must be in [0, 1]
-      let weight = match[2] && !isNaN(match[2]) ? parseFloat(match[2], 10) : 1
-      weight = Math.max(weight, 0)
-      weight = Math.min(weight, 1)
-
-      if (encoding === '*') {
-        // set the weights for the default encodings
-        this.wildcardAcceptEncoding.forEach((enc) => {
-          if (!encodingWeights.has(enc)) encodingWeights.set(enc, weight)
-        })
-        return
-      }
-
-      encodingWeights.set(encoding, weight)
-    })
-  }
-
-  getPreferredContentEncoding () {
-    const {
-      encodingWeights,
-      preferredEncodings
-    } = this
-
-    // get ordered list of accepted encodings
-    const acceptedEncodings = Array.from(encodingWeights.keys())
-      // sort by weight
-      .sort((a, b) => encodingWeights.get(b) - encodingWeights.get(a))
-      // filter by supported encodings
-      .filter((encoding) => encoding === 'identity' || typeof Encodings.encodingMethods[encoding] === 'function')
-
-    // group them by weights
-    const weightClasses = new Map()
-    acceptedEncodings.forEach((encoding) => {
-      const weight = encodingWeights.get(encoding)
-      if (!weightClasses.has(weight)) weightClasses.set(weight, new Set())
-      weightClasses.get(weight).add(encoding)
-    })
-
-    // search by weight, descending
-    const weights = Array.from(weightClasses.keys()).sort((a, b) => b - a)
-    for (let i = 0; i < weights.length; i++) {
-      // encodings at this weight
-      const encodings = weightClasses.get(weights[i])
-      // return the first encoding in the preferred list
-      for (let j = 0; j < preferredEncodings.length; j++) {
-        const preferredEncoding = preferredEncodings[j]
-        if (encodings.has(preferredEncoding)) return preferredEncoding
-      }
-    }
-
-    // no encoding matches, check to see if the client set identity, q=0
-    if (encodingWeights.get('identity') === 0) throw errors(406, 'Please accept br, gzip, deflate, or identity.')
-
-    // by default, return nothing
-    return 'identity'
-  }
-}
-
-Encodings.encodingMethods = {
-  gzip: zlib.createGzip,
-  deflate: zlib.createDeflate,
-  br: zlib.createBrotliCompress
-}
-
-Encodings.encodingMethodDefaultOptions = {
-  gzip: {},
-  deflate: {},
-  br: {
-    params: {
-      [zlib.constants.BROTLI_PARAM_QUALITY]: 4
-    }
-  }
-}
-
-// how we treat `Accept-Encoding: *`
-Encodings.wildcardAcceptEncoding = ['gzip', 'deflate']
-// our preferred encodings
-Encodings.preferredEncodings = ['br', 'gzip', 'deflate']
-Encodings.reDirective = /^\s*(gzip|compress|deflate|br|identity|\*)\s*(?:;\s*q\s*=\s*(\d(?:\.\d)?))?\s*$/
-
-module.exports = Encodings