peasy-compress

v0.2.2

Published

4 days ago

Archive & compression library for Node.js — ZIP, gzip, brotli, deflate. Zero-config, TypeScript-first.

0High
0Medium
0Low

dobestan

compress zip gzip brotli archive peasy

peasy-compress

Archive and compression library for Node.js -- ZIP create/extract/list/add, gzip, brotli, and deflate. TypeScript-first with full type safety, built on Node.js native zlib and adm-zip.

Built from Peasy Compress, the developer tools platform for file processing, text analysis, and web utilities.

Try the interactive tools at peasytools.com -- compression, archiving, and 255 more browser-based tools

Install

npm install peasy-compress

Quick Start

import {
  zipCreate,
  zipExtract,
  gzipCompress,
  gzipDecompress,
  brotliCompress,
} from "peasy-compress";

// Create a ZIP archive from files
const zip = zipCreate({
  "readme.txt": Buffer.from("Hello, world!"),
  "data.json": Buffer.from('{"version": 1}'),
});

// Extract all files from a ZIP
const files = zipExtract(zip);
console.log(files["readme.txt"]?.toString()); // "Hello, world!"

// Gzip compress and decompress
const compressed = gzipCompress(Buffer.from("Repetitive data ".repeat(100)));
const original = gzipDecompress(compressed);

// Brotli compression (great for web content)
const brotlied = brotliCompress(Buffer.from("<html>...</html>"), 9);

What You Can Do

ZIP Archives

ZIP is the most widely used archive format, combining multiple files into a single container with per-file compression. The ZIP format (PKZIP, 1989) supports file metadata, directory structures, and random access to individual entries without decompressing the entire archive.

| Operation | Function | Description | |-----------|----------|-------------| | Create | zipCreate() | Build a ZIP from a name-to-Buffer mapping | | Extract | zipExtract() | Extract all files from a ZIP to a Record | | List | zipList() | Inspect archive contents, sizes, and counts | | Add | zipAdd() | Append files to an existing ZIP archive |

import { zipCreate, zipExtract, zipList, zipAdd } from "peasy-compress";

// Create a ZIP archive with multiple files
const archive = zipCreate({
  "src/index.ts": Buffer.from('export const version = "1.0";'),
  "package.json": Buffer.from('{"name": "my-lib"}'),
  "LICENSE": Buffer.from("MIT License..."),
});

// Inspect archive contents without extracting
const info = zipList(archive);
console.log(info.fileCount);     // 3
console.log(info.totalSize);     // total uncompressed bytes
console.log(info.entries[0]);    // { name, size, compressedSize, isDir }

// Add more files to an existing archive
const updated = zipAdd(archive, {
  "README.md": Buffer.from("# My Library"),
});

// Extract everything
const files = zipExtract(updated);
Object.keys(files); // ["src/index.ts", "package.json", "LICENSE", "README.md"]

Learn more: Archive Formats Compared · What is Lossless Compression? · What is Compression Ratio?

Gzip Compression

Gzip (RFC 1952) is the standard compression format for HTTP content encoding and Unix file compression. It wraps DEFLATE with a header containing metadata like timestamps and checksums. Virtually all web servers and browsers support gzip natively.

import { gzipCompress, gzipDecompress } from "peasy-compress";

// Compress text content for storage or transfer
const html = Buffer.from("<html>".repeat(1000));
const compressed = gzipCompress(html);
console.log(compressed.length); // much smaller than original

// Verify gzip magic bytes (0x1f 0x8b)
console.log(compressed[0] === 0x1f); // true

// Decompress back to original
const original = gzipDecompress(compressed);
console.log(original.toString().startsWith("<html>")); // true

// Control compression level (1=fastest, 9=best compression)
const fast = gzipCompress(html, 1);
const best = gzipCompress(html, 9);

Learn more: Lossless vs Lossy Compression Guide · What is Archive? · What is Entropy?

Brotli Compression

Brotli (RFC 7932) is a modern compression algorithm developed by Google, achieving 15-25% better compression ratios than gzip for web content. All modern browsers support Brotli via the Content-Encoding: br header. It uses a pre-defined dictionary of common web patterns for superior text compression.

import { brotliCompress, brotliDecompress } from "peasy-compress";

// Compress web content with Brotli for best ratios
const css = Buffer.from("body { margin: 0; padding: 0; } ".repeat(500));
const compressed = brotliCompress(css, 9);

// Brotli typically outperforms gzip on text content
console.log(`${css.length} -> ${compressed.length} bytes`);

// Decompress
const original = brotliDecompress(compressed);
console.log(original.equals(css)); // true

// Fast compression for real-time use cases
const quick = brotliCompress(css, 1);

Learn more: Archive Compression Formats Explained · What is Brotli? · What is Lossy Compression?

Deflate Compression

