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

Extraction Mode - Triggered by .url(), .file(), .stream(), or .buffer()
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)

// Old static factory methods - NO LONGER EXIST
await SmartArchive.fromUrl(url);
await SmartArchive.fromFile(path);
await SmartArchive.fromDirectory(path, options);

New Fluent API

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

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

2.6 KiB Raw Blame History