@push.rocks/smartarchive 4.2.4 → 5.0.1

package/ts/classes.smartarchive.ts

@@ -1,238 +1,863 @@
 import * as plugins from './plugins.js';
-import * as paths from './paths.js';
+import type {
+  IArchiveEntry,
+  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, type IAnalyzedResult } from './classes.archiveanalyzer.js';
 
-import {
-  ArchiveAnalyzer,
-  type IAnalyzedResult,
-} from './classes.archiveanalyzer.js';
-
-import type { from } from '@push.rocks/smartrx/dist_ts/smartrx.plugins.rxjs.js';
+/**
+ * Pending directory entry for async resolution
+ */
+interface IPendingDirectory {
+  sourcePath: string;
+  archiveBase?: string;
+}
 
+/**
+ * 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 class SmartArchive {
-  // STATIC
-  public static async fromArchiveUrl(urlArg: string): Promise<SmartArchive> {
-    const smartArchiveInstance = new SmartArchive();
-    smartArchiveInstance.sourceUrl = urlArg;
-    return smartArchiveInstance;
-  }
+  // ============================================
+  // STATIC ENTRY POINT
+  // ============================================
 
-  public static async fromArchiveFile(
-    filePathArg: string,
-  ): Promise<SmartArchive> {
-    const smartArchiveInstance = new SmartArchive();
-    smartArchiveInstance.sourceFilePath = filePathArg;
-    return smartArchiveInstance;
+  /**
+   * Create a new SmartArchive instance for fluent configuration
+   */
+  public static create(): SmartArchive {
+    return new SmartArchive();
   }
 
-  public static async fromArchiveStream(
-    streamArg:
-      | plugins.stream.Readable
-      | plugins.stream.Duplex
-      | plugins.stream.Transform,
-  ): Promise<SmartArchive> {
-    const smartArchiveInstance = new SmartArchive();
-    smartArchiveInstance.sourceStream = streamArg;
-    return smartArchiveInstance;
-  }
+  // ============================================
+  // TOOLS (public for internal use)
+  // ============================================
 
-  // INSTANCE
   public tarTools = new TarTools();
   public zipTools = new ZipTools();
   public gzipTools = new GzipTools();
   public bzip2Tools = new Bzip2Tools(this);
   public archiveAnalyzer = new ArchiveAnalyzer(this);
 
-  public sourceUrl: string;
-  public sourceFilePath: string;
-  public sourceStream:
-    | plugins.stream.Readable
-    | plugins.stream.Duplex
-    | plugins.stream.Transform;
+  // ============================================
+  // SOURCE STATE (extraction mode)
+  // ============================================
+
+  private sourceUrl?: string;
+  private sourceFilePath?: string;
+  private sourceStream?: plugins.stream.Readable | plugins.stream.Duplex | plugins.stream.Transform;
+
+  // ============================================
+  // CREATION STATE
+  // ============================================
+
+  private archiveBuffer?: Buffer;
+  private creationFormat?: TArchiveFormat;
+  private _compressionLevel: TCompressionLevel = 6;
+  private pendingEntries: IArchiveEntry[] = [];
+  private pendingDirectories: IPendingDirectory[] = [];
 
-  public archiveName: string;
-  public singleFileMode: boolean = false;
+  // ============================================
+  // FLUENT STATE
+  // ============================================
 
-  public addedDirectories: string[] = [];
-  public addedFiles: (
-    | plugins.smartfile.SmartFile
-    | plugins.smartfile.StreamFile
-  )[] = [];
-  public addedUrls: string[] = [];
+  private _mode: 'extract' | 'create' | null = null;
+  private _filters: TEntryFilter[] = [];
+  private _excludePatterns: RegExp[] = [];
+  private _includePatterns: RegExp[] = [];
+  private _stripComponents: number = 0;
+  private _overwrite: boolean = false;
+  private _fileName?: string;
 
   constructor() {}
 
+  // ============================================
+  // SOURCE METHODS (set extraction mode)
+  // ============================================
+
   /**
-   * gets the original archive stream
+   * Load archive from URL
    */
