fix(ziptools,gziptools): Use fflate synchronous APIs for ZIP and GZIP operations for Deno compatibility; add TEntryFilter type and small docs/tests cleanup

readme.hints.md

@@ -1,38 +1,84 @@
 # Smartarchive Development Hints
 
-## Dependency Upgrades (2025-01-25)
+## Architecture Overview
 
-### Completed Upgrades
-- **@git.zone/tsbuild**: ^2.6.6 → ^3.1.0
-- **@git.zone/tsrun**: ^1.3.3 → ^2.0.0
-- **@git.zone/tstest**: ^2.3.4 → ^3.1.3
-- **@push.rocks/smartfile**: ^11.2.7 → ^13.0.0
+`@push.rocks/smartarchive` uses a **fluent builder pattern** for all archive operations. The main entry point is `SmartArchive.create()` which returns a builder instance.
 
-### Migration Notes
+### Two Operating Modes
 
-#### Smartfile v13 Migration
-Smartfile v13 removed filesystem operations (`fs`, `memory`, `fsStream` namespaces). These were replaced with Node.js native `fs` and `fs/promises`:
+1. **Extraction Mode** - Triggered by `.url()`, `.file()`, `.stream()`, or `.buffer()`
+2. **Creation Mode** - Triggered by `.format()` or `.entry()`
 
-**Replacements made:**
+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)`
-- `smartfile.fs.toStringSync(path)` → `fsPromises.readFile(path, 'utf8')`
-- `smartfile.fs.listFileTree(dir, pattern)` → custom `listFileTree()` helper
-- `smartfile.fsStream.createReadStream(path)` → `fs.createReadStream(path)`
-- `smartfile.fsStream.createWriteStream(path)` → `fs.createWriteStream(path)`
-- `smartfile.memory.toFs(content, path)` → `fsPromises.writeFile(path, content)`
 
-**Still using from smartfile v13:**
+### Still using from smartfile
 - `SmartFile` class (in-memory file representation)
 - `StreamFile` class (streaming file handling)
 
-### Removed Dependencies
-- `through@2.3.8` - was unused in the codebase
+## Testing
 
-## Architecture Notes
+```bash
+pnpm test              # Run all tests
+tstest test/test.node+deno.ts --verbose  # Run specific test
+```
 
-- Uses `fflate` for ZIP/GZIP compression (pure JS, works in browser)
-- Uses `tar-stream` for TAR archive handling
-- Uses `file-type` for MIME type detection
-- Custom BZIP2 implementation in `ts/bzip2/` directory
+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