Runtime-agnostic image compression utilities with pluggable adapters for Node.js (Sharp) and testing (MemoryAdapter). Supports resize, quality reduction, format conversion (JPEG, PNG, WebP, AVIF), and metadata stripping. The compressor core is pure TypeScript with zero runtime dependencies; only the Sharp adapter requires the native sharp library.

Documentation tree

memory — (no submodules)
- memory — (no submodules)
sharp — (no submodules)
- sharp — (no submodules)
compressor — (no submodules)
- compressor — (no submodules)
errors — (no submodules)
- compress-image-error — (no submodules)
schemas — (no submodules)
- compress-options.schema — (no submodules)
utils — (no submodules)
- image-utils — (no submodules)

Installation

bun add @suaveplan/compress-image

Quick Start

import { createCompressor } from "@suaveplan/compress-image/compressor";
import { SharpAdapter } from "@suaveplan/compress-image/adapters/sharp";
import sharp from "sharp";

const compressor = createCompressor(new SharpAdapter(sharp));

const result = await compressor.compress(imageBuffer, {
    format: "webp",
    quality: 75,
    width: 1280,
    height: 720,
    resizeMode: "cover",
    stripMetadata: true,
});

console.log(result.compressionRatio, result.compressedSize);

Modules

src/core/compressor/compressor.md — ImageCompressor core and createCompressor
src/adapters/memory/memory.md — MemoryAdapter for testing without native deps
src/adapters/sharp/sharp.md — SharpAdapter for Node.js production compression
src/errors/compress-image-error.md — CompressImageError and error codes
src/schemas/compress-options.schema.md — Zod schemas for compression options
src/types/compress-image.types.md — TypeScript interfaces for results and adapters
src/utils/image-utils.md — Pure TypeScript image utilities

Subpath Exports

. — All public types, errors, utilities, adapters, and the compressor
./compressor — ImageCompressor, createCompressor
./adapters/memory — MemoryAdapter
./adapters/sharp — SharpAdapter, SharpLike, SharpInstance
./errors — CompressImageError, COMPRESS_IMAGE_CODES