@push.rocks/smartarchive 5.0.0 → 5.1.0

package/readme.md

@@ -1,8 +1,6 @@
 # @push.rocks/smartarchive 📦
 
-Powerful archive manipulation for modern Node.js applications.
-
-`@push.rocks/smartarchive` is a versatile library for handling archive files with a focus on developer experience. Work with **zip**, **tar**, **gzip**, and **bzip2** formats through a unified, streaming-optimized API.
+A powerful, streaming-first archive manipulation library with a fluent builder API. Works seamlessly in Node.js and Deno.
 
 ## Issue Reporting and Security
 
@@ -10,13 +8,15 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## Features 🚀
 
-- 📁 **Multi-format support** – Handle `.zip`, `.tar`, `.tar.gz`, `.tgz`, and `.bz2` archives
+- 📁 **Multi-format support** – Handle `.zip`, `.tar`, `.tar.gz`, `.tgz`, `.gz`, and `.bz2` archives
 - 🌊 **Streaming-first architecture** – Process large archives without memory constraints
-- 🔄 **Unified API** – Consistent interface across different archive formats
+- ✨ **Fluent builder API** – Chain methods for readable, expressive code
 - 🎯 **Smart detection** – Automatically identifies archive types via magic bytes
 - ⚡ **High performance** – Built on `tar-stream` and `fflate` for speed
-- 🔧 **Flexible I/O** – Work with files, URLs, and streams seamlessly
+- 🔧 **Flexible I/O** – Work with files, URLs, streams, and buffers seamlessly
 - 🛠️ **Modern TypeScript** – Full type safety and excellent IDE support
+- 🔄 **Dual-mode operation** – Extract existing archives OR create new ones
+- 🦕 **Cross-runtime** – Works in both Node.js and Deno environments
 
 ## Installation 📥
 
@@ -39,354 +39,348 @@ yarn add @push.rocks/smartarchive
 import { SmartArchive } from '@push.rocks/smartarchive';
 
 // Extract a .tar.gz archive from a URL directly to the filesystem
-const archive = await SmartArchive.fromArchiveUrl(
-  'https://registry.npmjs.org/some-package/-/some-package-1.0.0.tgz'
-);
-await archive.exportToFs('./extracted');
+await SmartArchive.create()
+  .url('https://registry.npmjs.org/some-package/-/some-package-1.0.0.tgz')
+  .extract('./extracted');
 ```
 
-### Process archive as a stream
+### Create an archive from entries
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
 
-// Stream-based processing for memory efficiency
-const archive = await SmartArchive.fromArchiveFile('./large-archive.zip');
-const streamOfFiles = await archive.exportToStreamOfStreamFiles();
-
-// Process each file in the archive
-streamOfFiles.on('data', async (streamFile) => {
-  console.log(`Processing ${streamFile.relativeFilePath}`);
-  const readStream = await streamFile.createReadStream();
-  // Handle individual file stream
-});
-
-streamOfFiles.on('end', () => {
-  console.log('Extraction complete');
-});
+// Create a tar.gz archive with files
+await SmartArchive.create()
+  .format('tar.gz')
+  .compression(6)
+  .entry('config.json', JSON.stringify({ name: 'myapp' }))
+  .entry('readme.txt', 'Hello World!')
+  .toFile('./backup.tar.gz');
 ```
 
-## Core Concepts 💡
-
-### Archive Sources
-
-`SmartArchive` accepts archives from three sources:
-
-| Source | Method | Use Case |
-|--------|--------|----------|
-| **URL** | `SmartArchive.fromArchiveUrl(url)` | Download and process archives from the web |
-| **File** | `SmartArchive.fromArchiveFile(path)` | Load archives from the local filesystem |
-| **Stream** | `SmartArchive.fromArchiveStream(stream)` | Process archives from any Node.js stream |
-
-### Export Destinations
-
-| Destination | Method | Use Case |
-|-------------|--------|----------|
-| **Filesystem** | `exportToFs(targetDir, fileName?)` | Extract directly to a directory |
-| **Stream of files** | `exportToStreamOfStreamFiles()` | Process files individually as `StreamFile` objects |
-
-## Usage Examples 🔨
-
-### Working with ZIP files
+### Extract with filtering and path manipulation
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
 
