85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# Smartarchive Development Hints
|
|
|
|
## Architecture Overview
|
|
|
|
`@push.rocks/smartarchive` uses a **fluent builder pattern** for all archive operations. The main entry point is `SmartArchive.create()` which returns a builder instance.
|
|
|
|
### Two Operating Modes
|
|
|
|
1. **Extraction Mode** - Triggered by `.url()`, `.file()`, `.stream()`, or `.buffer()`
|
|
2. **Creation Mode** - Triggered by `.format()` or `.entry()`
|
|
|
|
Modes are mutually exclusive - you cannot mix extraction and creation methods in the same chain.
|
|
|
|
## Key Classes
|
|
|
|
- **SmartArchive** - Main class with fluent API for all operations
|
|
- **TarTools** - TAR-specific operations (pack/extract)
|
|
- **ZipTools** - ZIP-specific operations using fflate
|
|
- **GzipTools** - GZIP compression/decompression using fflate
|
|
- **Bzip2Tools** - BZIP2 decompression (extract only, no creation)
|
|
- **ArchiveAnalyzer** - Format detection via magic bytes
|
|
|
|
## Dependencies
|
|
|
|
- **fflate** - Pure JS compression for ZIP/GZIP (works in browser)
|
|
- **tar-stream** - TAR archive handling
|
|
- **file-type** - MIME type detection via magic bytes
|
|
- **@push.rocks/smartfile** - SmartFile and StreamFile classes
|
|
|
|
## API Changes (v5.0.0)
|
|
|
|
The v5.0.0 release introduced a complete API refactor:
|
|
|
|
### Old API (deprecated)
|
|
```typescript
|
|
// Old static factory methods - NO LONGER EXIST
|
|
await SmartArchive.fromUrl(url);
|
|
await SmartArchive.fromFile(path);
|
|
await SmartArchive.fromDirectory(path, options);
|
|
```
|
|
|
|
### New Fluent API
|
|
```typescript
|
|
// Current fluent builder pattern
|
|
await SmartArchive.create()
|
|
.url(url)
|
|
.extract(targetDir);
|
|
|
|
await SmartArchive.create()
|
|
.format('tar.gz')
|
|
.directory(path)
|
|
.toFile(outputPath);
|
|
```
|
|
|
|
## Migration Notes (from v4.x)
|
|
|
|
### Smartfile v13 Changes
|
|
Smartfile v13 removed filesystem operations. Replacements:
|
|
- `smartfile.fs.ensureDir(path)` → `fsPromises.mkdir(path, { recursive: true })`
|
|
- `smartfile.fs.stat(path)` → `fsPromises.stat(path)`
|
|
- `smartfile.fs.toReadStream(path)` → `fs.createReadStream(path)`
|
|
|
|
### Still using from smartfile
|
|
- `SmartFile` class (in-memory file representation)
|
|
- `StreamFile` class (streaming file handling)
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
pnpm test # Run all tests
|
|
tstest test/test.node+deno.ts --verbose # Run specific test
|
|
```
|
|
|
|
Tests use a Verdaccio registry URL (`verdaccio.lossless.digital`) for test archives.
|
|
|
|
## Key Files
|
|
|
|
- `ts/classes.smartarchive.ts` - Main SmartArchive class with fluent API
|
|
- `ts/classes.tartools.ts` - TAR operations
|
|
- `ts/classes.ziptools.ts` - ZIP operations
|
|
- `ts/classes.gziptools.ts` - GZIP operations
|
|
- `ts/classes.bzip2tools.ts` - BZIP2 decompression
|
|
- `ts/classes.archiveanalyzer.ts` - Format detection
|
|
- `ts/interfaces.ts` - Type definitions
|