or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdplugin-configuration.mdrequest-decompression.mdresponse-compression.md
tile.json

tessl/npm-fastify--compress

Fastify plugin providing compression and decompression utilities for HTTP responses and requests.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@fastify/compress@8.1.x

To install, run

npx @tessl/cli install tessl/npm-fastify--compress@8.1.0

index.mddocs/

@fastify/compress

@fastify/compress is a comprehensive Fastify plugin that provides HTTP response compression and request decompression capabilities. It supports multiple compression algorithms including gzip, deflate, brotli, and zstd, with intelligent algorithm selection based on client Accept-Encoding headers and configurable compression thresholds.

Package Information

  • Package Name: @fastify/compress
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install @fastify/compress
  • Node.js Compatibility: All Node.js versions supported by Fastify 5.x
  • zstd Support: Node.js 22.15+ or 23.8+ required for zstd compression

Core Imports

const fastifyCompress = require('@fastify/compress');

ESM support:

import fastifyCompress from '@fastify/compress';

Basic Usage

const fastify = require('fastify')({ logger: true });

// Register the plugin with global compression
await fastify.register(fastifyCompress, {
  global: true,
  encodings: ['gzip', 'deflate', 'br'], 
  threshold: 1024
});

// Routes will automatically compress responses > 1024 bytes
fastify.get('/data', async (request, reply) => {
  return { large: 'data'.repeat(1000) };
});

// Manual compression using reply.compress
fastify.get('/manual', async (request, reply) => {
  const data = { message: 'Hello World' };
  reply.compress(data);
});

await fastify.listen({ port: 3000 });

Architecture

@fastify/compress integrates deeply with Fastify's lifecycle through several key components:

  • Plugin Registration: Configures global compression and decompression settings
  • Hook Integration: Automatically adds lifecycle hooks for transparent operation
  • Reply Decoration: Adds reply.compress() method for manual compression control
  • Content Negotiation: Uses Accept-Encoding headers to select optimal compression algorithm
  • Stream Processing: Handles both buffer and stream payloads with compression detection

Hook Integration Details

// Fastify lifecycle hooks used by @fastify/compress
const LIFECYCLE_HOOKS = {
  // onRoute: Configures per-route compression/decompression settings
  onRoute: 'Merges global and route-specific options during route registration',
  
  // onRequest: Decorates reply object with compress method
  onRequest: 'Adds reply.compress() method for manual compression',
  
  // preParsing: Handles automatic request decompression
  preParsing: 'Decompresses request payload based on Content-Encoding header',
  
  // onSend: Handles automatic response compression
  onSend: 'Compresses response payload based on Accept-Encoding header'
};

Capabilities

Plugin Configuration

Core plugin setup with global compression and decompression settings, encoding preferences, and custom content-type matching.

function fastifyCompress(
  fastify: FastifyInstance,
  options: FastifyCompressOptions,
  next: (err?: Error) => void
): void;

interface FastifyCompressOptions {
  global?: boolean;
  encodings?: EncodingToken[];
  threshold?: number;
  customTypes?: RegExp | CompressibleContentTypeFunction;
  brotliOptions?: BrotliOptions;
  zlibOptions?: ZlibOptions;
  removeContentLengthHeader?: boolean;
  inflateIfDeflated?: boolean;
  onUnsupportedEncoding?: (encoding: string, request: FastifyRequest, reply: FastifyReply) => string | Buffer | Stream;
  requestEncodings?: EncodingToken[];
  forceRequestEncoding?: EncodingToken;
  onUnsupportedRequestEncoding?: (encoding: string, request: FastifyRequest) => Error | undefined | null;
  onInvalidRequestPayload?: (encoding: string, request: FastifyRequest, error: Error) => Error | undefined | null;
  zlib?: unknown;
}

Plugin Configuration

Response Compression

Automatic and manual response compression with content-type filtering, algorithm selection, and custom compression thresholds.

// Reply decoration
interface FastifyReply {
  compress(payload: CompressiblePayload): void;
}

type Input =
  | Buffer
  | NodeJS.TypedArray
  | ArrayBuffer
  | string
  | Iterable<Buffer | string>
  | AsyncIterable<Buffer | string>;

type CompressiblePayload = Input | Stream;

Response Compression

Request Decompression

Automatic decompression of compressed request payloads with support for multiple encoding algorithms and error handling.

// Route-level decompression configuration
interface RouteDecompressOptions {
  forceRequestEncoding?: EncodingToken;
  onInvalidRequestPayload?: (encoding: string, request: FastifyRequest, error: Error) => Error | undefined | null;
  onUnsupportedRequestEncoding?: (encoding: string, request: FastifyRequest) => Error | undefined | null;
  requestEncodings?: EncodingToken[];
  zlib?: unknown;
}

Request Decompression

Types

type EncodingToken = 'zstd' | 'br' | 'gzip' | 'deflate' | 'identity';

type CompressibleContentTypeFunction = (contentType: string) => boolean;

// Route-level compression options
type RouteCompressOptions = Pick<FastifyCompressOptions,
  | 'brotliOptions'
  | 'customTypes' 
  | 'encodings'
  | 'inflateIfDeflated'
  | 'onUnsupportedEncoding'
  | 'removeContentLengthHeader'
  | 'threshold'
  | 'zlib'
  | 'zlibOptions'
>;

interface BrotliOptions {
  params?: {
    [key: number]: number;
  };
}

interface ZlibOptions {
  flush?: number;
  finishFlush?: number;
  chunkSize?: number;
  windowBits?: number;
  level?: number;
  memLevel?: number;
  strategy?: number;
  dictionary?: Buffer | NodeJS.TypedArray | DataView | ArrayBuffer;
}

Constants and Defaults

The plugin uses several important constants and default values:

// Default compression threshold (bytes)
const DEFAULT_THRESHOLD = 1024;

// Default compressible content types (regex)
const DEFAULT_COMPRESSIBLE_TYPES = /^text\/(?!event-stream)|(?:\+|\/)json(?:;|$)|(?:\+|\/)text(?:;|$)|(?:\+|\/)xml(?:;|$)|octet-stream(?:;|$)/u;

// Default Brotli compression quality
const DEFAULT_BROTLI_QUALITY = 4;

// gzip alias patterns in Accept-Encoding headers
const GZIP_ALIAS_PATTERN = /\*|x-gzip/gu;

// Plugin metadata
const PLUGIN_NAME = '@fastify/compress';
const FASTIFY_VERSION = '5.x';

Error Handling

The plugin defines custom error classes for compression-related failures:

// Error codes
const ERROR_CODES = {
  INVALID_CONTENT_ENCODING: 'FST_CP_ERR_INVALID_CONTENT_ENCODING',
  INVALID_CONTENT: 'FST_CP_ERR_INVALID_CONTENT'
};

class InvalidRequestEncodingError extends Error {
  name: 'FastifyCompressError';
  code: 'FST_CP_ERR_INVALID_CONTENT_ENCODING';
  statusCode: 415;
  message: 'Unsupported Content-Encoding: {encoding}';
}

class InvalidRequestCompressedPayloadError extends Error {
  name: 'FastifyCompressError';
  code: 'FST_CP_ERR_INVALID_CONTENT';
  statusCode: 400;
  message: 'Could not decompress the request payload using the provided encoding';
}