-// Extract a ZIP file
-const zipArchive = await SmartArchive.fromArchiveFile('./archive.zip');
-await zipArchive.exportToFs('./output');
-
-// Stream ZIP contents for processing
-const fileStream = await zipArchive.exportToStreamOfStreamFiles();
-
-fileStream.on('data', async (streamFile) => {
-  if (streamFile.relativeFilePath.endsWith('.json')) {
-    const readStream = await streamFile.createReadStream();
-    // Process JSON files from the archive
-  }
-});
+// Extract only JSON files, stripping the first path component
+await SmartArchive.create()
+  .url('https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz')
+  .stripComponents(1)           // Remove 'package/' prefix
+  .include(/\.json$/)           // Only extract JSON files
+  .extract('./node_modules/lodash');
 ```
 
-### Working with TAR archives
+## Core Concepts 💡
 
-```typescript
-import { SmartArchive, TarTools } from '@push.rocks/smartarchive';
+### Fluent Builder Pattern
 
-// Extract a .tar.gz file
-const tarGzArchive = await SmartArchive.fromArchiveFile('./archive.tar.gz');
-await tarGzArchive.exportToFs('./extracted');
+`SmartArchive` uses a fluent builder pattern where you chain methods to configure the operation:
 
-// Create a TAR archive using TarTools directly
-const tarTools = new TarTools();
-const pack = await tarTools.getPackStream();
+```typescript
+SmartArchive.create()     // Start a new builder
+  .source(...)            // Configure source (extraction mode)
+  .options(...)           // Set options
+  .terminal()             // Execute the operation
+```
 
-// Add files to the pack
-await tarTools.addFileToPack(pack, {
-  fileName: 'hello.txt',
-  content: 'Hello, World!'
-});
+### Two Operating Modes
 
-await tarTools.addFileToPack(pack, {
-  fileName: 'data.json',
-  content: Buffer.from(JSON.stringify({ foo: 'bar' }))
-});
+**Extraction Mode** - Load an existing archive and extract/analyze it:
+```typescript
+SmartArchive.create()
+  .url('...')        // or .file(), .stream(), .buffer()
+  .extract('./out')  // or .toSmartFiles(), .list(), etc.
+```
 
-// Finalize and pipe to destination
-pack.finalize();
-pack.pipe(createWriteStream('./output.tar'));
+**Creation Mode** - Build a new archive from entries:
+```typescript
+SmartArchive.create()
+  .format('tar.gz')  // Set output format
+  .entry(...)        // Add files
+  .toFile('./out.tar.gz')  // or .toBuffer(), .toStream()
 ```
 
-### Pack a directory into TAR
+> ⚠️ **Note:** You cannot mix extraction and creation methods in the same chain.
 
