@fastify/compress 8.1.0 → 8.3.0

package/.github/workflows/ci.yml

@@ -14,6 +14,11 @@ on:
       - 'docs/**'
       - '*.md'
 
+# This allows a subsequently queued workflow run to interrupt previous runs
+concurrency:
+    group: "${{ github.workflow }}-${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+    cancel-in-progress: true
+
 permissions:
   contents: read
 

package/README.md

@@ -57,6 +57,23 @@ await fastify.register(
   { global: false }
 )
 ```
+
+If only compression or decompression is required, set the `globalCompression` or `globalDecompression` config flags to `false` respectively (both are `true` by default).
+
+```js
+await fastify.register(
+  import('@fastify/compress'),
+  // Disable compression but keep decompression enabled (default behavior for globalDecompression is true)
+  { globalCompression: false }
+)
+
+// Disable decompression but keep compression enabled
+await fastify.register(
+  import('@fastify/compress'),
+  { globalDecompression: false }
+)
+```
+
 Fastify encapsulation can be used to set global compression but run it only in a subset of routes by wrapping them inside a plugin.
 
 > ℹ️ Note: If using `@fastify/compress` plugin together with `@fastify/static` plugin, `@fastify/compress` must be registered (with *global hook*) **before** registering `@fastify/static`.
@@ -106,6 +123,40 @@ app.get('/', (req, reply) => {
 await app.listen({ port: 3000 })
 ```
 
+It's also possible to pass a Fetch API `Response` object or a Web `ReadableStream`. The plugin will automatically extract the body stream from the `Response` or convert the Web stream to a Node.js `Readable` behind the scenes.
+
+```js
+import fastify from 'fastify'
+
+const app = fastify()
+await app.register(import('@fastify/compress'), { global: true })
+
+app.get('/', async (req, reply) => {
+  const resp = new Response('Hello from Fetch Response')
+  reply.compress(resp)
+})
+```
+
+```js
+app.get('/', async (req, reply) => {
+  return new Response('Hello from Fetch Response')
+})
+```
+
+```js
+app.get('/', (req, reply) => {
+  const stream = new ReadableStream({
+    start (controller) {
+      controller.enqueue(new TextEncoder().encode('Hello from Web ReadableStream'))
+      controller.close()
+    }
+  })
+
+  reply.header('content-type', 'text/plain')
+  reply.compress(stream)
+})
+```
+
 ## Compress Options
 
 ### threshold
@@ -222,15 +273,24 @@ This plugin adds a `preParsing` hook to decompress the request payload based on
 
 Currently, the following encoding tokens are supported:
 
-1. `zstd` (Node.js 22.15+/23.8+)
-2. `br`
-3. `gzip`
-4. `deflate`
+- `zstd` (Node.js 22.15+/23.8+)
+- `br`
+- `gzip`
+- `deflate`
 
 If an unsupported encoding or invalid payload is received, the plugin throws an error.
 
 If the request header is missing, the plugin yields to the next hook.
 
+### Supported payload types
+
+The plugin supports compressing the following payload types:
+
+- Strings and Buffers
+- Node.js streams
+- Response objects (from the Fetch API)
+- ReadableStream objects (from the Web Streams API)
+
 ### Global hook
 
 The global request decompression hook is enabled by default. To disable it, pass `{ global: false }`:

package/index.js

@@ -12,7 +12,7 @@ const { Minipass } = require('minipass')
 const pumpify = require('pumpify')
 const { Readable } = require('readable-stream')
 
-const { isStream, isGzip, isDeflate, intoAsyncIterator } = require('./lib/utils')
+const { isStream, isGzip, isDeflate, intoAsyncIterator, isWebReadableStream, isFetchResponse, webStreamToNodeReadable } = require('./lib/utils')
 
 const InvalidRequestEncodingError = createError('FST_CP_ERR_INVALID_CONTENT_ENCODING', 'Unsupported Content-Encoding: %s', 415)
 const InvalidRequestCompressedPayloadError = createError('FST_CP_ERR_INVALID_CONTENT', 'Could not decompress the request payload using the provided encoding', 400)
