koa-compress 5.2.0 → 5.2.1

package/HISTORY.md

@@ -1,5 +1,15 @@
 SEE https://github.com/koajs/compress/releases
 
+5.2.1 / 2026-03-12
+==================
+
+* fixed TS typings and refactored them
+* minor bug fix
+* simplified code and removed unused code
+* improved docs and typo fixes
+* more tests
+* updated dependencies
+
 5.2.0 / 2026-02-10
 ==================
 

package/README.md

@@ -42,51 +42,49 @@ app.use(
 ### filter\<Function\>
 
 ```ts
-function (mimeType: string): Boolean {
-
-}
+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).
+A predicate that checks the response MIME type to decide whether to compress.
+Default: [compressible](https://github.com/jshttp/compressible).
 
 ### options.threshold\<String|Number|Function\>
 
-Minimum response size in bytes to compress or a function that returns such response (see below).
-Default `1024` bytes or `1kb`.
+Minimum response size in bytes to compress.
+Can also be a string parsed by `bytes()` (e.g. `"1kb"`) or a function (see [Functional properties](#functional-properties)).
+Default: `1024`.
 
 ### options[encoding]\<Object|Function\>
 
-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.
+Supported encodings in default preference order: `zstd`, `br`, `gzip`, `deflate`.
+Setting `options[encoding] = {}` passes those options to the corresponding `zlib` compressor.
+Setting `options[encoding] = false` disables that encoding.
 
-It can be a function that returns options (see below).
+Can also be a function (see [Functional properties](#functional-properties)).
 
 #### 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.
+[Brotli compression](https://en.wikipedia.org/wiki/Brotli) is available natively in all supported Node.js versions.
+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.
+[Zstandard compression](https://en.wikipedia.org/wiki/Zstandard) is natively supported starting from Node.js v22.15.0 (LTS) and v23.8.0 (Current). The middleware detects `zlib.createZstdCompress` at runtime; if available, zstd is enabled automatically, otherwise it is skipped.
 
 ### options.defaultEncoding\<String\>
 
-An optional string, which specifies what encoders to use for requests without
-[Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding).
-Default `identity`.
+Encoding assumed when the client sends no
+[Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header.
+Default: `"identity"` (no compression).
 
-The standard dictates to treat such requests as `*` meaning that all compressions are permissible,
-yet it causes very practical problems when debugging servers with manual tools like `curl`, `wget`, and so on.
-If you want to enable the standard behavior, just set `defaultEncoding` to `*`.
+The HTTP spec treats a missing header as `*` (any encoding is acceptable),
+but that causes problems when debugging with tools like `curl` or `wget`.
+Set `defaultEncoding` to `"*"` to restore spec-compliant behavior.
 
 ## Manually turning compression on and off
 
-You can always enable compression by setting `ctx.compress = true`.
-You can always disable compression by setting `ctx.compress = false`.
-This bypasses the filter check.
+You can force compression by setting `ctx.compress = true` (bypasses the filter check).
+You can disable compression by setting `ctx.compress = false`.
 
 ```js
 app.use((ctx, next) => {
@@ -95,32 +93,31 @@ app.use((ctx, next) => {
 });
 ```
 
-`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.
+`ctx.compress` can also be an options object (same shape as the middleware options).
+Its `threshold` and encoding properties override the global defaults for this response.
+Note: an options object does **not** bypass the filter check — only `true` does.
 
 ## Functional properties
 
-Certain properties (`threshold` and encoding options) can be specified as functions. Such functions will be called
+The `threshold` and per-encoding options can be functions. They are 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
+- `type` &mdash; same as `ctx.response.type`
+- `size` &mdash; same as `ctx.response.length`
+- `ctx` &mdash; the full Koa context object
 
-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.
+The function should return a valid value for that property.
+Returning another function of the same shape is allowed — it will be called in turn.
 
 Example:
 
 ```js
-app.use((ctx, next) => {
-  // ...
-  ctx.compress = (type, size, ctx) => ({
-    br: size && size >= 65536,
-    gzip: size && size < 65536,
-  });
-  ctx.body = payload;
-});
+app.use(
+  compress({
+    gzip: (type, size) => (size && size < 65536 ? { level: 9 } : false),
+    br: (type, size) => size && size >= 65536,
+  }),
+);
 ```
 
-Read all about `ctx` in https://koajs.com/#context and `ctx.response` in https://koajs.com/#response
+See the Koa documentation for [`ctx`](https://koajs.com/#context) and [`ctx.response`](https://koajs.com/#response).

package/lib/index.d.ts

@@ -1,136 +1,161 @@
 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;
+declare namespace compress {
   /**
-   * Default value for `Accept-Encoding` header, if it is not supplied by the client.
-   * Default: `"identity"`.
+   * Calculates a threshold value dynamically from the MIME type,
+   * the response size, and the current context.
    */
-  defaultEncoding?: string;
+  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;
+
   /**
-   * What `Accept-Encoding` value should be assumed if it is set to `"*"`. Default: `"gzip"`.
+   * Computes `deflate`/`gzip` compression options from the MIME type,
+   * the response size, and the current context.
    */
-  wildcardAcceptEncoding?: string;
+  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;
+
   /**
-   * 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']`.
+   * Computes `brotli` compression options from the MIME type,
+   * the response size, and the current context.
    */
-  encodingPreference?: string[];
+  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;
+
   /**
-   * 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: `{}`.
+   * Computes `zstd` compression options from the MIME type,
+   * the response size, and the current context.
    */
-  deflate?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+  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;
+
   /**
-   * 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: `{}`.
+   * Options for the `koa-compress` middleware.
    */
-  gzip?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+  type CompressOptions = {
+    /**
+     * Predicate that decides whether a given MIME type should be compressed.
+     * Default: `compressible()`.
+     * @param type - MIME type of the response
+     * @returns `true` to compress, `false` to skip
+     */
+    filter?: (type: string) => boolean;
+    /**
+     * Minimum response size to compress. A number (bytes), a string
+     * parsed by `bytes()` (e.g. `"1mb"`), or a {@link ThresholdFunction}.
+     * Default: `1024`.
+     */
+    threshold?: number | string | ThresholdFunction;
+    /**
+     * Encoding assumed when the client sends no `Accept-Encoding` header.
+     * Set to `"*"` for spec-compliant behavior. Default: `"identity"`.
+     */
+    defaultEncoding?: string;
+    /**
+     * Encoding to use when `Accept-Encoding` is `"*"`. Default: `"gzip"`.
+     */
+    wildcardAcceptEncoding?: string;
+    /**
+     * Preferred encoding order used to break ties among equally weighted
+     * encodings. Lower index = higher priority.
+     * Default: `['zstd', 'br', 'gzip', 'deflate', 'identity']`.
+     */
+    encodingPreference?: string[];
+    /**
+     * Options passed to `zlib.createDeflate()`, or `false`/`null` to disable.
+     * Can be a {@link ZlibOptionsFunction} for per-response values.
+     * Default: `{}`.
+     */
+    deflate?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+    /**
+     * Options passed to `zlib.createGzip()`, or `false`/`null` to disable.
+     * Can be a {@link ZlibOptionsFunction} for per-response values.
+     * Default: `{}`.
+     */
+    gzip?: boolean | null | ZlibOptions | ZlibOptionsFunction;
+    /**
+     * Options passed to `zlib.createBrotliCompress()`, or `false`/`null` to disable.
+     * Can be a {@link BrotliOptionsFunction} for per-response values.
+     * Default: `{params: {[zlib.constants.BROTLI_PARAM_QUALITY]: 4}}`.
+     */
+    br?: boolean | null | BrotliOptions | BrotliOptionsFunction;
+    /**
+     * Options passed to `zlib.createZstdCompress()`, or `false`/`null` to disable.
+     * Can be a {@link ZstdOptionsFunction} for per-response values.
+     * Default: `{}`.
+     */
+    zstd?: boolean | null | ZstdOptions | ZstdOptionsFunction;
+  };
+
   /**
-   * 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}`.
+   * Per-encoding options: built-in defaults merged with user-supplied values.
    */
-  br?: boolean | null | BrotliOptions | BrotliOptionsFunction;
+  type EncodingOptions = {
+    [encoding: string]: BrotliOptions | ZlibOptions | ZstdOptions | undefined;
+  };
+
   /**
-   * 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: `{}`.
+   * Koa middleware with additional properties for introspection.
    */
-  zstd?: boolean | null | ZstdOptions | ZstdOptionsFunction;
-};
+  interface CompressMiddleware extends Koa.Middleware {
+    /**
+     * Supported content encodings available in the current Node.js runtime,
+     * ordered by preference.
+     */
+    preferredEncodings: string[];
+    /**
+     * Resolved options for each supported encoding (built-in defaults
+     * merged with user-provided values).
+     */
+    encodingOptions: EncodingOptions;
+  }
+}
 
 /**
- * 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.
+ * Creates a Koa middleware that compresses response bodies via content
+ * negotiation. The returned function also exposes
+ * {@link compress.CompressMiddleware.preferredEncodings | preferredEncodings} and
+ * {@link compress.CompressMiddleware.encodingOptions | encodingOptions}.
+ *
+ * @param options - Compression options. See {@link compress.CompressOptions}.
+ * @returns Koa middleware with introspection properties.
  */
-declare function compress(options: CompressOptions = {}): Koa.Middleware;
+declare function compress(options?: compress.CompressOptions): compress.CompressMiddleware;
 
 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.
+     * Per-response compression override.
+     * Set to `false` to disable compression, `true` to force it
+     * (bypassing the filter), or a `CompressOptions` object whose
+     * properties override the defaults for this response.
      */
-    compress?: boolean | CompressOptions;
+    compress?: boolean | compress.CompressOptions;
   }
 }
 

package/lib/index.js

@@ -43,9 +43,9 @@ const encodingMethodDefaultOptions = {
 const NO_TRANSFORM_REGEX = /(?:^|,)\s*?no-transform\s*?(?:,|$)/
 
 /**
- * empty body statues.
+ * empty body statuses.
  */
-const emptyBodyStatues = new Set([204, 205, 304])
+const emptyBodyStatuses = new Set([204, 205, 304])
 
 /**
  * Compress middleware.
@@ -58,12 +58,10 @@ const emptyBodyStatues = new Set([204, 205, 304])
 module.exports = (options = {}) => {
   let {
     filter = compressible,
-    threshold = 1024,
     defaultEncoding,
     wildcardAcceptEncoding,
     encodingPreference = encodingDefaultPreference
   } = options
-  if (typeof threshold === 'string') threshold = bytes(threshold)
   if (!wildcardAcceptEncoding || wildcardAcceptEncoding === '*') {
     wildcardAcceptEncoding = 'gzip'
   }
@@ -103,7 +101,7 @@ module.exports = (options = {}) => {
       !ctx.writable ||
       ctx.compress === false ||
       ctx.request.method === 'HEAD' ||
-      emptyBodyStatues.has(+ctx.response.status) ||
+      emptyBodyStatuses.has(+ctx.response.status) ||
       ctx.response.get('Content-Encoding') ||
       // forced compression or implied
       !(ctx.compress === true || filter(type)) ||
@@ -168,7 +166,8 @@ module.exports = (options = {}) => {
     ctx.res.removeHeader('Content-Length')
 
     const compress = encodingMethods[encoding]
-    const stream = (ctx.body = compress(responseOptions[encoding]))
+    const compressOptions = { ...encodingMethodDefaultOptions[encoding], ...responseOptions[encoding] }
+    const stream = (ctx.body = compress(compressOptions))
 
     if (body instanceof Stream) return body.pipe(stream)
     stream.end(body)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koa-compress",
   "description": "Compress middleware for koa",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "type": "commonjs",
   "author": {
     "name": "Jonathan Ong",
@@ -32,10 +32,10 @@
   },
   "devDependencies": {
     "@types/koa": "^3.0.1",
-    "@types/node": "^25.2.2",
-    "c8": "^10.1.3",
-    "jest": "^30.2.0",
-    "koa": "^3.1.1",
+    "@types/node": "^25.5.0",
+    "c8": "^11.0.0",
+    "jest": "^30.3.0",
+    "koa": "^3.1.2",
     "snazzy": "^9.0.0",
     "standard": "^17.1.2",
     "supertest": "^7.2.2",