-```typescript
-import { TarTools } from '@push.rocks/smartarchive';
-import { createWriteStream } from 'fs';
+## API Reference 📚
 
-const tarTools = new TarTools();
+### Source Methods (Extraction Mode)
+
+| Method | Description |
+|--------|-------------|
+| `.url(url)` | Load archive from a URL |
+| `.file(path)` | Load archive from local filesystem |
+| `.stream(readable)` | Load archive from any Node.js readable stream |
+| `.buffer(buffer)` | Load archive from an in-memory Buffer |
+
+### Creation Methods (Creation Mode)
+
+| Method | Description |
+|--------|-------------|
+| `.format(fmt)` | Set output format: `'tar'`, `'tar.gz'`, `'tgz'`, `'zip'`, `'gz'` |
+| `.compression(level)` | Set compression level (0-9, default: 6) |
+| `.entry(path, content)` | Add a file entry (string or Buffer content) |
+| `.entries(array)` | Add multiple entries at once |
+| `.directory(path, archiveBase?)` | Add entire directory contents |
+| `.addSmartFile(file, path?)` | Add a SmartFile instance |
+| `.addStreamFile(file, path?)` | Add a StreamFile instance |
+
+### Filter Methods (Both Modes)
+
+| Method | Description |
+|--------|-------------|
+| `.filter(predicate)` | Filter entries with custom function |
+| `.include(pattern)` | Only include entries matching regex/string pattern |
+| `.exclude(pattern)` | Exclude entries matching regex/string pattern |
+
+### Extraction Options
+
+| Method | Description |
+|--------|-------------|
+| `.stripComponents(n)` | Strip N leading path components |
+| `.overwrite(bool)` | Overwrite existing files (default: false) |
+| `.fileName(name)` | Set output filename for single-file archives (gz, bz2) |
+
+### Terminal Methods (Extraction)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.extract(targetDir)` | `Promise<void>` | Extract to filesystem directory |
+| `.toStreamFiles()` | `Promise<StreamIntake<StreamFile>>` | Get stream of StreamFile objects |
+| `.toSmartFiles()` | `Promise<SmartFile[]>` | Get in-memory SmartFile array |
+| `.extractFile(path)` | `Promise<SmartFile \| null>` | Extract single file by path |
+| `.list()` | `Promise<IArchiveEntryInfo[]>` | List all entries |
+| `.analyze()` | `Promise<IArchiveInfo>` | Get archive metadata |
+| `.hasFile(path)` | `Promise<boolean>` | Check if file exists |
+
+### Terminal Methods (Creation)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.build()` | `Promise<SmartArchive>` | Build the archive (implicit in other terminals) |
+| `.toBuffer()` | `Promise<Buffer>` | Get archive as Buffer |
+| `.toFile(path)` | `Promise<void>` | Write archive to disk |
+| `.toStream()` | `Promise<Readable>` | Get raw archive stream |
 
-// Pack an entire directory
-const pack = await tarTools.packDirectory('./src');
-pack.finalize();
-pack.pipe(createWriteStream('./source.tar'));
-```
+## Usage Examples 🔨
 
-### Extracting from URLs
+### Download and extract npm packages
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
 
-// Download and extract npm packages
-const npmPackage = await SmartArchive.fromArchiveUrl(
-  'https://registry.npmjs.org/@push.rocks/smartfile/-/smartfile-11.2.7.tgz'
-);
-await npmPackage.exportToFs('./node_modules/@push.rocks/smartfile');
+const pkg = await SmartArchive.create()
+  .url('https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz');
 
-// Or process as stream for memory efficiency
-const stream = await npmPackage.exportToStreamOfStreamFiles();
-stream.on('data', async (file) => {
-  console.log(`Extracted: ${file.relativeFilePath}`);
-});
+// Quick inspection of package.json
+const pkgJson = await pkg.extractFile('package/package.json');
+if (pkgJson) {
+  const metadata = JSON.parse(pkgJson.contents.toString());
+  console.log(`Package: ${metadata.name}@${metadata.version}`);
+}
+
+// Full extraction with path normalization
+await SmartArchive.create()
+  .url('https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz')
+  .stripComponents(1)
+  .extract('./node_modules/lodash');
 ```
 
-### Working with GZIP files
+### Create ZIP archive
 
 ```typescript
-import { SmartArchive, GzipTools } from '@push.rocks/smartarchive';
-import { createReadStream, createWriteStream } from 'fs';
-
-// Decompress a .gz file - provide filename since gzip doesn't store it
-const gzipArchive = await SmartArchive.fromArchiveFile('./data.json.gz');
-await gzipArchive.exportToFs('./decompressed', 'data.json');
-
-// Use GzipTools directly for streaming decompression
-const gzipTools = new GzipTools();
-const decompressStream = gzipTools.getDecompressionStream();
+import { SmartArchive } from '@push.rocks/smartarchive';
 
-createReadStream('./compressed.gz')
-  .pipe(decompressStream)
-  .pipe(createWriteStream('./decompressed.txt'));
+await SmartArchive.create()
+  .format('zip')
+  .compression(9)
+  .entry('report.txt', 'Monthly sales report...')
+  .entry('data/figures.json', JSON.stringify({ revenue: 10000 }))
+  .entry('images/logo.png', pngBuffer)
+  .toFile('./report-bundle.zip');
 ```
 
-### Working with BZIP2 files
+### Create TAR.GZ from directory
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
 
