smartarchive/readme.hints.md

# 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