npm - peasy-compress - Versions diffs - 0.1.0 - Mend

peasy-compress 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Peasy Tools
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,242 @@
+# peasy-compress
+[![npm](https://img.shields.io/npm/v/peasy-compress)](https://www.npmjs.com/package/peasy-compress)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+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](https://peasytools.com), the developer tools platform for file processing, text analysis, and web utilities.
+> **Try the interactive tools at [peasytools.com](https://peasytools.com)** -- [Compress Tool](https://peasytools.com/tools/compress/), [Archive Tool](https://peasytools.com/tools/archive/)
+## Table of Contents
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+  - [ZIP Archives](#zip-archives)
+  - [Gzip Compression](#gzip-compression)
+  - [Brotli Compression](#brotli-compression)
+  - [Deflate Compression](#deflate-compression)
+- [TypeScript Types](#typescript-types)
+- [API Reference](#api-reference)
+- [Also Available for Python](#also-available-for-python)
+- [Peasy Developer Tools](#peasy-developer-tools)
+- [License](#license)
+## Install
+```bash
+npm install peasy-compress
+```
+## Quick Start
+```typescript
+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 |
+```typescript
+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: [Compress Tool](https://peasytools.com/tools/compress/) -- [Archive Guide](https://peasytools.com/glossary/archive/)
+### 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.
+```typescript
+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: [Gzip Reference](https://peasytools.com/glossary/gzip/) -- [Compression Guide](https://peasytools.com/glossary/compression/)
+### 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.
+```typescript
+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: [Brotli Reference](https://peasytools.com/glossary/brotli/) -- [Web Compression Guide](https://peasytools.com/glossary/web-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.
+```typescript
+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: [Deflate Reference](https://peasytools.com/glossary/deflate/) -- [Compression Algorithms](https://peasytools.com/glossary/compression-algorithms/)
+## TypeScript Types
+```typescript
+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 |
+## Also Available for Python
+```bash
+pip install peasy-compress
+```
+The Python package provides ZIP, tar, and gzip operations with CLI, MCP server, and REST API client. See [peasy-compress on PyPI](https://pypi.org/project/peasy-compress/).
+## Peasy Developer Tools
+| Package | PyPI | npm | Description |
+|---------|------|-----|-------------|
+| peasytext | [PyPI](https://pypi.org/project/peasytext/) | [npm](https://www.npmjs.com/package/peasytext) | Text analysis -- readability, sentiment, keywords |
+| peasy-pdf | [PyPI](https://pypi.org/project/peasy-pdf/) | -- | PDF processing -- extract, merge, split, metadata |
+| peasy-image | [PyPI](https://pypi.org/project/peasy-image/) | -- | Image ops -- resize, crop, filter, watermark |
+| peasy-css | [PyPI](https://pypi.org/project/peasy-css/) | [npm](https://www.npmjs.com/package/peasy-css) | CSS generation -- gradients, shadows, flexbox, grid |
+| **peasy-compress** | [PyPI](https://pypi.org/project/peasy-compress/) | **[npm](https://www.npmjs.com/package/peasy-compress)** | **Archive & compression -- ZIP, gzip, brotli, deflate** |
+Part of the [Peasy](https://peasytools.com) developer tools ecosystem.
+## License
+MIT

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,180 @@
+/**
+ * peasy-compress — Archive & compression types.
+ *
+ * @packageDocumentation
+ */
+/** Metadata for a single entry inside an archive. */
+interface ArchiveEntry {
+    /** File or directory name (relative path within the archive). */
+    name: string;
+    /** Uncompressed size in bytes. */
+    size: number;
+    /** Compressed size in bytes. */
+    compressedSize: number;
+    /** Whether this entry is a directory. */
+    isDir: boolean;
+}
+/** Summary information about an archive. */
+interface ArchiveInfo {
+    /** Archive format identifier (e.g. "zip"). */
+    format: string;
+    /** List of all entries in the archive. */
+    entries: ArchiveEntry[];
+    /** Total uncompressed size in bytes. */
+    totalSize: number;
+    /** Total compressed size in bytes. */
+    totalCompressed: number;
+    /** Number of file entries. */
+    fileCount: number;
+    /** Number of directory entries. */
+    dirCount: number;
+}
+/** Compression level from 1 (fastest) to 9 (best compression). */
+type CompressionLevel = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * peasy-compress — Archive & compression engine.
+ *
+ * ZIP operations use adm-zip. Gzip, deflate, and brotli use Node.js
+ * built-in zlib module for zero-config compression.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create a ZIP archive from a name-to-content mapping.
+ *
+ * @param files - Record where keys are filenames and values are file contents
+ * @returns Buffer containing the ZIP archive
+ *
+ * @example
+ * ```typescript
+ * const zip = zipCreate({
+ *   "hello.txt": Buffer.from("Hello, world!"),
+ *   "data.json": Buffer.from('{"key": "value"}'),
+ * });
+ * ```
+ */
+declare function zipCreate(files: Record<string, Buffer>): Buffer;
+/**
+ * Extract all files from a ZIP archive.
+ *
+ * @param source - Buffer containing a ZIP archive
+ * @returns Record where keys are filenames and values are file contents
+ *
+ * @example
+ * ```typescript
+ * const files = zipExtract(zipBuffer);
+ * console.log(files["hello.txt"].toString()); // "Hello, world!"
+ * ```
+ */
+declare function zipExtract(source: Buffer): Record<string, Buffer>;
+/**
+ * List the contents of a ZIP archive with metadata.
+ *
+ * @param source - Buffer containing a ZIP archive
+ * @returns Archive information including entries, sizes, and counts
+ *
+ * @example
+ * ```typescript
+ * const info = zipList(zipBuffer);
+ * console.log(info.fileCount); // 2
+ * console.log(info.totalSize); // 42
+ * ```
+ */
+declare function zipList(source: Buffer): ArchiveInfo;
+/**
+ * Add files to an existing ZIP archive.
+ *
+ * @param source - Buffer containing an existing ZIP archive
+ * @param files - Record of files to add (name to content mapping)
+ * @returns New Buffer containing the updated ZIP archive
+ *
+ * @example
+ * ```typescript
+ * const updated = zipAdd(existingZip, {
+ *   "new-file.txt": Buffer.from("New content"),
+ * });
+ * ```
+ */
+declare function zipAdd(source: Buffer, files: Record<string, Buffer>): Buffer;
+/**
+ * Compress data using gzip.
+ *
+ * @param data - Buffer to compress
+ * @param level - Compression level 1-9 (default: 6)
+ * @returns Gzip-compressed Buffer
+ *
+ * @example
+ * ```typescript
+ * const compressed = gzipCompress(Buffer.from("Hello, world!"));
+ * ```
+ */
+declare function gzipCompress(data: Buffer, level?: CompressionLevel): Buffer;
+/**
+ * Decompress gzip data.
+ *
+ * @param data - Gzip-compressed Buffer
+ * @returns Decompressed Buffer
+ *
+ * @example
+ * ```typescript
+ * const original = gzipDecompress(compressed);
+ * console.log(original.toString()); // "Hello, world!"
+ * ```
+ */
+declare function gzipDecompress(data: Buffer): Buffer;
+/**
+ * Compress data using deflate (raw DEFLATE without gzip/zlib headers).
+ *
+ * @param data - Buffer to compress
+ * @param level - Compression level 1-9 (default: 6)
+ * @returns Deflated Buffer
+ *
+ * @example
+ * ```typescript
+ * const compressed = deflateCompress(Buffer.from("Hello, world!"));
+ * ```
+ */
+declare function deflateCompress(data: Buffer, level?: CompressionLevel): Buffer;
+/**
+ * Decompress deflate data.
+ *
+ * @param data - Deflated Buffer
+ * @returns Decompressed Buffer
+ *
+ * @example
+ * ```typescript
+ * const original = deflateDecompress(compressed);
+ * console.log(original.toString()); // "Hello, world!"
+ * ```
+ */
+declare function deflateDecompress(data: Buffer): Buffer;
+/**
+ * Compress data using Brotli.
+ *
+ * @param data - Buffer to compress
+ * @param level - Compression level 1-9 (maps to Brotli quality 1-11, default: 6)
+ * @returns Brotli-compressed Buffer
+ *
+ * @example
+ * ```typescript
+ * const compressed = brotliCompress(Buffer.from("Hello, world!"));
+ * ```
+ */
+declare function brotliCompress(data: Buffer, level?: CompressionLevel): Buffer;
+/**
+ * Decompress Brotli data.
+ *
+ * @param data - Brotli-compressed Buffer
+ * @returns Decompressed Buffer
+ *
+ * @example
+ * ```typescript
+ * const original = brotliDecompress(compressed);
+ * console.log(original.toString()); // "Hello, world!"
+ * ```
+ */
+declare function brotliDecompress(data: Buffer): Buffer;
+export { type ArchiveEntry, type ArchiveInfo, type CompressionLevel, brotliCompress, brotliDecompress, deflateCompress, deflateDecompress, gzipCompress, gzipDecompress, zipAdd, zipCreate, zipExtract, zipList };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,102 @@
+// src/engine.ts
+import {
+  gzipSync,
+  gunzipSync,
+  deflateSync,
+  inflateSync,
+  brotliCompressSync,
+  brotliDecompressSync,
+  constants
+} from "zlib";
+import AdmZip from "adm-zip";
+function zipCreate(files) {
+  const zip = new AdmZip();
+  for (const [name, content] of Object.entries(files)) {
+    zip.addFile(name, content);
+  }
+  return zip.toBuffer();
+}
+function zipExtract(source) {
+  const zip = new AdmZip(source);
+  const result = {};
+  for (const entry of zip.getEntries()) {
+    if (!entry.isDirectory) {
+      result[entry.entryName] = entry.getData();
+    }
+  }
+  return result;
+}
+function zipList(source) {
+  const zip = new AdmZip(source);
+  const entries = [];
+  let totalSize = 0;
+  let totalCompressed = 0;
+  let fileCount = 0;
+  let dirCount = 0;
+  for (const entry of zip.getEntries()) {
+    const archiveEntry = {
+      name: entry.entryName,
+      size: entry.header.size,
+      compressedSize: entry.header.compressedSize,
+      isDir: entry.isDirectory
+    };
+    entries.push(archiveEntry);
+    if (entry.isDirectory) {
+      dirCount++;
+    } else {
+      fileCount++;
+      totalSize += entry.header.size;
+      totalCompressed += entry.header.compressedSize;
+    }
+  }
+  return {
+    format: "zip",
+    entries,
+    totalSize,
+    totalCompressed,
+    fileCount,
+    dirCount
+  };
+}
+function zipAdd(source, files) {
+  const zip = new AdmZip(source);
+  for (const [name, content] of Object.entries(files)) {
+    zip.addFile(name, content);
+  }
+  return zip.toBuffer();
+}
+function gzipCompress(data, level) {
+  return gzipSync(data, { level: level ?? constants.Z_DEFAULT_COMPRESSION });
+}
+function gzipDecompress(data) {
+  return gunzipSync(data);
+}
+function deflateCompress(data, level) {
+  return deflateSync(data, { level: level ?? constants.Z_DEFAULT_COMPRESSION });
+}
+function deflateDecompress(data) {
+  return inflateSync(data);
+}
+function brotliCompress(data, level) {
+  const params = {};
+  if (level !== void 0) {
+    const quality = Math.round(1 + (level - 1) / 8 * 10);
+    params[constants.BROTLI_PARAM_QUALITY] = quality;
+  }
+  return brotliCompressSync(data, { params });
+}
+function brotliDecompress(data) {
+  return brotliDecompressSync(data);
+}
+export {
+  brotliCompress,
+  brotliDecompress,
+  deflateCompress,
+  deflateDecompress,
+  gzipCompress,
+  gzipDecompress,
+  zipAdd,
+  zipCreate,
+  zipExtract,
+  zipList
+};

package/package.json ADDED Viewed

@@ -0,0 +1,47 @@
+{
+  "name": "peasy-compress",
+  "version": "0.1.0",
+  "description": "Archive & compression library for Node.js — ZIP, gzip, brotli, deflate. Zero-config, TypeScript-first.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "compress",
+    "zip",
+    "gzip",
+    "brotli",
+    "archive",
+    "peasy"
+  ],
+  "author": "Peasy Tools",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/peasytools/peasy-compress-js.git"
+  },
+  "homepage": "https://peasytools.com",
+  "dependencies": {
+    "adm-zip": "^0.5",
+    "archiver": "^7.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5",
+    "@types/archiver": "^6.0",
+    "tsup": "^8.0",
+    "typescript": "^5.7",
+    "vitest": "^3.0"
+  }
+}