-// Handle .bz2 files
-const bzipArchive = await SmartArchive.fromArchiveUrl(
-  'https://example.com/data.bz2'
-);
-await bzipArchive.exportToFs('./extracted', 'data.txt');
+await SmartArchive.create()
+  .format('tar.gz')
+  .compression(9)
+  .directory('./src', 'source')  // Archive ./src as 'source/' in archive
+  .toFile('./project-backup.tar.gz');
 ```
 
-### In-memory processing (no filesystem)
+### Stream-based extraction
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
-import { Readable } from 'stream';
-
-// Process archives entirely in memory
-const compressedBuffer = await fetchCompressedData();
-const memoryStream = Readable.from(compressedBuffer);
 
-const archive = await SmartArchive.fromArchiveStream(memoryStream);
-const streamFiles = await archive.exportToStreamOfStreamFiles();
+const fileStream = await SmartArchive.create()
+  .file('./large-archive.tar.gz')
+  .toStreamFiles();
 
-const extractedFiles: Array<{ name: string; content: Buffer }> = [];
-
-streamFiles.on('data', async (streamFile) => {
-  const chunks: Buffer[] = [];
-  const readStream = await streamFile.createReadStream();
+fileStream.on('data', async (streamFile) => {
+  console.log(`Processing: ${streamFile.relativeFilePath}`);
 
-  for await (const chunk of readStream) {
-    chunks.push(chunk);
+  if (streamFile.relativeFilePath.endsWith('.json')) {
+    const content = await streamFile.getContentAsBuffer();
+    const data = JSON.parse(content.toString());
+    // Process JSON data...
   }
-
-  extractedFiles.push({
-    name: streamFile.relativeFilePath,
-    content: Buffer.concat(chunks)
-  });
 });
 
-await new Promise((resolve) => streamFiles.on('end', resolve));
-console.log(`Extracted ${extractedFiles.length} files in memory`);
+fileStream.on('end', () => {
+  console.log('Extraction complete');
+});
 ```
 
-### Nested archive handling (e.g., .tar.gz)
-
-The library automatically handles nested compression. A `.tar.gz` file is:
-1. First decompressed from gzip
-2. Then unpacked from tar
-
-This happens transparently:
+### Filter specific file types
 
 ```typescript
 import { SmartArchive } from '@push.rocks/smartarchive';
 
-// Automatically handles gzip → tar extraction chain
-const tgzArchive = await SmartArchive.fromArchiveFile('./package.tar.gz');
-await tgzArchive.exportToFs('./extracted');
-```
+// Extract only TypeScript files
+const tsFiles = await SmartArchive.create()
+  .url('https://example.com/project.tar.gz')
+  .include(/\.ts$/)
+  .exclude(/node_modules/)
+  .toSmartFiles();
 
-## API Reference 📚
+for (const file of tsFiles) {
+  console.log(`${file.relative}: ${file.contents.length} bytes`);
+}
+```
 
-### SmartArchive Class
+### Analyze archive without extraction
 
-The main entry point for archive operations.
+```typescript
+import { SmartArchive } from '@push.rocks/smartarchive';
 
-#### Static Factory Methods
+const archive = SmartArchive.create()
+  .file('./unknown-archive.tar.gz');
 
-```typescript
-// Create from URL - downloads and processes archive
-SmartArchive.fromArchiveUrl(url: string): Promise<SmartArchive>
+// Get format info
+const info = await archive.analyze();
+console.log(`Format: ${info.format}`);
+console.log(`Compressed: ${info.isCompressed}`);
 
-// Create from local file path
-SmartArchive.fromArchiveFile(path: string): Promise<SmartArchive>
+// List contents
+const entries = await archive.list();
+for (const entry of entries) {
+  console.log(`${entry.path} (${entry.isDirectory ? 'dir' : 'file'})`);
+}
 
-// Create from any Node.js readable stream
-SmartArchive.fromArchiveStream(stream: Readable | Duplex | Transform): Promise<SmartArchive>
+// Check for specific file
+if (await archive.hasFile('package.json')) {
+  const pkgFile = await archive.extractFile('package.json');
+  console.log(pkgFile?.contents.toString());
+}
 ```
 
