7zip-wrapper

A powerful, type-safe Node.js wrapper for 7-Zip with native Stream & Buffer support.

7zip-wrapper provides a modern, Promise-based API for 7-Zip operations. It bundles the 7-Zip binary for Windows, Linux, and macOS, ensuring zero configuration and reliable execution everywhere.

✨ Features

• 🔋 Bundled Binaries: No external dependencies or system installations required. Works out of the box.
• 🌊 Stream Support: Pipe data directly into archives (addFromStream) and out of archives (extractToStream).
• 💾 Buffer Support: Extract files directly to memory (extractToBuffer) or add Buffers to archives.
• 📦 Multi-Format: Support for 7z, ZIP, TAR, GZIP, XZ, and reading RAR.
• 🔒 Security: Full password protection and header encryption support.
• 🚀 TypeScript: Written in TypeScript with complete type definitions.
• 📈 Progress Monitoring: Real-time progress updates for long-running operations.

📦 Installation

npm install 7zip-wrapper

🚀 Quick Start

Object-Oriented API (Recommended)

The ZipWrapper class provides a clean, fluent interface for all operations.

import { ZipWrapper } from '7zip-wrapper';

const zip = new ZipWrapper();

// 1. Create an archive
await zip.add('backup.7z', ['src/', 'package.json'], {
  level: 9,
  password: 'secret-password',
});

// 2. Extract an archive
await zip.extract('backup.7z', {
  outputDir: './restored',
  overwrite: true,
});

Functional API

If you prefer functions over classes, you can import them directly:

import { add, extract, list } from '7zip-wrapper';

await add('archive.zip', 'files/', { type: 'zip' });
await extract('archive.zip', { outputDir: 'out' });

🌊 Streams & Buffers (New!)

Handle data efficiently without writing to temporary files.

Streaming Into an Archive

Pipe a Readable stream (or Buffer) directly into an archive entry.

import { Readable } from 'stream';

const myStream = Readable.from(['Hello World']);
await zip.addFromStream('archive.7z', 'hello.txt', myStream);

Streaming Out of an Archive

Get a Readable stream for a file inside an archive.

const readStream = zip.extractToStream('archive.7z', 'large-file.log');
readStream.pipe(process.stdout);

Working with Buffers

Read a file from an archive directly into memory.

const buffer = await zip.extractToBuffer('assets.7z', 'config.json');
const config = JSON.parse(buffer.toString());

📚 API Reference

Core Operations

add(archive, files, options)

Create or update an archive.

| Option | Type | Description | | ------------------ | --------- | ------------------------------------------------- | | type | string | Archive format (7z, zip, tar, gzip, etc.) | | level | 0-9 | Compression level (0=store, 9=ultra) | | password | string | Password for encryption | | encryptFilenames | boolean | Encrypt file names (Head encryption) | | recursive | boolean | Recurse into subdirectories (default: true) |

extract(archive, options)

Extract files from an archive.

| Option | Type | Description | | ----------- | ---------- | ---------------------------------- | | outputDir | string | Destination directory | | files | string[] | Specific files/patterns to extract | | overwrite | boolean | Overwrite existing files | | password | string | Password for decryption |

Advanced Usage

Progress Events

Monitor operation progress for UI feedback.

await zip.add('big-archive.7z', 'data/', {
  onProgress: (progress) => {
    console.log(`Processing: ${progress.percent}% (${progress.file})`);
  },
});

Quick Helpers

For simple, one-off tasks without configuration.

import { quick } from '7zip-wrapper';

await quick.zip(['file1.txt'], 'archive.zip'); // Max compression ZIP
await quick.sevenz(['file1.txt'], 'archive.7z'); // Max compression 7z
await quick.extract('archive.7z', 'output/');

📂 Supported Formats

| Format | Read | Write | | ------ | ---- | ----- | | 7z | ✅ | ✅ | | ZIP | ✅ | ✅ | | TAR | ✅ | ✅ | | GZIP | ✅ | ✅ | | XZ | ✅ | ✅ | | RAR | ✅ | ❌* |

*RAR creation is not supported by 7-Zip open source binaries.

🛠 Project Structure

• src/: TypeScript source code.
• examples/: Ready-to-run usage examples.

📄 License

MIT © Rashed Iqbal