@push.rocks/smartarchive 4.2.4 → 5.0.1

package/dist_ts/classes.smartarchive.d.ts

@@ -1,32 +1,214 @@
 import * as plugins from './plugins.js';
+import type { IArchiveEntryInfo, IArchiveInfo, TArchiveFormat, TCompressionLevel, TEntryFilter } from './interfaces.js';
 import { Bzip2Tools } from './classes.bzip2tools.js';
 import { GzipTools } from './classes.gziptools.js';
 import { TarTools } from './classes.tartools.js';
 import { ZipTools } from './classes.ziptools.js';
 import { ArchiveAnalyzer } from './classes.archiveanalyzer.js';
+/**
+ * Main class for archive manipulation with fluent API
+ * Supports TAR, ZIP, GZIP, and BZIP2 formats
+ *
+ * @example Extraction from URL
+ * ```typescript
+ * await SmartArchive.create()
+ *   .url('https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz')
+ *   .stripComponents(1)
+ *   .extract('./node_modules/lodash');
+ * ```
+ *
+ * @example Creation with thenable
+ * ```typescript
+ * const archive = await SmartArchive.create()
+ *   .format('tar.gz')
+ *   .compression(9)
+ *   .entry('config.json', JSON.stringify(config))
+ *   .directory('./src');
+ * ```
+ */
 export declare class SmartArchive {
-    static fromArchiveUrl(urlArg: string): Promise<SmartArchive>;
-    static fromArchiveFile(filePathArg: string): Promise<SmartArchive>;
-    static fromArchiveStream(streamArg: plugins.stream.Readable | plugins.stream.Duplex | plugins.stream.Transform): Promise<SmartArchive>;
+    /**
+     * Create a new SmartArchive instance for fluent configuration
+     */
+    static create(): SmartArchive;
     tarTools: TarTools;
     zipTools: ZipTools;
     gzipTools: GzipTools;
     bzip2Tools: Bzip2Tools;
     archiveAnalyzer: ArchiveAnalyzer;
-    sourceUrl: string;
-    sourceFilePath: string;
-    sourceStream: plugins.stream.Readable | plugins.stream.Duplex | plugins.stream.Transform;
-    archiveName: string;
-    singleFileMode: boolean;
-    addedDirectories: string[];
-    addedFiles: (plugins.smartfile.SmartFile | plugins.smartfile.StreamFile)[];
-    addedUrls: string[];
+    private sourceUrl?;
+    private sourceFilePath?;
+    private sourceStream?;
+    private archiveBuffer?;
+    private creationFormat?;
+    private _compressionLevel;
+    private pendingEntries;
+    private pendingDirectories;
+    private _mode;
+    private _filters;
+    private _excludePatterns;
+    private _includePatterns;
+    private _stripComponents;
+    private _overwrite;
+    private _fileName?;
     constructor();
     /**
-     * gets the original archive stream
+     * Load archive from URL
+     */
+    url(urlArg: string): this;
+    /**
+     * Load archive from file path
+     */
+    file(pathArg: string): this;
+    /**
+     * Load archive from readable stream
+     */
+    stream(streamArg: plugins.stream.Readable | plugins.stream.Duplex | plugins.stream.Transform): this;
+    /**
+     * Load archive from buffer
+     */
+    buffer(bufferArg: Buffer): this;
+    /**
+     * Set output format for archive creation
+     */
+    format(fmt: TArchiveFormat): this;
+    /**
+     * Set compression level (0-9)
+     */
+    compression(level: TCompressionLevel): this;
+    /**
+     * Add a single file entry to the archive
+     */
+    entry(archivePath: string, content: string | Buffer): this;
+    /**
+     * Add multiple entries to the archive
+     */
+    entries(entriesArg: Array<{
+        archivePath: string;
+        content: string | Buffer;
+    }>): this;
+    /**
+     * Add an entire directory to the archive (queued, resolved at build time)
+     */
+    directory(sourcePath: string, archiveBase?: string): this;
+    /**
+     * Add a SmartFile to the archive
+     */
+    addSmartFile(fileArg: plugins.smartfile.SmartFile, archivePath?: string): this;
+    /**
+     * Add a StreamFile to the archive
+     */
+    addStreamFile(fileArg: plugins.smartfile.StreamFile, archivePath?: string): this;
+    /**
+     * Filter entries by predicate function
+     */
+    filter(predicate: TEntryFilter): this;
+    /**
+     * Include only entries matching the pattern
+     */
+    include(pattern: string | RegExp): this;
+    /**
+     * Exclude entries matching the pattern
+     */
+    exclude(pattern: string | RegExp): this;
+    /**
+     * Strip N leading path components from extracted files
+     */
+    stripComponents(n: number): this;
+    /**
+     * Overwrite existing files during extraction
+     */
+    overwrite(value?: boolean): this;
+    /**
+     * Set output filename for single-file archives (gz, bz2)
+     */
+    fileName(name: string): this;
+    /**
+     * Extract archive to filesystem directory
+     */
+    extract(targetDir: string): Promise<void>;
+    /**
+     * Extract archive to a stream of StreamFile objects
+     */
+    toStreamFiles(): Promise<plugins.smartstream.StreamIntake<plugins.smartfile.StreamFile>>;
+    /**
+     * Extract archive to an array of SmartFile objects (in-memory)
+     */
+    toSmartFiles(): Promise<plugins.smartfile.SmartFile[]>;
+    /**
+     * Extract a single file from the archive by path
+     */
+    extractFile(filePath: string): Promise<plugins.smartfile.SmartFile | null>;
+    /**
+     * Build and finalize the archive, returning this instance
+     */
+    build(): Promise<SmartArchive>;
+    /**
+     * Internal build implementation (avoids thenable recursion)
+     */
+    private doBuild;
+    /**
+     * Build archive and return as Buffer
+     */
+    toBuffer(): Promise<Buffer>;
+    /**
+     * Build archive and write to file
+     */
+    toFile(filePath: string): Promise<void>;
+    /**
+     * Get archive as a readable stream
+     */
+    toStream(): Promise<plugins.stream.Readable>;
+    /**
+     * Analyze the archive and return metadata
+     */
+    analyze(): Promise<IArchiveInfo>;
+    /**
+     * List all entries in the archive
+     */
+    list(): Promise<IArchiveEntryInfo[]>;
+    /**
+     * Check if a specific file exists in the archive
+     */
+    hasFile(filePath: string): Promise<boolean>;
+    /**
+     * Ensure we're not in create mode when calling extraction methods
+     */
+    private ensureNotInCreateMode;
+    /**
+     * Ensure we're not in extract mode when calling creation methods
+     */
+    private ensureNotInExtractMode;
+    /**
+     * Ensure an extraction source is configured
+     */
+    private ensureExtractionSource;
+    /**
+     * Ensure a format is configured for creation
+     */
+    private ensureCreationFormat;
+    /**
+     * Get the source stream
+     */
+    private getSourceStream;
+    /**
+     * Build a combined filter function from all configured filters
+     */
+    private buildFilterFunction;
+    /**
+     * Resolve pending directories to entries
+     */
+    private resolveDirectories;
+    /**
+     * Get entries filtered by include/exclude patterns
+     */
+    private getFilteredEntries;
+    /**
+     * Convert a stream to buffer
+     */
+    private streamToBuffer;
+    /**
+     * Read first chunk from stream
      */
-    getArchiveStream(): Promise<plugins.stream.Readable>;
-    exportToTarGzStream(): Promise<void>;
-    exportToFs(targetDir: string, fileNameArg?: string): Promise<void>;
-    exportToStreamOfStreamFiles(): Promise<plugins.smartstream.StreamIntake<plugins.smartfile.StreamFile>>;
+    private readFirstChunk;
 }