-  public async getArchiveStream() {
-    if (this.sourceStream) {
-      return this.sourceStream;
-    }
-    if (this.sourceUrl) {
-      const response = await plugins.smartrequest.SmartRequest.create()
-        .url(this.sourceUrl)
-        .get();
-      const webStream = response.stream();
-      // @ts-ignore - Web stream to Node.js stream conversion
-      const urlStream = plugins.stream.Readable.fromWeb(webStream);
-      return urlStream;
-    }
-    if (this.sourceFilePath) {
-      const fileStream = plugins.fs.createReadStream(this.sourceFilePath);
-      return fileStream;
+  public url(urlArg: string): this {
+    this.ensureNotInCreateMode('url');
+    this._mode = 'extract';
+    this.sourceUrl = urlArg;
+    return this;
+  }
+
+  /**
+   * Load archive from file path
+   */
+  public file(pathArg: string): this {
+    this.ensureNotInCreateMode('file');
+    this._mode = 'extract';
+    this.sourceFilePath = pathArg;
+    return this;
+  }
+
+  /**
+   * Load archive from readable stream
+   */
+  public stream(streamArg: plugins.stream.Readable | plugins.stream.Duplex | plugins.stream.Transform): this {
+    this.ensureNotInCreateMode('stream');
+    this._mode = 'extract';
+    this.sourceStream = streamArg;
+    return this;
+  }
+
+  /**
+   * Load archive from buffer
+   */
+  public buffer(bufferArg: Buffer): this {
+    this.ensureNotInCreateMode('buffer');
+    this._mode = 'extract';
+    this.sourceStream = plugins.stream.Readable.from(bufferArg);
+    return this;
+  }
+
+  // ============================================
+  // FORMAT METHODS (set creation mode)
+  // ============================================
+
+  /**
+   * Set output format for archive creation
+   */
+  public format(fmt: TArchiveFormat): this {
+    this.ensureNotInExtractMode('format');
+    this._mode = 'create';
+    this.creationFormat = fmt;
+    return this;
+  }
+
+  /**
+   * Set compression level (0-9)
+   */
+  public compression(level: TCompressionLevel): this {
+    this._compressionLevel = level;
+    return this;
+  }
+
+  // ============================================
+  // CONTENT METHODS (creation mode)
+  // ============================================
+
+  /**
+   * Add a single file entry to the archive
+   */
+  public entry(archivePath: string, content: string | Buffer): this {
+    this.ensureNotInExtractMode('entry');
+    if (!this._mode) this._mode = 'create';
+    this.pendingEntries.push({ archivePath, content });
+    return this;
+  }
+
+  /**
+   * Add multiple entries to the archive
+   */
+  public entries(entriesArg: Array<{ archivePath: string; content: string | Buffer }>): this {
+    this.ensureNotInExtractMode('entries');
+    if (!this._mode) this._mode = 'create';
+    for (const e of entriesArg) {
+      this.pendingEntries.push({ archivePath: e.archivePath, content: e.content });
     }
+    return this;
+  }
+
+  /**
+   * Add an entire directory to the archive (queued, resolved at build time)
+   */
+  public directory(sourcePath: string, archiveBase?: string): this {
+    this.ensureNotInExtractMode('directory');
+    if (!this._mode) this._mode = 'create';
+    this.pendingDirectories.push({ sourcePath, archiveBase });
+    return this;
+  }
+
+  /**
+   * Add a SmartFile to the archive
+   */
+  public addSmartFile(fileArg: plugins.smartfile.SmartFile, archivePath?: string): this {
+    this.ensureNotInExtractMode('addSmartFile');
+    if (!this._mode) this._mode = 'create';
+    this.pendingEntries.push({
+      archivePath: archivePath || fileArg.relative,
+      content: fileArg,
+    });
+    return this;
+  }
+
+  /**
+   * Add a StreamFile to the archive
+   */
+  public addStreamFile(fileArg: plugins.smartfile.StreamFile, archivePath?: string): this {
+    this.ensureNotInExtractMode('addStreamFile');
+    if (!this._mode) this._mode = 'create';
+    this.pendingEntries.push({
+      archivePath: archivePath || fileArg.relativeFilePath,
+      content: fileArg,
+    });
+    return this;
+  }
+
+  // ============================================
+  // FILTER METHODS (both modes)
+  // ============================================
+
+  /**
+   * Filter entries by predicate function
+   */
+  public filter(predicate: TEntryFilter): this {
+    this._filters.push(predicate);
+    return this;
   }
 
-  public async exportToTarGzStream() {
-    const tarPackStream = await this.tarTools.getPackStream();
-    const gzipStream = await this.gzipTools.getCompressionStream();
-    // const archiveStream = tarPackStream.pipe(gzipStream);
-    // return archiveStream;
+  /**
+   * Include only entries matching the pattern
+   */
+  public include(pattern: string | RegExp): this {
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    this._includePatterns.push(regex);
+    return this;
+  }
+
+  /**
+   * Exclude entries matching the pattern
+   */
+  public exclude(pattern: string | RegExp): this {
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    this._excludePatterns.push(regex);
+    return this;
+  }
+
+  // ============================================
+  // EXTRACTION OPTIONS
+  // ============================================
+
+  /**
+   * Strip N leading path components from extracted files
+   */
+  public stripComponents(n: number): this {
+    this._stripComponents = n;
+    return this;
+  }
+
+  /**
+   * Overwrite existing files during extraction
+   */
+  public overwrite(value: boolean = true): this {
+    this._overwrite = value;
+    return this;
   }
 
-  public async exportToFs(
-    targetDir: string,
-    fileNameArg?: string,
-  ): Promise<void> {
+  /**
+   * Set output filename for single-file archives (gz, bz2)
+   */
+  public fileName(name: string): this {
+    this._fileName = name;
+    return this;
+  }
+
+  // ============================================
+  // TERMINAL METHODS - EXTRACTION
+  // ============================================
+
+  /**
+   * Extract archive to filesystem directory
+   */
+  public async extract(targetDir: string): Promise<void> {
+    this.ensureExtractionSource();
     const done = plugins.smartpromise.defer<void>();
-    const streamFileStream = await this.exportToStreamOfStreamFiles();
+    const streamFileStream = await this.toStreamFiles();
+
     streamFileStream.pipe(
       new plugins.smartstream.SmartDuplex({
         objectMode: true,
-        writeFunction: async (
-          streamFileArg: plugins.smartfile.StreamFile,
-          streamtools,
-        ) => {
-          const done = plugins.smartpromise.defer<void>();
-          console.log(
-            streamFileArg.relativeFilePath
-              ? streamFileArg.relativeFilePath
-              : 'no relative path',
-          );
+        writeFunction: async (streamFileArg: plugins.smartfile.StreamFile) => {
+          const innerDone = plugins.smartpromise.defer<void>();
           const streamFile = streamFileArg;
+          let relativePath = streamFile.relativeFilePath || this._fileName || 'extracted_file';
+
+          // Apply stripComponents
+          if (this._stripComponents > 0) {
+            const parts = relativePath.split('/');
+            relativePath = parts.slice(this._stripComponents).join('/');
+            if (!relativePath) {
+              innerDone.resolve();
+              return;
+            }
+          }
+
+          // Apply filter
+          const filterFn = this.buildFilterFunction();
+          if (filterFn) {
+            const entryInfo: IArchiveEntryInfo = {
+              path: relativePath,
+              size: 0,
+              isDirectory: false,
+              isFile: true,
+            };
+            if (!filterFn(entryInfo)) {
+              innerDone.resolve();
+              return;
+            }
+          }
+
           const readStream = await streamFile.createReadStream();
           await plugins.fsPromises.mkdir(targetDir, { recursive: true });
-          const writePath = plugins.path.join(
-            targetDir,
-            streamFile.relativeFilePath || fileNameArg,
-          );
+          const writePath = plugins.path.join(targetDir, relativePath);
           await plugins.fsPromises.mkdir(plugins.path.dirname(writePath), { recursive: true });
           const writeStream = plugins.fs.createWriteStream(writePath);
           readStream.pipe(writeStream);
           writeStream.on('finish', () => {
-            done.resolve();
+            innerDone.resolve();
           });
-          await done.promise;
+          await innerDone.promise;
         },
         finalFunction: async () => {
           done.resolve();
         },
-      }),
+      })
     );
+
     return done.promise;
   }
 
-  public async exportToStreamOfStreamFiles() {
-    const streamFileIntake =
-      new plugins.smartstream.StreamIntake<plugins.smartfile.StreamFile>({
-        objectMode: true,
-      });
-    const archiveStream = await this.getArchiveStream();
+  /**
+   * Extract archive to a stream of StreamFile objects
+   */
+  public async toStreamFiles(): Promise<plugins.smartstream.StreamIntake<plugins.smartfile.StreamFile>> {
+    this.ensureExtractionSource();
+
+    const streamFileIntake = new plugins.smartstream.StreamIntake<plugins.smartfile.StreamFile>({
+      objectMode: true,
+    });
+
+    // Guard to prevent multiple signalEnd calls
+    let hasSignaledEnd = false;
+    const safeSignalEnd = () => {
+      if (!hasSignaledEnd) {
+        hasSignaledEnd = true;
+        streamFileIntake.signalEnd();
+      }
+    };
+
+    const archiveStream = await this.getSourceStream();
     const createAnalyzedStream = () => this.archiveAnalyzer.getAnalyzedStream();
 
-    // lets create a function that can be called multiple times to unpack layers of archives
     const createUnpackStream = () =>
-      plugins.smartstream.createTransformFunction<IAnalyzedResult, any>(
+      plugins.smartstream.createTransformFunction<IAnalyzedResult, void>(
         async (analyzedResultChunk) => {
           if (analyzedResultChunk.fileType?.mime === 'application/x-tar') {
-            const tarStream =
-              analyzedResultChunk.decompressionStream as plugins.tarStream.Extract;
+            const tarStream = analyzedResultChunk.decompressionStream as plugins.tarStream.Extract;
+
             tarStream.on('entry', async (header, stream, next) => {
               if (header.type === 'directory') {
-                console.log(
-                  `tar stream directory: ${header.name} ... skipping!`,
-                );
-                stream.resume(); // Consume directory stream
+                stream.resume();
                 stream.on('end', () => next());
                 return;
               }
-              console.log(`tar stream file: ${header.name}`);
-              
-              // Create a PassThrough stream to buffer the data
+
               const passThrough = new plugins.stream.PassThrough();
-              const streamfile = plugins.smartfile.StreamFile.fromStream(
-                passThrough,
-                header.name,
-              );
-              
-              // Push the streamfile immediately
+              const streamfile = plugins.smartfile.StreamFile.fromStream(passThrough, header.name);
               streamFileIntake.push(streamfile);
-              
-              // Pipe the tar entry stream to the passthrough
               stream.pipe(passThrough);
-              
-              // Move to next entry when this one ends
               stream.on('end', () => {
                 passThrough.end();
                 next();
               });
             });
-            tarStream.on('finish', function () {
-              console.log('tar extraction finished');
-              // Only signal end if this is the final stream
-              streamFileIntake.signalEnd();
+
+            tarStream.on('finish', () => {
+              safeSignalEnd();
             });
-            analyzedResultChunk.resultStream.pipe(
-              analyzedResultChunk.decompressionStream,
-            );
+
+            analyzedResultChunk.resultStream.pipe(analyzedResultChunk.decompressionStream);
           } else if (analyzedResultChunk.fileType?.mime === 'application/zip') {
             analyzedResultChunk.resultStream
               .pipe(analyzedResultChunk.decompressionStream)
               .pipe(
                 new plugins.smartstream.SmartDuplex({
                   objectMode: true,
-                  writeFunction: async (
-                    streamFileArg: plugins.smartfile.StreamFile,
-                    streamtools,
-                  ) => {
+                  writeFunction: async (streamFileArg: plugins.smartfile.StreamFile) => {
                     streamFileIntake.push(streamFileArg);
                   },
                   finalFunction: async () => {
-                    streamFileIntake.signalEnd();
+                    safeSignalEnd();
                   },
-                }),
+                })
               );
-          } else if (
-            analyzedResultChunk.isArchive &&
-            analyzedResultChunk.decompressionStream
-          ) {
+          } else if (analyzedResultChunk.isArchive && analyzedResultChunk.decompressionStream) {
             // For nested archives (like gzip containing tar)
-            const nestedStream = analyzedResultChunk.resultStream
+            analyzedResultChunk.resultStream
               .pipe(analyzedResultChunk.decompressionStream)
               .pipe(createAnalyzedStream())
               .pipe(createUnpackStream());
-            
-            // Don't signal end here - let the nested unpacker handle it
           } else {
             const streamFile = plugins.smartfile.StreamFile.fromStream(
               analyzedResultChunk.resultStream,
-              analyzedResultChunk.fileType?.ext,
+              analyzedResultChunk.fileType?.ext
             );
             streamFileIntake.push(streamFile);
-            streamFileIntake.signalEnd();
+            safeSignalEnd();
           }
         },
-        {
-          objectMode: true,
-        },
+        { objectMode: true }
       );
 
     archiveStream.pipe(createAnalyzedStream()).pipe(createUnpackStream());
     return streamFileIntake;
   }
+
+  /**
+   * Extract archive to an array of SmartFile objects (in-memory)
+   */
+  public async toSmartFiles(): Promise<plugins.smartfile.SmartFile[]> {
+    this.ensureExtractionSource();
+    const streamFiles = await this.toStreamFiles();
+    const smartFiles: plugins.smartfile.SmartFile[] = [];
+    const filterFn = this.buildFilterFunction();
+    const pendingConversions: Promise<void>[] = [];
+
+    return new Promise((resolve, reject) => {
+      streamFiles.on('data', (streamFile: plugins.smartfile.StreamFile) => {
+        // Track all async conversions to ensure they complete before resolving
+        const conversion = (async () => {
+          try {
+            const smartFile = await streamFile.toSmartFile();
+
+            // Apply filter if configured
+            if (filterFn) {
+              const passes = filterFn({
+                path: smartFile.relative,
+                size: smartFile.contents.length,
+                isDirectory: false,
+                isFile: true,
+              });
+              if (!passes) return;
+            }
+
+            smartFiles.push(smartFile);
+          } catch (err) {
+            reject(err);
+          }
+        })();
+        pendingConversions.push(conversion);
+      });
+      streamFiles.on('end', async () => {
+        // Wait for all conversions to complete before resolving
+        await Promise.all(pendingConversions);
+        resolve(smartFiles);
+      });
+      streamFiles.on('error', reject);
+    });
+  }
+
+  /**
+   * Extract a single file from the archive by path
+   */
+  public async extractFile(filePath: string): Promise<plugins.smartfile.SmartFile | null> {
+    this.ensureExtractionSource();
+    const streamFiles = await this.toStreamFiles();
+
+    return new Promise((resolve, reject) => {
+      let found = false;
+
+      streamFiles.on('data', async (streamFile: plugins.smartfile.StreamFile) => {
+        if (streamFile.relativeFilePath === filePath || streamFile.relativeFilePath?.endsWith(filePath)) {
+          found = true;
+          try {
+            const smartFile = await streamFile.toSmartFile();
+            resolve(smartFile);
+          } catch (err) {
+            reject(err);
+          }
+        }
+      });
+
+      streamFiles.on('end', () => {
+        if (!found) {
+          resolve(null);
+        }
+      });
+
+      streamFiles.on('error', reject);
+    });
+  }
+
+  // ============================================
+  // TERMINAL METHODS - OUTPUT
+  // ============================================
+
+  /**
+   * Build and finalize the archive, returning this instance
+   */
+  public async build(): Promise<SmartArchive> {
+    await this.doBuild();
+    return this;
+  }
+
+  /**
+   * Internal build implementation (avoids thenable recursion)
+   */
+  private async doBuild(): Promise<void> {
+    if (this._mode === 'extract') {
+      // For extraction mode, nothing to build
+      return;
+    }
+
+    if (this.archiveBuffer) {
+      // Already built
+      return;
+    }
+
+    // For creation mode, build the archive buffer
+    this.ensureCreationFormat();
+    await this.resolveDirectories();
+
+    const entries = this.getFilteredEntries();
+
+    if (this.creationFormat === 'tar' || this.creationFormat === 'tar.gz' || this.creationFormat === 'tgz') {
+      if (this.creationFormat === 'tar') {
+        this.archiveBuffer = await this.tarTools.packFiles(entries);
+      } else {
+        this.archiveBuffer = await this.tarTools.packFilesToTarGz(entries, this._compressionLevel);
+      }
+    } else if (this.creationFormat === 'zip') {
+      this.archiveBuffer = await this.zipTools.createZip(entries, this._compressionLevel);
+    } else if (this.creationFormat === 'gz') {
+      if (entries.length !== 1) {
+        throw new Error('GZIP format only supports a single file');
+      }
+      let content: Buffer;
+      if (typeof entries[0].content === 'string') {
+        content = Buffer.from(entries[0].content);
+      } else if (Buffer.isBuffer(entries[0].content)) {
+        content = entries[0].content;
+      } else {
+        throw new Error('GZIP format requires string or Buffer content');
+      }
+      this.archiveBuffer = await this.gzipTools.compress(content, this._compressionLevel);
+    } else {
+      throw new Error(`Unsupported format: ${this.creationFormat}`);
+    }
+  }
+
+  /**
+   * Build archive and return as Buffer
+   */
+  public async toBuffer(): Promise<Buffer> {
+    if (this._mode === 'create' && !this.archiveBuffer) {
+      await this.doBuild();
+    }
+
+    if (this.archiveBuffer) {
+      return this.archiveBuffer;
+    }
+
+    // For extraction mode, get the source as buffer
+    const stream = await this.getSourceStream();
+    return this.streamToBuffer(stream);
+  }
+
+  /**
+   * Build archive and write to file
+   */
+  public async toFile(filePath: string): Promise<void> {
+    const buffer = await this.toBuffer();
+    await plugins.fsPromises.mkdir(plugins.path.dirname(filePath), { recursive: true });
+    await plugins.fsPromises.writeFile(filePath, buffer);
+  }
+
+  /**
+   * Get archive as a readable stream
+   */
+  public async toStream(): Promise<plugins.stream.Readable> {
+    if (this._mode === 'create' && !this.archiveBuffer) {
+      await this.doBuild();
+    }
+
+    if (this.archiveBuffer) {
+      return plugins.stream.Readable.from(this.archiveBuffer);
+    }
+
+    return this.getSourceStream();
+  }
+
+  // ============================================
+  // TERMINAL METHODS - ANALYSIS
+  // ============================================
+
+  /**
+   * Analyze the archive and return metadata
+   */
+  public async analyze(): Promise<IArchiveInfo> {
+    this.ensureExtractionSource();
+    const stream = await this.getSourceStream();
+    const firstChunk = await this.readFirstChunk(stream);
+    const fileType = await plugins.fileType.fileTypeFromBuffer(firstChunk);
+
+    let format: TArchiveFormat | null = null;
+    let isCompressed = false;
+    let isArchive = false;
+
+    if (fileType) {
+      switch (fileType.mime) {
+        case 'application/gzip':
+          format = 'gz';
+          isCompressed = true;
+          isArchive = true;
+          break;
+        case 'application/zip':
+          format = 'zip';
+          isCompressed = true;
+          isArchive = true;
+          break;
+        case 'application/x-tar':
+          format = 'tar';
+          isArchive = true;
+          break;
+        case 'application/x-bzip2':
+          format = 'bz2';
+          isCompressed = true;
+          isArchive = true;
+          break;
+      }
+    }
+
+    return {
+      format,
+      isCompressed,
+      isArchive,
+    };
+  }
+
+  /**
+   * List all entries in the archive
+   */
+  public async list(): Promise<IArchiveEntryInfo[]> {
+    this.ensureExtractionSource();
+    const entries: IArchiveEntryInfo[] = [];
+    const streamFiles = await this.toStreamFiles();
+
+    return new Promise((resolve, reject) => {
+      streamFiles.on('data', (streamFile: plugins.smartfile.StreamFile) => {
+        entries.push({
+          path: streamFile.relativeFilePath || 'unknown',
+          size: 0, // Size not available without reading
+          isDirectory: false,
+          isFile: true,
+        });
+      });
+      streamFiles.on('end', () => resolve(entries));
+      streamFiles.on('error', reject);
+    });
+  }
+
+  /**
+   * Check if a specific file exists in the archive
+   */
+  public async hasFile(filePath: string): Promise<boolean> {
+    this.ensureExtractionSource();
+    const entries = await this.list();
+    return entries.some((e) => e.path === filePath || e.path.endsWith(filePath));
+  }
+
+
+  // ============================================
+  // PRIVATE HELPERS
+  // ============================================
+
+  /**
+   * Ensure we're not in create mode when calling extraction methods
+   */
+  private ensureNotInCreateMode(methodName: string): void {
+    if (this._mode === 'create') {
+      throw new Error(
+        `Cannot call .${methodName}() in creation mode. ` +
+          `Use extraction methods (.url(), .file(), .stream(), .buffer()) for extraction mode.`
+      );
+    }
+  }
+
+  /**
+   * Ensure we're not in extract mode when calling creation methods
+   */
+  private ensureNotInExtractMode(methodName: string): void {
+    if (this._mode === 'extract') {
+      throw new Error(
+        `Cannot call .${methodName}() in extraction mode. ` +
+          `Use .format() for creation mode.`
+      );
+    }
+  }
+
+  /**
+   * Ensure an extraction source is configured
+   */
+  private ensureExtractionSource(): void {
+    if (!this.sourceUrl && !this.sourceFilePath && !this.sourceStream && !this.archiveBuffer) {
+      throw new Error(
+        'No source configured. Call .url(), .file(), .stream(), or .buffer() first.'
+      );
+    }
+  }
+
+  /**
+   * Ensure a format is configured for creation
+   */
+  private ensureCreationFormat(): void {
+    if (!this.creationFormat) {
+      throw new Error('No format specified. Call .format() before creating archive.');
+    }
+  }
+
+  /**
+   * Get the source stream
+   */
+  private async getSourceStream(): Promise<plugins.stream.Readable> {
+    if (this.archiveBuffer) {
+      return plugins.stream.Readable.from(this.archiveBuffer);
+    }
+    if (this.sourceStream) {
+      return this.sourceStream;
+    }
+    if (this.sourceUrl) {
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(this.sourceUrl)
+        .get();
+      const webStream = response.stream();
+      return plugins.stream.Readable.fromWeb(webStream as any);
+    }
+    if (this.sourceFilePath) {
+      return plugins.fs.createReadStream(this.sourceFilePath);
+    }
+    throw new Error('No archive source configured');
+  }
+
+  /**
+   * Build a combined filter function from all configured filters
+   */
+  private buildFilterFunction(): TEntryFilter | undefined {
+    const hasFilters =
+      this._filters.length > 0 ||
+      this._includePatterns.length > 0 ||
+      this._excludePatterns.length > 0;
+
+    if (!hasFilters) {
+      return undefined;
+    }
+
+    return (entry: IArchiveEntryInfo) => {
+      // Check include patterns (if any specified, at least one must match)
+      if (this._includePatterns.length > 0) {
+        const included = this._includePatterns.some((p) => p.test(entry.path));
+        if (!included) return false;
+      }
+
+      // Check exclude patterns (none must match)
+      for (const pattern of this._excludePatterns) {
+        if (pattern.test(entry.path)) return false;
+      }
+
+      // Check custom filters (all must pass)
+      for (const filter of this._filters) {
+        if (!filter(entry)) return false;
+      }
+
+      return true;
+    };
+  }
+
+  /**
+   * Resolve pending directories to entries
+   */
+  private async resolveDirectories(): Promise<void> {
+    for (const dir of this.pendingDirectories) {
+      const files = await plugins.listFileTree(dir.sourcePath, '**/*');
+      for (const filePath of files) {
+        const archivePath = dir.archiveBase
+          ? plugins.path.join(dir.archiveBase, filePath)
+          : filePath;
+        const absolutePath = plugins.path.join(dir.sourcePath, filePath);
+        const content = await plugins.fsPromises.readFile(absolutePath);
+        this.pendingEntries.push({
+          archivePath,
+          content,
+        });
+      }
+    }
+    this.pendingDirectories = [];
+  }
+
+  /**
+   * Get entries filtered by include/exclude patterns
+   */
+  private getFilteredEntries(): IArchiveEntry[] {
+    const filterFn = this.buildFilterFunction();
+    if (!filterFn) {
+      return this.pendingEntries;
+    }
+
+    return this.pendingEntries.filter((entry) =>
+      filterFn({
+        path: entry.archivePath,
+        size: 0,
+        isDirectory: false,
+        isFile: true,
+      })
+    );
+  }
+
+  /**
+   * Convert a stream to buffer
+   */
+  private async streamToBuffer(stream: plugins.stream.Readable): Promise<Buffer> {
+    const chunks: Buffer[] = [];
+    return new Promise((resolve, reject) => {
+      stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+      stream.on('end', () => resolve(Buffer.concat(chunks)));
+      stream.on('error', reject);
+    });
+  }
+
+  /**
+   * Read first chunk from stream
+   */
+  private async readFirstChunk(stream: plugins.stream.Readable): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const onData = (chunk: Buffer) => {
+        stream.removeListener('data', onData);
+        stream.removeListener('error', reject);
+        resolve(chunk);
+      };
+      stream.on('data', onData);
+      stream.on('error', reject);
+    });
+  }
 }