koa-compress 5.2.1 → 5.3.0

package/HISTORY.md

@@ -1,4 +1,19 @@
-SEE https://github.com/koajs/compress/releases
+5.3.0 / 2026-11-09
+==================
+
+* fixed `Blob` bodies, which were sent as `{}`, and compressed `Blob`, `ReadableStream`, and `Response` bodies, thx [yash](https://github.com/yxshee)
+* fixed a compressed stream body that fails partway: its error reaches Koa instead of leaving the response open
+* fixed a 500 when a client refuses every encoding, `identity` included: the response is sent uncompressed
+* added the `rejectUnacceptable` option to respond with `406 Not Acceptable` in that case instead
+* changed: `ReadableStream` and `Response` bodies without `Content-Length` are compressed regardless of `threshold`; set `ctx.compress = false` for live streams, such as server-sent events
+* breaking for strict TypeScript: the `size` argument of threshold and encoding functions is typed `number | undefined`
+* removed the unused `http-errors` dependency
+* updated docs and dependencies
+
+5.2.2 / 2026-06-15
+==================
+
+* skip compression for `206 Partial Content`, `Content-Range`, and `multipart/byteranges` responses, thx [naveentehrpariya](https://github.com/naveentehrpariya)
 
 5.2.1 / 2026-03-12
 ==================

package/README.md

@@ -81,6 +81,14 @@ 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.
 
+### options.rejectUnacceptable\<Boolean\>
+
+What to do when the client refuses every encoding the middleware can send, `identity` included (for example, `Accept-Encoding: identity;q=0`).
+By default, the response goes out uncompressed.
+Set `rejectUnacceptable` to `true` to respond with `406 Not Acceptable` instead.
+It applies only to responses that pass the filter and the threshold.
+Default: `false`.
+
 ## Manually turning compression on and off
 
 You can force compression by setting `ctx.compress = true` (bypasses the filter check).
@@ -94,16 +102,31 @@ app.use((ctx, next) => {
 ```
 
 `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.
+Its `threshold`, `rejectUnacceptable`, and encoding properties override the global defaults for this response.
 Note: an options object does **not** bypass the filter check — only `true` does.
 
+### Live streams
+
+The `threshold` applies to a stream only when you set `Content-Length`.
+Otherwise, Node.js streams, `ReadableStream` bodies, and `Response` bodies are compressed whenever the filter accepts their type.
+A compressor holds data until it has enough to compress, so a live stream, such as server-sent events, can reach the client late.
+To send a live stream as it's written, set `ctx.compress = false`:
+
+```js
+app.use((ctx, next) => {
+  ctx.compress = false;
+  ctx.type = "text/event-stream";
+  ctx.body = events; // a stream that writes each event as it happens
+});
+```
+
 ## Functional properties
 
 The `threshold` and per-encoding options can be functions. They are called
 for every response with three arguments:
 
 - `type` &mdash; same as `ctx.response.type`
-- `size` &mdash; same as `ctx.response.length`
+- `size` &mdash; the response size in bytes, or `undefined` for a stream without `Content-Length`
 - `ctx` &mdash; the full Koa context object
 
 The function should return a valid value for that property.

package/lib/index.d.ts

@@ -9,8 +9,8 @@ declare namespace compress {
   type ThresholdFunction = (
     /** MIME type of the response */
     type: string,
-    /** Size of the response in bytes */
-    size: number,
+    /** Size of the response in bytes, or `undefined` for a stream without `Content-Length` */
+    size: number | undefined,
     /** Context of the request */
     ctx: Koa.Context,
   ) => number | string | ThresholdFunction;
@@ -22,8 +22,8 @@ declare namespace compress {
   type ZlibOptionsFunction = (
     /** MIME type of the response */
     type: string,
-    /** Size of the response in bytes */
-    size: number,
+    /** Size of the response in bytes, or `undefined` for a stream without `Content-Length` */
+    size: number | undefined,
     /** Context of the request */
     ctx: Koa.Context,
   ) => boolean | null | ZlibOptions | ZlibOptionsFunction;
@@ -35,8 +35,8 @@ declare namespace compress {
   type BrotliOptionsFunction = (
     /** MIME type of the response */
     type: string,
-    /** Size of the response in bytes */
-    size: number,
+    /** Size of the response in bytes, or `undefined` for a stream without `Content-Length` */
+    size: number | undefined,
     /** Context of the request */
     ctx: Koa.Context,
   ) => boolean | null | BrotliOptions | BrotliOptionsFunction;
@@ -48,8 +48,8 @@ declare namespace compress {
   type ZstdOptionsFunction = (
     /** MIME type of the response */
     type: string,
-    /** Size of the response in bytes */
-    size: number,
+    /** Size of the response in bytes, or `undefined` for a stream without `Content-Length` */
+    size: number | undefined,
     /** Context of the request */
     ctx: Koa.Context,
   ) => boolean | null | ZstdOptions | ZstdOptionsFunction;
@@ -86,6 +86,13 @@ declare namespace compress {
      * Default: `['zstd', 'br', 'gzip', 'deflate', 'identity']`.
      */
     encodingPreference?: string[];
+    /**
+     * What to do when the client refuses every encoding the middleware can
+     * send, `identity` included (for example, `Accept-Encoding: identity;q=0`):
+     * `false` sends the response uncompressed, `true` responds with
+     * `406 Not Acceptable`. Default: `false`.
+     */
+    rejectUnacceptable?: boolean;
     /**
      * Options passed to `zlib.createDeflate()`, or `false`/`null` to disable.
      * Can be a {@link ZlibOptionsFunction} for per-response values.

package/lib/index.js

@@ -93,7 +93,11 @@ module.exports = (options = {}) => {
     await next()
 
     let { body } = ctx
-    const { type, length: size } = ctx.response
+    let { type, length: size } = ctx.response
+    // koa measures web streams as the JSON '{}', but their size is unknown
+    if (!ctx.response.has('Content-Length') && (body instanceof ReadableStream || body instanceof Response)) {
+      size = undefined
+    }
     if (
       // early exit if there's no content body or the body is already encoded
       !body ||
@@ -101,7 +105,11 @@ module.exports = (options = {}) => {
       !ctx.writable ||
       ctx.compress === false ||
       ctx.request.method === 'HEAD' ||
-      emptyBodyStatuses.has(+ctx.response.status) ||
+      emptyBodyStatuses.has(ctx.status) ||
+      // don't compress partial content: Content-Range describes unencoded byte offsets
+      ctx.status === 206 ||
+      ctx.response.get('Content-Range') ||
+      /^multipart\/byteranges\b/i.test(ctx.response.get('Content-Type') || '') ||
       ctx.response.get('Content-Encoding') ||
       // forced compression or implied
       !(ctx.compress === true || filter(type)) ||
@@ -149,16 +157,28 @@ module.exports = (options = {}) => {
     }
 
     const negotiator = new Negotiator(request)
-    // if no encodings are supported, negotiator returns 'identity'
+    // undefined when the client refuses identity along with everything we offer
     const encoding = negotiator.encoding(finalEncodings, {
       preferred: encodingPreference
     })
 
+    if (!encoding && responseOptions.rejectUnacceptable) {
+      // koa drops the headers we set when it renders an error
+      ctx.throw(406, `Please accept one of: ${finalEncodings.join(', ')}.`, {
+        headers: { Vary: 'Accept-Encoding' }
+      })
+    }
+
     // identity === no compression
-    if (encoding === 'identity') return
+    if (!encoding || encoding === 'identity') return
 
     /** begin compression logic **/
 
+    // web bodies supported by Koa 3: Blob, ReadableStream and Response
+    if (body instanceof Blob) body = body.stream()
+    else if (body instanceof Response) body = body.body ?? ''
+    if (body instanceof ReadableStream) body = Stream.Readable.from(body)
+
     // json
     if (isJSON(body)) body = ctx.body = JSON.stringify(body)
 
@@ -169,7 +189,8 @@ module.exports = (options = {}) => {
     const compressOptions = { ...encodingMethodDefaultOptions[encoding], ...responseOptions[encoding] }
     const stream = (ctx.body = compress(compressOptions))
 
-    if (body instanceof Stream) return body.pipe(stream)
-    stream.end(body)
+    // pipeline hands source errors to the compressor, which koa handles
+    if (body instanceof Stream) Stream.pipeline(body, stream, () => {})
+    else stream.end(body)
   }
 }

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "koa-compress",
-  "description": "Compress middleware for koa",
-  "version": "5.2.1",
+  "description": "Koa middleware that compresses HTTP responses with zstd, Brotli, gzip, or deflate",
+  "keywords": [
+    "koa",
+    "koajs",
+    "koa-middleware",
+    "middleware",
+    "compress",
+    "compression",
+    "gzip",
+    "deflate",
+    "brotli",
+    "zstd",
+    "zstandard",
+    "content-encoding",
+    "accept-encoding",
+    "http",
+    "response",
+    "stream"
+  ],
+  "version": "5.3.0",
   "type": "commonjs",
   "author": {
     "name": "Jonathan Ong",
@@ -22,24 +40,26 @@
     }
   ],
   "license": "MIT",
-  "repository": "koajs/compress",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koajs/compress.git"
+  },
   "dependencies": {
     "bytes": "^3.1.2",
     "compressible": "^2.0.18",
-    "http-errors": "^2.0.1",
     "koa-is-json": "^1.0.0",
-    "negotiator": "^1.0.0"
+    "negotiator": "^1.1.0"
   },
   "devDependencies": {
-    "@types/koa": "^3.0.1",
-    "@types/node": "^25.5.0",
-    "c8": "^11.0.0",
-    "jest": "^30.3.0",
-    "koa": "^3.1.2",
+    "@types/koa": "^3.0.3",
+    "@types/node": "^26.6.6",
+    "c8": "^9.1.0",
+    "jest": "^29.7.0",
+    "koa": "^3.3.0",
     "snazzy": "^9.0.0",
     "standard": "^17.1.2",
-    "supertest": "^7.2.2",
-    "typescript": "^5.9.3"
+    "supertest": "^7.3.2",
+    "typescript": "^7.0.2"
   },
   "scripts": {
     "test": "jest",
@@ -57,9 +77,6 @@
   ],
   "main": "lib",
   "types": "lib/index.d.ts",
-  "engines": {
-    "node": ">= 12"
-  },
   "standard": {
     "globals": [
       "afterAll",
@@ -72,5 +89,9 @@
       "expect",
       "it"
     ]
+  },
+  "homepage": "https://github.com/koajs/compress",
+  "bugs": {
+    "url": "https://github.com/koajs/compress/issues"
   }
 }