@push.rocks/smartarchive 4.2.4 → 5.0.1

package/dist_ts/index.js

@@ -1,5 +1,13 @@
+// Core types and errors
+export * from './interfaces.js';
+export * from './errors.js';
+// Main archive class
 export * from './classes.smartarchive.js';
+// Format-specific tools
 export * from './classes.tartools.js';
 export * from './classes.ziptools.js';
 export * from './classes.gziptools.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHdCQUF3QixDQUFDIn0=
+export * from './classes.bzip2tools.js';
+// Archive analysis
+export * from './classes.archiveanalyzer.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSx3QkFBd0I7QUFDeEIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGFBQWEsQ0FBQztBQUU1QixxQkFBcUI7QUFDckIsY0FBYywyQkFBMkIsQ0FBQztBQUUxQyx3QkFBd0I7QUFDeEIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyx5QkFBeUIsQ0FBQztBQUV4QyxtQkFBbUI7QUFDbkIsY0FBYyw4QkFBOEIsQ0FBQyJ9

package/dist_ts/interfaces.d.ts

@@ -0,0 +1,119 @@
+import type * as stream from 'node:stream';
+import type { SmartFile, StreamFile } from '@push.rocks/smartfile';
+/**
+ * Supported archive formats
+ */
+export type TArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip' | 'gz' | 'bz2';
+/**
+ * Compression level (0 = no compression, 9 = maximum compression)
+ */
+export type TCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * Supported MIME types for archive detection
+ */
+export type TSupportedMime = 'application/gzip' | 'application/zip' | 'application/x-bzip2' | 'application/x-tar' | undefined;
+/**
+ * Entry to add to an archive during creation
+ */
+export interface IArchiveEntry {
+    /** Path within the archive */
+    archivePath: string;
+    /** Content: string, Buffer, Readable stream, SmartFile, or StreamFile */
+    content: string | Buffer | stream.Readable | SmartFile | StreamFile;
+    /** Optional size hint for streams (improves performance) */
+    size?: number;
+    /** Optional file mode/permissions */
+    mode?: number;
+    /** Optional modification time */
+    mtime?: Date;
+}
+/**
+ * Options for creating archives
+ */
+export interface IArchiveCreationOptions {
+    /** Target archive format */
+    format: TArchiveFormat;
+    /** Compression level (0-9, default depends on format) */
+    compressionLevel?: TCompressionLevel;
+    /** Base path to strip from file paths in archive */
+    basePath?: string;
+}
+/**
+ * Options for extracting archives
+ */
+export interface IArchiveExtractionOptions {
+    /** Target directory for extraction */
+    targetDir: string;
+    /** Optional filename for single-file archives (gz, bz2) */
+    fileName?: string;
+    /** Number of leading path components to strip */
+    stripComponents?: number;
+    /** Filter function to select which entries to extract */
+    filter?: (entry: IArchiveEntryInfo) => boolean;
+    /** Whether to overwrite existing files */
+    overwrite?: boolean;
+}
+/**
+ * Information about an archive entry
+ */
+export interface IArchiveEntryInfo {
+    /** Path of the entry within the archive */
+    path: string;
+    /** Size in bytes */
+    size: number;
+    /** Whether this entry is a directory */
+    isDirectory: boolean;
+    /** Whether this entry is a file */
+    isFile: boolean;
+    /** Modification time */
+    mtime?: Date;
+    /** File mode/permissions */
+    mode?: number;
+}
+/**
+ * Result of archive analysis
+ */
+export interface IArchiveInfo {
+    /** Detected archive format */
+    format: TArchiveFormat | null;
+    /** Whether the archive is compressed */
+    isCompressed: boolean;
+    /** Whether this is a recognized archive format */
+    isArchive: boolean;
+    /** List of entries (if available without full extraction) */
+    entries?: IArchiveEntryInfo[];
+}
+/**
+ * Options for adding a file to a TAR pack stream
+ */
+export interface IAddFileOptions {
+    /** Filename within the archive */
+    fileName?: string;
+    /** File content */
+    content?: string | Buffer | stream.Readable | SmartFile | StreamFile;
+    /** Size in bytes (required for streams) */
+    byteLength?: number;
+    /** Path to file on disk (alternative to content) */
+    filePath?: string;
+}
+/**
+ * Bit reader interface for BZIP2 decompression
+ */
+export interface IBitReader {
+    (n: number | null): number | void;
+    bytesRead: number;
+}
+/**
+ * Huffman group for BZIP2 decompression
+ */
+export interface IHuffmanGroup {
+    permute: Int32Array;
+    limit: Int32Array;
+    base: Int32Array;
+    minLen: number;
+    maxLen: number;
+}
+/**
+ * Entry filter predicate for fluent API
+ */
+export type TEntryFilter = (entry: IArchiveEntryInfo) => boolean;

package/dist_ts/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVyZmFjZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartarchive",
-  "version": "4.2.4",
+  "version": "5.0.1",
   "description": "A library for working with archive files, providing utilities for compressing and decompressing data.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",

package/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
+
+```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.
 
-## Architecture Notes
+## Key Files
 
-- 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
+- `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