koa-compress 5.1.0 → 5.2.0

package/HISTORY.md

@@ -1,3 +1,35 @@
+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'
 
 /**
@@ -6,17 +8,45 @@
 
 const compressible = require('compressible')
 const isJSON = require('koa-is-json')
-const status = require('statuses')
 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 Encodings = require('./encodings')
+const encodingDefaultPreference = ['zstd', 'br', 'gzip', 'deflate', 'identity']
+
+const preferredEncodings = encodingDefaultPreference.filter(
+  (encoding) => encodingMethods[encoding] || encoding === 'identity'
+)
+
+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*?(?:,|$)/
 
+/**
+ * empty body statues.
+ */
+const emptyBodyStatues = new Set([204, 205, 304])
+
 /**
  * Compress middleware.
  *
@@ -26,18 +56,31 @@ const NO_TRANSFORM_REGEX = /(?:^|,)\s*?no-transform\s*?(?:,|$)/
  */
 
 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,
@@ -51,32 +94,67 @@ module.exports = (options = {}) => {
 
     await next()
 
-    // early exit if there's no content body or the body is already encoded
     let { body } = ctx
-    if (!body) return
-    if (ctx.res.headersSent || !ctx.writable) return
-    if (ctx.compress === false) return
-    if (ctx.request.method === 'HEAD') return
-    if (status.empty[ctx.response.status]) return
-    if (ctx.response.get('Content-Encoding')) return
-
-    // forced compression or implied
-    if (!(ctx.compress === true || filter(ctx.response.type))) return
+    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.compress === false ||
+      ctx.request.method === 'HEAD' ||
+      emptyBodyStatues.has(+ctx.response.status) ||
+      ctx.response.get('Content-Encoding') ||
+      // forced compression or implied
+      !(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'))
+    ) {
+      return
+    }
 
-    // don't compress for Cache-Control: no-transform
-    // https://tools.ietf.org/html/rfc7234#section-5.2.1.6
-    const cacheControl = ctx.response.get('Cache-Control')
-    if (cacheControl && NO_TRANSFORM_REGEX.test(cacheControl)) 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 && ctx.response.length < threshold) return
+    if (threshold && size < threshold) return
 
     // get the preferred content encoding
-    const encodings = new Encodings({
-      preferredEncodings
+    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
     })
-    encodings.parseAcceptEncoding(ctx.request.headers['accept-encoding'] || defaultEncoding)
-    const encoding = encodings.getPreferredContentEncoding()
 
     // identity === no compression
     if (encoding === 'identity') return
@@ -89,13 +167,10 @@ 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) {
-      body.pipe(stream)
-    } else {
-      stream.end(body)
-    }
+    if (body instanceof Stream) return body.pipe(stream)
+    stream.end(body)
   }
 }

package/package.json

@@ -1,36 +1,54 @@
 {
   "name": "koa-compress",
   "description": "Compress middleware for koa",
-  "version": "5.1.0",
+  "version": "5.2.0",
+  "type": "commonjs",
   "author": {
     "name": "Jonathan Ong",
     "email": "me@jongleberry.com",
     "url": "http://jongleberry.com",
     "twitter": "https://twitter.com/jongleberry"
   },
+  "contributors": [
+    {
+      "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",
   "repository": "koajs/compress",
   "dependencies": {
-    "bytes": "^3.0.0",
-    "compressible": "^2.0.0",
-    "http-errors": "^1.8.0",
+    "bytes": "^3.1.2",
+    "compressible": "^2.0.18",
+    "http-errors": "^2.0.1",
     "koa-is-json": "^1.0.0",
-    "statuses": "^2.0.1"
+    "negotiator": "^1.0.0"
   },
   "devDependencies": {
-    "eslint": "^7.32.0",
-    "eslint-config-standard": "^16.0.3",
-    "eslint-plugin-import": "^2.24.0",
-    "eslint-plugin-node": "^11.0.0",
-    "eslint-plugin-promise": "^5.1.0",
-    "eslint-plugin-standard": "^5.0.0",
-    "jest": "^27.0.6",
-    "koa": "^2.13.1",
-    "supertest": "^6.1.6"
+    "@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",
@@ -38,10 +56,21 @@
     "HISTORY.md"
   ],
   "main": "lib",
-  "jest": {
-    "testEnvironment": "node"
-  },
+  "types": "lib/index.d.ts",
   "engines": {
-    "node": ">= 8.0.0"
+    "node": ">= 12"
+  },
+  "standard": {
+    "globals": [
+      "afterAll",
+      "beforeAll",
+      "afterEach",
+      "jasmine",
+      "describe",
+      "test",
+      "jest",
+      "expect",
+      "it"
+    ]
   }
 }

package/lib/encodings.js

@@ -1,102 +0,0 @@
-
-// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding
-const errors = require('http-errors')
-const zlib = require('zlib')
-
-module.exports = Encodings
-
-// TODO: convert this to a Class when we drop node@10 support
-// because node@10 does not support class fields.
-function Encodings (options = {}) {
-  this.wildcardAcceptEncoding = options.wildcardAcceptEncoding || Encodings.wildcardAcceptEncoding
-  this.preferredEncodings = options.preferredEncodings || Encodings.preferredEncodings
-  this.reDirective = options.reDirective || Encodings.reDirective
-
-  this.encodingWeights = new Map()
-}
-
-Encodings.encodingMethods = {
-  gzip: zlib.createGzip,
-  deflate: zlib.createDeflate,
-  br: zlib.createBrotliCompress
-}
-
-Encodings.encodingMethodDefaultOptions = {
-  gzip: {},
-  deflate: {},
-  br: {
-    [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*$/
-
-Encodings.prototype.parseAcceptEncoding = function (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)
-  })
-}
-
-Encodings.prototype.getPreferredContentEncoding = function () {
-  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'
-}