-#### Instance Methods
+### Working with GZIP files
 
 ```typescript
-// Extract all files to a directory
-// fileName is optional - used for single-file archives (like .gz) that don't store filename
-exportToFs(targetDir: string, fileName?: string): Promise<void>
+import { SmartArchive, GzipTools } from '@push.rocks/smartarchive';
 
-// Get a stream that emits StreamFile objects for each file in the archive
-exportToStreamOfStreamFiles(): Promise<StreamIntake<StreamFile>>
+// Decompress a .gz file
+await SmartArchive.create()
+  .file('./data.json.gz')
+  .fileName('data.json')  // Specify output name (gzip doesn't store filename)
+  .extract('./decompressed');
 
-// Get the raw archive stream (useful for piping)
-getArchiveStream(): Promise<Readable>
-```
+// Use GzipTools directly for compression/decompression
+const gzipTools = new GzipTools();
 
-#### Instance Properties
+// Compress a buffer
+const compressed = await gzipTools.compress(Buffer.from('Hello World'), 9);
+const decompressed = await gzipTools.decompress(compressed);
 
-```typescript
-archive.tarTools      // TarTools instance for TAR-specific operations
-archive.zipTools      // ZipTools instance for ZIP-specific operations
-archive.gzipTools     // GzipTools instance for GZIP-specific operations
-archive.bzip2Tools    // Bzip2Tools instance for BZIP2-specific operations
-archive.archiveAnalyzer // ArchiveAnalyzer for inspecting archive type
-```
+// Synchronous operations
+const compressedSync = gzipTools.compressSync(inputBuffer, 6);
+const decompressedSync = gzipTools.decompressSync(compressedSync);
 
-### TarTools Class
+// Streaming
+const compressStream = gzipTools.getCompressionStream(6);
+const decompressStream = gzipTools.getDecompressionStream();
 
-TAR-specific operations for creating and extracting TAR archives.
+createReadStream('./input.txt')
+  .pipe(compressStream)
+  .pipe(createWriteStream('./output.gz'));
+```
+
+### Working with TAR archives directly
 
 ```typescript
 import { TarTools } from '@push.rocks/smartarchive';
 
 const tarTools = new TarTools();
 
-// Get a tar pack stream for creating archives
+// Create a TAR archive manually
 const pack = await tarTools.getPackStream();
 
-// Add files to a pack stream
 await tarTools.addFileToPack(pack, {
-  fileName: 'file.txt',          // Name in archive
-  content: 'Hello World',        // String, Buffer, Readable, SmartFile, or StreamFile
-  byteLength?: number,           // Optional: specify size for streams
-  filePath?: string              // Optional: path to file on disk
+  fileName: 'hello.txt',
+  content: 'Hello, World!'
+});
+
+await tarTools.addFileToPack(pack, {
+  fileName: 'data.json',
+  content: Buffer.from(JSON.stringify({ foo: 'bar' }))
 });
 
-// Pack an entire directory
-const pack = await tarTools.packDirectory('./src');
+pack.finalize();
+pack.pipe(createWriteStream('./output.tar'));
 
-// Get extraction stream
-const extract = tarTools.getDecompressionStream();
-```
+// Pack a directory to TAR.GZ buffer
+const tgzBuffer = await tarTools.packDirectoryToTarGz('./src', 6);
 
-### ZipTools Class
+// Pack a directory to TAR.GZ stream
+const tgzStream = await tarTools.packDirectoryToTarGzStream('./src');
+```
 
-ZIP-specific operations.
+### Working with ZIP archives directly
 
 ```typescript
 import { ZipTools } from '@push.rocks/smartarchive';
 
 const zipTools = new ZipTools();
 
-// Get compression stream (for creating ZIP)
-const compressor = zipTools.getCompressionStream();
+// Create a ZIP archive from entries
+const zipBuffer = await zipTools.createZip([
+  { archivePath: 'readme.txt', content: 'Hello!' },
+  { archivePath: 'data.bin', content: Buffer.from([0x00, 0x01, 0x02]) }
+], 6);
 
-// Get decompression stream (for extracting ZIP)
-const decompressor = zipTools.getDecompressionStream();
+// Extract a ZIP buffer
+const entries = await zipTools.extractZip(zipBuffer);
+for (const entry of entries) {
+  console.log(`${entry.path}: ${entry.content.length} bytes`);
+}
 ```
 