DEFLATE (RFC 1951) is the foundational compression algorithm used inside both gzip and ZIP. The raw deflate functions are useful when you need the core LZ77+Huffman compression without any framing format -- for example, inside custom binary protocols or when implementing your own container format.

import { deflateCompress, deflateDecompress } from "peasy-compress";

// Raw DEFLATE compression (no gzip/zlib headers)
const data = Buffer.from("DEFLATE is the foundation of gzip and ZIP");
const compressed = deflateCompress(data);
const original = deflateDecompress(compressed);
console.log(original.toString()); // "DEFLATE is the foundation of gzip and ZIP"

// Compression levels work the same way
const fast = deflateCompress(data, 1);
const best = deflateCompress(data, 9);

Learn more: Archive Format ZIP TAR 7z RAR Compared · What is TAR? · What is Lossless Compression?

TypeScript Types

import type {
  ArchiveEntry,
  ArchiveInfo,
  CompressionLevel,
} from "peasy-compress";

// ArchiveEntry — metadata for a single file in an archive
const entry: ArchiveEntry = {
  name: "hello.txt",
  size: 13,
  compressedSize: 11,
  isDir: false,
};

// ArchiveInfo — summary of an archive's contents
const info: ArchiveInfo = {
  format: "zip",
  entries: [entry],
  totalSize: 13,
  totalCompressed: 11,
  fileCount: 1,
  dirCount: 0,
};

// CompressionLevel — 1 (fastest) to 9 (best compression)
const level: CompressionLevel = 6;

API Reference

| Function | Description | |----------|-------------| | zipCreate(files) | Create ZIP archive from Record<string, Buffer> | | zipExtract(source) | Extract all files from ZIP to Record<string, Buffer> | | zipList(source) | List ZIP contents with metadata (ArchiveInfo) | | zipAdd(source, files) | Add files to existing ZIP archive | | gzipCompress(data, level?) | Gzip compress a Buffer | | gzipDecompress(data) | Gzip decompress a Buffer | | deflateCompress(data, level?) | DEFLATE compress a Buffer | | deflateDecompress(data) | DEFLATE decompress (inflate) a Buffer | | brotliCompress(data, level?) | Brotli compress a Buffer | | brotliDecompress(data) | Brotli decompress a Buffer |

REST API Client

The API client connects to the Peasy Compress developer API for tool discovery and content.

import { PeasyCompressClient } from "peasy-compress";

const client = new PeasyCompressClient();

// List available tools
const tools = await client.listTools();
console.log(tools.results);

// Search across all content
const results = await client.search("zip");
console.log(results);

// Browse the glossary
const glossary = await client.listGlossary({ search: "format" });
for (const term of glossary.results) {
  console.log(`${term.term}: ${term.definition}`);
}

// Discover guides
const guides = await client.listGuides({ category: "compress" });
for (const guide of guides.results) {
  console.log(`${guide.title} (${guide.audience_level})`);
}

Full API documentation at peasytools.com/developers/.

Learn More

Guides: Archive Formats Compared · Lossless vs Lossy Compression · Archive Compression Formats Explained · Archive Format ZIP TAR 7z RAR Compared · PDF Compression Guide · All Guides
Glossary: Archive · TAR · Brotli · Lossless Compression · Lossy Compression · Compression Ratio · Entropy · All Terms
Formats: ZIP · TAR · Gzip · 7z · BZ2 · XZ · LZ4 · Zstandard · RAR · All Formats
API: REST API Docs · OpenAPI Spec

Also Available

| Language | Package | Install | |----------|---------|---------| | Python | peasy-compress | pip install "peasy-compress[all]" | | Go | peasy-compress-go | go get github.com/peasytools/peasy-compress-go | | Rust | peasy-compress | cargo add peasy-compress | | Ruby | peasy-compress | gem install peasy-compress |

Peasy Developer Tools

Part of the Peasy Tools open-source developer ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | peasy-pdf | PyPI | npm | PDF merge, split, rotate, compress, 21 operations — peasypdf.com | | peasy-image | PyPI | npm | Image resize, crop, convert, compress — peasyimage.com | | peasy-audio | PyPI | npm | Audio trim, merge, convert, normalize — peasyaudio.com | | peasy-video | PyPI | npm | Video trim, resize, thumbnails, GIF — peasyvideo.com | | peasy-css | PyPI | npm | CSS minify, format, analyze — peasycss.com | | peasy-compress | PyPI | npm | ZIP, TAR, gzip compression — peasytools.com | | peasy-document | PyPI | npm | Markdown, HTML, CSV, JSON conversion — peasyformats.com | | peasytext | PyPI | npm | Text case conversion, slugify, word count — peasytext.com |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

peasy-compress

Table of Contents

Install

Quick Start

What You Can Do

ZIP Archives

Gzip Compression

Brotli Compression

Deflate Compression

TypeScript Types

API Reference

REST API Client

Learn More

Also Available

Peasy Developer Tools

License