@fastify/compress/CLAUDE.md

Fastify compression utils

# 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`.