-### GzipTools Class
-
-GZIP compression/decompression streams.
+### In-memory round-trip
 
 ```typescript
-import { GzipTools } from '@push.rocks/smartarchive';
-
-const gzipTools = new GzipTools();
-
-// Get compression stream
-const compressor = gzipTools.getCompressionStream();
-
-// Get decompression stream
-const decompressor = gzipTools.getDecompressionStream();
-```
-
-## Supported Formats 📋
-
-| Format | Extension(s) | Extract | Create |
-|--------|--------------|---------|--------|
-| TAR | `.tar` | ✅ | ✅ |
-| TAR.GZ / TGZ | `.tar.gz`, `.tgz` | ✅ | ⚠️ |
-| ZIP | `.zip` | ✅ | ⚠️ |
-| GZIP | `.gz` | ✅ | ✅ |
-| BZIP2 | `.bz2` | ✅ | ❌ |
-
-✅ Full support | ⚠️ Partial/basic support | ❌ Not supported
-
-## Performance Tips 🏎️
+import { SmartArchive } from '@push.rocks/smartarchive';
 
-1. **Use streaming for large files** – Avoid loading entire archives into memory with `exportToStreamOfStreamFiles()`
-2. **Provide byte lengths when known** – When adding streams to TAR, provide `byteLength` for better performance
-3. **Process files as they stream** – Don't collect all files into an array unless necessary
-4. **Choose the right format** – TAR.GZ for Unix/compression, ZIP for cross-platform compatibility
+// Create archive in memory
+const archive = await SmartArchive.create()
+  .format('tar.gz')
+  .entry('config.json', JSON.stringify({ version: '1.0.0' }))
+  .build();
 
-## Error Handling 🛡️
+const buffer = await archive.toBuffer();
 
-```typescript
-import { SmartArchive } from '@push.rocks/smartarchive';
+// Extract from buffer
+const files = await SmartArchive.create()
+  .buffer(buffer)
+  .toSmartFiles();
 
-try {
-  const archive = await SmartArchive.fromArchiveUrl('https://example.com/file.zip');
-  await archive.exportToFs('./output');
-} catch (error) {
-  if (error.code === 'ENOENT') {
-    console.error('Archive file not found');
-  } else if (error.code === 'EACCES') {
-    console.error('Permission denied');
-  } else if (error.message.includes('fetch')) {
-    console.error('Network error downloading archive');
-  } else {
-    console.error('Archive extraction failed:', error.message);
-  }
+for (const file of files) {
+  console.log(`${file.relative}: ${file.contents.toString()}`);
 }
 ```
 
