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

``bash
npm install 7zip-wrapper
`

---

🚀 Quick Start

$3

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

`typescript
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,
});
`

$3

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

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

$3

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

`typescript
import { Readable } from 'stream';

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

$3

Get a Readable stream for a file inside an archive.

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

$3

Read a file from an archive directly into memory.

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

---

📚 API Reference

$3

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

$3

#### Progress Events

Monitor operation progress for UI feedback.

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

`typescript
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