@@ -124,7 +124,9 @@ function processCompressParams (opts) {
   }
 
   const params = {
-    global: (typeof opts.global === 'boolean') ? opts.global : true
+    global: (typeof opts.globalCompression === 'boolean')
+      ? opts.globalCompression
+      : (typeof opts.global === 'boolean') ? opts.global : true
   }
 
   params.removeContentLengthHeader = typeof opts.removeContentLengthHeader === 'boolean' ? opts.removeContentLengthHeader : true
@@ -184,7 +186,9 @@ function processDecompressParams (opts) {
   const customZlib = opts.zlib || zlib
 
   const params = {
-    global: (typeof opts.global === 'boolean') ? opts.global : true,
+    global: (typeof opts.globalDecompression === 'boolean')
+      ? opts.globalDecompression
+      : (typeof opts.global === 'boolean') ? opts.global : true,
     onUnsupportedRequestEncoding: opts.onUnsupportedRequestEncoding,
     onInvalidRequestPayload: opts.onInvalidRequestPayload,
     decompressStream: {
@@ -254,6 +258,7 @@ function buildRouteCompress (_fastify, params, routeOptions, decorateOnly) {
     if (payload == null) {
       return next()
     }
+
     const responseEncoding = reply.getHeader('Content-Encoding')
     if (responseEncoding && responseEncoding !== 'identity') {
       // response is already compressed
@@ -290,10 +295,18 @@ function buildRouteCompress (_fastify, params, routeOptions, decorateOnly) {
     }
 
     if (typeof payload.pipe !== 'function') {
-      if (Buffer.byteLength(payload) < params.threshold) {
-        return next()
+      if (isFetchResponse(payload)) {
+        payload = payload.body
+      }
+
+      if (isWebReadableStream(payload)) {
+        payload = webStreamToNodeReadable(payload)
+      } else {
+        if (Buffer.byteLength(payload) < params.threshold) {
+          return next()
+        }
+        payload = Readable.from(intoAsyncIterator(payload))
       }
-      payload = Readable.from(intoAsyncIterator(payload))
     }
 
     setVaryHeader(reply)
@@ -408,7 +421,13 @@ function compress (params) {
     }
 
     if (typeof payload.pipe !== 'function') {
-      if (!Buffer.isBuffer(payload) && typeof payload !== 'string') {
+      if (isFetchResponse(payload)) {
+        payload = payload.body
+      }
+
+      if (isWebReadableStream(payload)) {
+        payload = webStreamToNodeReadable(payload)
+      } else if (!Buffer.isBuffer(payload) && typeof payload !== 'string') {
         payload = this.serialize(payload)
       }
     }

package/lib/utils.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { Readable: NodeReadable } = require('node:stream')
+
 // https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1
 function isZstd (buffer) {
   return (
@@ -49,6 +51,18 @@ function isStream (stream) {
   return stream !== null && typeof stream === 'object' && typeof stream.pipe === 'function'
 }
 
+function isWebReadableStream (obj) {
+  return obj instanceof ReadableStream
+}
+
+function isFetchResponse (obj) {
+  return obj instanceof Response
+}
+
+function webStreamToNodeReadable (webStream) {
+  return NodeReadable.fromWeb(webStream)
+}
+
 /**
  * Provide a async iteratable for Readable.from
  */
@@ -90,4 +104,4 @@ async function * intoAsyncIterator (payload) {
   yield payload
 }
 
-module.exports = { isZstd, isGzip, isDeflate, isStream, intoAsyncIterator }
+module.exports = { isZstd, isGzip, isDeflate, isStream, intoAsyncIterator, isWebReadableStream, isFetchResponse, webStreamToNodeReadable }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/compress",
-  "version": "8.1.0",
+  "version": "8.3.0",
   "description": "Fastify compression utils",
   "main": "index.js",
   "type": "commonjs",
@@ -16,16 +16,15 @@
     "readable-stream": "^4.5.2"
   },
   "devDependencies": {
-    "@fastify/pre-commit": "^2.1.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.8",
     "adm-zip": "^0.5.12",
     "c8": "^10.1.2",
     "eslint": "^9.17.0",
     "fastify": "^5.0.0",
     "jsonstream": "^1.0.3",
     "neostandard": "^0.12.0",
-    "tsd": "^0.32.0",
-    "typescript": "~5.8.3"
+    "tsd": "^0.33.0",
+    "typescript": "~5.9.2"
   },
   "scripts": {
     "lint": "eslint",
@@ -84,7 +83,7 @@
     "url": "git+https://github.com/fastify/fastify-compress.git"
   },
   "tsd": {
-    "directory": "test/types"
+    "directory": "types"
   },
   "publishConfig": {
     "access": "public"

package/test/global-compress.test.js

@@ -9,6 +9,7 @@ const JSONStream = require('jsonstream')
 const Fastify = require('fastify')
 const compressPlugin = require('../index')
 const { once } = require('node:events')
+const { ReadableStream: WebReadableStream, Response } = globalThis
 
 describe('When `global` is not set, it is `true` by default :', async () => {
   test('it should compress Buffer data using brotli when `Accept-Encoding` request header is `br`', async (t) => {
@@ -265,6 +266,54 @@ describe('When `global` is not set, it is `true` by default :', async () => {
     const payload = zlib.gunzipSync(response.rawPayload)
     t.assert.equal(payload.toString('utf-8'), 'hello')
   })
+
+  test('it should compress a Fetch API Response body', async (t) => {
+    t.plan(1)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    const body = 'hello from fetch response'
+    fastify.get('/fetch-resp', (_request, reply) => {
+      const resp = new Response(body, { headers: { 'content-type': 'text/plain' } })
+      reply.send(resp)
+    })
+
+    const response = await fastify.inject({
+      url: '/fetch-resp',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    const payload = zlib.gunzipSync(response.rawPayload)
+    t.assert.equal(payload.toString('utf-8'), body)
+  })
+
+  test('it should compress a Web ReadableStream body', async (t) => {
+    t.plan(1)
+
+    const fastify = Fastify()
+    await fastify.register(compressPlugin, { threshold: 0 })
+
+    const body = 'hello from web stream'
+    fastify.get('/web-stream', (_request, reply) => {
+      const stream = new WebReadableStream({
+        start (controller) {
+          controller.enqueue(Buffer.from(body))
+          controller.close()
+        }
+      })
+      reply.header('content-type', 'text/plain')
+      reply.send(stream)
+    })
+
+    const response = await fastify.inject({
+      url: '/web-stream',
+      method: 'GET',
+      headers: { 'accept-encoding': 'gzip' }
+    })
+    const payload = zlib.gunzipSync(response.rawPayload)
+    t.assert.equal(payload.toString('utf-8'), body)
+  })
 })
 
 describe('It should send compressed Stream data when `global` is `true` :', async () => {
@@ -3350,3 +3399,152 @@ for (const contentType of notByDefaultSupportedContentTypes) {
     t.assert.equal(response.rawPayload.toString('utf-8'), file)
   })
 }
+
+test('It should support separate globalCompression and globalDecompression settings', async (t) => {
+  t.plan(3)
+
+  // Test case: disable compression but enable decompression globally
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, {
+    globalCompression: false,
+    globalDecompression: true
+  })
+
+  const testData = { message: 'test data for decompression only' }
+
+  fastify.get('/', (request, reply) => {
+    reply.send(testData)
+  })
+
+  // Test that compression is disabled
+  const getResponse = await fastify.inject({
+    url: '/',
+    method: 'GET',
+    headers: {
+      'accept-encoding': 'gzip, deflate, br'
+    }
+  })
+
+  t.assert.equal(getResponse.statusCode, 200)
+  // No compression should happen since globalCompression is false
+  t.assert.equal(getResponse.headers['content-encoding'], undefined)
+  t.assert.deepEqual(getResponse.json(), testData)
+})
+
+test('It should enable decompression when globalDecompression is true', async (t) => {
+  t.plan(2)
+
+  // Test case: enable decompression globally
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, {
+    globalCompression: false,
+    globalDecompression: true
+  })
+
+  // Create a compressed request payload to test decompression
+  const compressedPayload = zlib.gzipSync(JSON.stringify({ input: 'compressed data' }))
+
+  fastify.post('/', (request, reply) => {
+    // This should be decompressed automatically
+    reply.send({ received: request.body })
+  })
+
+  // Test that decompression is enabled
+  const postResponse = await fastify.inject({
+    url: '/',
+    method: 'POST',
+    headers: {
+      'content-encoding': 'gzip',
+      'content-type': 'application/json'
+    },
+    payload: compressedPayload
+  })
+
+  t.assert.equal(postResponse.statusCode, 200)
+  // Decompression should work since globalDecompression is true
+  t.assert.deepEqual(postResponse.json(), { received: { input: 'compressed data' } })
+})
+
+test('It should fall back to global option when specific options are not provided', async (t) => {
+  t.plan(2)
+
+  // Test that global: false affects both compression and decompression
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, {
+    global: false
+  })
+
+  const testData = { message: 'test data' }
+
+  fastify.get('/', (request, reply) => {
+    reply.send(testData)
+  })
+
+  const response = await fastify.inject({
+    url: '/',
+    method: 'GET',
+    headers: {
+      'accept-encoding': 'gzip, deflate, br'
+    }
+  })
+
+  t.assert.equal(response.statusCode, 200)
+  // No compression should happen since global is false
+  t.assert.equal(response.headers['content-encoding'], undefined)
+})
+
+test('It should demonstrate globalCompression overrides global setting', async (t) => {
+  t.plan(2)
+
+  // Test that globalCompression: true overrides global: false
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, {
+    global: false,
+    globalCompression: true,
+    threshold: 0
+  })
+
+  fastify.get('/', (request, reply) => {
+    reply.send({ message: 'globalCompression overrides global' })
+  })
+
+  const response = await fastify.inject({
+    url: '/',
+    method: 'GET',
+    headers: { 'accept-encoding': 'gzip' }
+  })
+
+  t.assert.equal(response.statusCode, 200)
+  t.assert.equal(response.headers['content-encoding'], 'gzip') // Compression enabled despite global: false
+})
+
+test('It should demonstrate globalDecompression controls decompression independently', async (t) => {
+  t.plan(2)
+
+  // Test globalDecompression: false disables decompression even with global: true
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, {
+    global: true,
+    globalDecompression: false
+  })
+
+  const compressedPayload = zlib.gzipSync(JSON.stringify({ test: 'decompression' }))
+
+  fastify.post('/', (request, reply) => {
+    reply.send({ received: request.body })
+  })
+
+  const response = await fastify.inject({
+    url: '/',
+    method: 'POST',
+    headers: {
+      'content-encoding': 'gzip',
+      'content-type': 'application/json'
+    },
+    payload: compressedPayload
+  })
+
+  // Should get 400 error since decompression is disabled and compressed data can't be parsed
+  t.assert.equal(response.statusCode, 400)
+  t.assert.ok(response.body.includes('Content-Length') || response.body.includes('Bad Request'))
+})

package/test/routes-compress.test.js

@@ -440,3 +440,33 @@ test('It should avoid to trigger `onSend` hook twice', async (t) => {
   })
   t.assert.deepEqual(JSON.parse(zlib.brotliDecompressSync(response.rawPayload)), { hi: true })
 })
+
+test('reply.compress should handle Fetch Response', async (t) => {
+  t.plan(1)
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, { global: true, threshold: 0 })
+  fastify.get('/', (_req, reply) => {
+    const r = new Response('from reply.compress', { headers: { 'content-type': 'text/plain' } })
+    reply.compress(r)
+  })
+  const res = await fastify.inject({ url: '/', method: 'GET', headers: { 'accept-encoding': 'gzip' } })
+  t.assert.equal(zlib.gunzipSync(res.rawPayload).toString('utf8'), 'from reply.compress')
+})
+
+test('reply.compress should handle Web ReadableStream', async (t) => {
+  t.plan(1)
+  const fastify = Fastify()
+  await fastify.register(compressPlugin, { global: true, threshold: 0 })
+  fastify.get('/', (_req, reply) => {
+    const stream = new ReadableStream({
+      start (controller) {
+        controller.enqueue(Buffer.from('from webstream'))
+        controller.close()
+      }
+    })
+    reply.header('content-type', 'text/plain')
+    reply.compress(stream)
+  })
+  const res = await fastify.inject({ url: '/', method: 'GET', headers: { 'accept-encoding': 'gzip' } })
+  t.assert.equal(zlib.gunzipSync(res.rawPayload).toString('utf8'), 'from webstream')
+})

package/types/index.d.ts

@@ -26,7 +26,7 @@ declare module 'fastify' {
   }
 
   interface FastifyReply {
-    compress(input: Stream | Input): void;
+    compress(input: Stream | Input | Response | ReadableStream): void;
   }
 
   export interface RouteOptions {
@@ -77,6 +77,8 @@ declare namespace fastifyCompress {
     encodings?: EncodingToken[];
     forceRequestEncoding?: EncodingToken;
     global?: boolean;
+    globalDecompression?: boolean;
+    globalCompression?: boolean;
     inflateIfDeflated?: boolean;
     onInvalidRequestPayload?: (encoding: string, request: FastifyRequest, error: Error) => Error | undefined | null;
     onUnsupportedEncoding?: (encoding: string, request: FastifyRequest, reply: FastifyReply) => string | Buffer | Stream;

package/types/index.test-d.ts

@@ -132,3 +132,18 @@ expectError(appThatTriggerAnError.register(fastifyCompress, {
   global: true,
   thisOptionDoesNotExist: 'trigger a typescript error'
 }))
+
+app.get('/ts-fetch-response', async (_request, reply) => {
+  const resp = new Response('ok', { headers: { 'content-type': 'text/plain' } })
+  expectType<void>(reply.compress(resp))
+})
+
+app.get('/ts-web-readable-stream', async (_request, reply) => {
+  const stream = new ReadableStream({
+    start (controller) {
+      controller.enqueue(new Uint8Array([1, 2, 3]))
+      controller.close()
+    }
+  })
+  expectType<void>(reply.compress(stream))
+})

package/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__ripgrep__search"
-    ],
-    "deny": []
-  }
-}

package/CLAUDE.md

@@ -1,64 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-### Testing
-- `npm run test` - Run both unit and TypeScript tests
-- `npm run test:unit` - Run unit tests with Node.js test runner
-- `npm run test:coverage` - Run tests with coverage reporting
-- `npm run lint` - Run ESLint for code style checking
-- `npm run lint:fix` - Auto-fix linting issues
-
-### Running Single Tests
-Use Node.js test runner with file path:
-```bash
-node --test test/global-compress.test.js
-```
-
-## Architecture Overview
-
-This is a Fastify plugin (`@fastify/compress`) that provides compression and decompression capabilities for HTTP requests and responses.
-
-### Core Components
-
-**Main Plugin (`index.js`)**: 574-line plugin implementation using Fastify's hook system:
-- `onSend` hook for response compression
-- `preParsing` hook for request decompression  
-- `onRoute` hook for route-level configuration
-
-**Utilities (`lib/utils.js`)**: Core compression detection and stream handling:
-- `isZstd()` / `isGzip()` / `isDeflate()` - Magic byte detection (RFC 8878/1952/1950)
-- `isStream()` - Stream type checking
-- `intoAsyncIterator()` - Payload conversion utilities
-
-**TypeScript Support (`types/index.d.ts`)**: Full type definitions with Fastify module augmentation
-
-### Compression System
-
-**Supported Encodings**: zstd (Node.js 22.15+/23.8+), brotli (`br`), gzip, deflate, identity
-**Priority Order**: zstd > br > gzip > deflate > * (defaults to gzip) > identity
-**Threshold-based**: Default 1024 bytes minimum for compression
-**Content-Type Aware**: Uses `mime-db` for compressible content detection
-
-### Configuration Levels
-1. **Global**: Applied to all routes via plugin options
-2. **Route-level**: Override global settings in route config
-3. **Runtime**: Manual compression via `reply.compress()`
-
-### Key Dependencies
-- `@fastify/accept-negotiator` - Content encoding negotiation
-- `fastify-plugin` - Plugin registration
-- `mime-db` - MIME type database
-- `minipass`, `pump`, `pumpify` - Stream processing
-
-### Testing Structure
-Uses Node.js built-in test runner with describe/test pattern. Test files are organized by functionality:
-- `global-compress.test.js` / `global-decompress.test.js` - Global functionality
-- `routes-compress.test.js` / `routes-decompress.test.js` - Route-level functionality
-- `utils.test.js` - Utility functions
-- `regression/` - Regression tests
-
-### Code Style
-Uses `neostandard` (ESLint-based) with TypeScript support. Configuration in `eslint.config.js`.