@@ -395,51 +389,139 @@ try {
 ### CI/CD: Download & Extract Build Artifacts
 
 ```typescript
-const artifacts = await SmartArchive.fromArchiveUrl(
-  `${CI_SERVER}/artifacts/build-${BUILD_ID}.zip`
-);
-await artifacts.exportToFs('./dist');
+const artifacts = await SmartArchive.create()
+  .url(`${CI_SERVER}/artifacts/build-${BUILD_ID}.zip`)
+  .stripComponents(1)
+  .extract('./dist');
 ```
 
-### Backup System: Restore from Archive
+### Backup System
 
 ```typescript
-const backup = await SmartArchive.fromArchiveFile('./backup-2024.tar.gz');
-await backup.exportToFs('/restore/location');
+// Create backup
+await SmartArchive.create()
+  .format('tar.gz')
+  .compression(9)
+  .directory('./data')
+  .toFile(`./backups/backup-${Date.now()}.tar.gz`);
+
+// Restore backup
+await SmartArchive.create()
+  .file('./backups/backup-latest.tar.gz')
+  .extract('/restore/location');
 ```
 
-### NPM Package Inspection
+### Bundle files for HTTP download
 
 ```typescript
-const pkg = await SmartArchive.fromArchiveUrl(
-  'https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz'
-);
-const files = await pkg.exportToStreamOfStreamFiles();
-
-files.on('data', async (file) => {
-  if (file.relativeFilePath.includes('package.json')) {
-    const stream = await file.createReadStream();
-    // Read and analyze package.json
-  }
+import { SmartArchive } from '@push.rocks/smartarchive';
+
+// Express/Fastify handler
+app.get('/download-bundle', async (req, res) => {
+  const buffer = await SmartArchive.create()
+    .format('zip')
+    .entry('report.pdf', pdfBuffer)
+    .entry('data.xlsx', excelBuffer)
+    .entry('images/chart.png', chartBuffer)
+    .toBuffer();
+
+  res.setHeader('Content-Type', 'application/zip');
+  res.setHeader('Content-Disposition', 'attachment; filename=report-bundle.zip');
+  res.send(buffer);
 });
 ```
 
 ### Data Pipeline: Process Compressed Datasets
 
 ```typescript
-const dataset = await SmartArchive.fromArchiveUrl(
-  'https://data.source/dataset.tar.gz'
-);
+const fileStream = await SmartArchive.create()
+  .url('https://data.source/dataset.tar.gz')
+  .toStreamFiles();
 
-const files = await dataset.exportToStreamOfStreamFiles();
-files.on('data', async (file) => {
+fileStream.on('data', async (file) => {
   if (file.relativeFilePath.endsWith('.csv')) {
-    const stream = await file.createReadStream();
-    // Stream CSV processing
+    const content = await file.getContentAsBuffer();
+    // Stream CSV processing...
   }
 });
 ```
 
+## Supported Formats 📋
+
+| Format | Extension(s) | Extract | Create |
+|--------|--------------|---------|--------|
+| TAR | `.tar` | ✅ | ✅ |
+| TAR.GZ / TGZ | `.tar.gz`, `.tgz` | ✅ | ✅ |
+| ZIP | `.zip` | ✅ | ✅ |
+| GZIP | `.gz` | ✅ | ✅ |
+| BZIP2 | `.bz2` | ✅ | ❌ |
+
+## Type Definitions
+
+```typescript
+// Supported archive formats
+type TArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip' | 'gz' | 'bz2';
+
+// Compression level (0 = none, 9 = maximum)
+type TCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+// Entry for creating archives
+interface IArchiveEntry {
+  archivePath: string;
+  content: string | Buffer | Readable | SmartFile | StreamFile;
+  size?: number;
+  mode?: number;
+  mtime?: Date;
+}
+
+// Information about an archive entry
+interface IArchiveEntryInfo {
+  path: string;
+  size: number;
+  isDirectory: boolean;
+  isFile: boolean;
+  mtime?: Date;
+  mode?: number;
+}
+
+// Archive analysis result
+interface IArchiveInfo {
+  format: TArchiveFormat | null;
+  isCompressed: boolean;
+  isArchive: boolean;
+  entries?: IArchiveEntryInfo[];
+}
+```
+
+## Performance Tips 🏎️
+
+1. **Use streaming for large files** – `.toStreamFiles()` processes entries one at a time without loading the entire archive
+2. **Provide byte lengths when known** – When using TarTools directly, provide `byteLength` for better performance
+3. **Choose appropriate compression** – Use 1-3 for speed, 6 (default) for balance, 9 for maximum compression
+4. **Filter early** – Use `.include()`/`.exclude()` to skip unwanted entries before processing
+
+## Error Handling 🛡️
+
+```typescript
+import { SmartArchive } from '@push.rocks/smartarchive';
+
+try {
+  await SmartArchive.create()
+    .url('https://example.com/file.zip')
+    .extract('./output');
+} catch (error) {
+  if (error.message.includes('No source configured')) {
+    console.error('Forgot to specify source');
+  } else if (error.message.includes('No format specified')) {
+    console.error('Forgot to set format for creation');
+  } else if (error.message.includes('extraction mode')) {
+    console.error('Cannot mix extraction and creation methods');
+  } else {
+    console.error('Archive operation failed:', error.message);
+  }
+}
+```
+
 ## License and Legal Information
 
 This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
@@ -450,6 +532,10 @@ This repository contains open-source code that is licensed under the MIT License
 
 This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
 
+### Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 ### Company Information
 
 Task Venture Capital GmbH