@push.rocks/smartarchive 4.2.3 → 5.0.0

package/ts/classes.tartools.ts

@@ -1,11 +1,14 @@
-import type { SmartArchive } from './classes.smartarchive.js';
 import * as plugins from './plugins.js';
+import type { IArchiveEntry, TCompressionLevel } from './interfaces.js';
+import { GzipTools } from './classes.gziptools.js';
 
+/**
+ * TAR archive creation and extraction utilities
+ */
 export class TarTools {
-  // INSTANCE
-  constructor() {}
-
-  // packing
+  /**
+   * Add a file to a TAR pack stream
+   */
   public async addFileToPack(
     pack: plugins.tarStream.Pack,
     optionsArg: {
@@ -13,12 +16,12 @@ export class TarTools {
       content?:
         | string
         | Buffer
-        | plugins.smartstream.stream.Readable
+        | plugins.stream.Readable
         | plugins.smartfile.SmartFile
         | plugins.smartfile.StreamFile;
       byteLength?: number;
       filePath?: string;
-    },
+    }
   ): Promise<void> {
     return new Promise<void>(async (resolve, reject) => {
       let fileName: string | null = null;
@@ -26,18 +29,20 @@ export class TarTools {
       if (optionsArg.fileName) {
         fileName = optionsArg.fileName;
       } else if (optionsArg.content instanceof plugins.smartfile.SmartFile) {
-        fileName = (optionsArg.content as plugins.smartfile.SmartFile).relative;
+        fileName = optionsArg.content.relative;
       } else if (optionsArg.content instanceof plugins.smartfile.StreamFile) {
-        fileName = (optionsArg.content as plugins.smartfile.StreamFile)
-          .relativeFilePath;
+        fileName = optionsArg.content.relativeFilePath;
       } else if (optionsArg.filePath) {
         fileName = optionsArg.filePath;
       }
 
-      /**
-       * contentByteLength is used to set the size of the entry in the tar file
-       */
-      let contentByteLength: number;
+      if (!fileName) {
+        reject(new Error('No filename specified for TAR entry'));
+        return;
+      }
+
+      // Determine content byte length
+      let contentByteLength: number | undefined;
       if (optionsArg.byteLength) {
         contentByteLength = optionsArg.byteLength;
       } else if (typeof optionsArg.content === 'string') {
@@ -45,95 +50,159 @@ export class TarTools {
       } else if (Buffer.isBuffer(optionsArg.content)) {
         contentByteLength = optionsArg.content.length;
       } else if (optionsArg.content instanceof plugins.smartfile.SmartFile) {
-        contentByteLength = await optionsArg.content.getSize(); // assuming SmartFile has getSize method
+        contentByteLength = await optionsArg.content.getSize();
       } else if (optionsArg.content instanceof plugins.smartfile.StreamFile) {
-        contentByteLength = await optionsArg.content.getSize(); // assuming StreamFile has getSize method
-      } else if (
-        optionsArg.content instanceof plugins.smartstream.stream.Readable
-      ) {
-        console.warn(
-          '@push.rocks/smartarchive: When streaming, it is recommended to provide byteLength, if known.',
-        );
+        contentByteLength = await optionsArg.content.getSize();
       } else if (optionsArg.filePath) {
-        const fileStat = await plugins.smartfile.fs.stat(optionsArg.filePath);
+        const fileStat = await plugins.fsPromises.stat(optionsArg.filePath);
         contentByteLength = fileStat.size;
       }
 
-      /**
-       * here we try to harmonize all kind of entries towards a readable stream
-       */
-      let content: plugins.smartstream.stream.Readable;
+      // Convert all content types to Readable stream
+      let content: plugins.stream.Readable;
       if (Buffer.isBuffer(optionsArg.content)) {
-        content = plugins.smartstream.stream.Readable.from(optionsArg.content);
+        content = plugins.stream.Readable.from(optionsArg.content);
       } else if (typeof optionsArg.content === 'string') {
-        content = plugins.smartstream.stream.Readable.from(
-          Buffer.from(optionsArg.content),
-        );
+        content = plugins.stream.Readable.from(Buffer.from(optionsArg.content));
       } else if (optionsArg.content instanceof plugins.smartfile.SmartFile) {
-        content = plugins.smartstream.stream.Readable.from(
-          optionsArg.content.contents,
-        );
+        content = plugins.stream.Readable.from(optionsArg.content.contents);
       } else if (optionsArg.content instanceof plugins.smartfile.StreamFile) {
         content = await optionsArg.content.createReadStream();
-      } else if (
-        optionsArg.content instanceof plugins.smartstream.stream.Readable
-      ) {
+      } else if (optionsArg.content instanceof plugins.stream.Readable) {
         content = optionsArg.content;
+      } else if (optionsArg.filePath) {
+        content = plugins.fs.createReadStream(optionsArg.filePath);
+      } else {
+        reject(new Error('No content or filePath specified for TAR entry'));
+        return;
       }
 
       const entry = pack.entry(
         {
           name: fileName,
-          ...(contentByteLength
-            ? {
-                size: contentByteLength,
-              }
-            : null),
+          ...(contentByteLength !== undefined ? { size: contentByteLength } : {}),
         },
-        (err: Error) => {
+        (err: Error | null) => {
           if (err) {
             reject(err);
           } else {
             resolve();
           }
-        },
+        }
       );
 
       content.pipe(entry);
-      resolve();
+      // Note: resolve() is called in the callback above when pipe completes
     });
   }
 
   /**
-   * packs a directory from disk into a tar stream
-   * @param directoryPath
+   * Pack a directory into a TAR stream
    */
-  public async packDirectory(directoryPath: string) {
-    const fileTree = await plugins.smartfile.fs.listFileTree(
-      directoryPath,
-      '**/*',
-    );
+  public async packDirectory(directoryPath: string): Promise<plugins.tarStream.Pack> {
+    const fileTree = await plugins.listFileTree(directoryPath, '**/*');
     const pack = await this.getPackStream();
+
     for (const filePath of fileTree) {
       const absolutePath = plugins.path.join(directoryPath, filePath);
-      const fileStat = await plugins.smartfile.fs.stat(absolutePath);
+      const fileStat = await plugins.fsPromises.stat(absolutePath);
       await this.addFileToPack(pack, {
         byteLength: fileStat.size,
         filePath: absolutePath,
         fileName: filePath,
-        content: plugins.smartfile.fsStream.createReadStream(absolutePath),
+        content: plugins.fs.createReadStream(absolutePath),
       });
     }
+
     return pack;
   }
 
-  public async getPackStream() {
-    const pack = plugins.tarStream.pack();
-    return pack;
+  /**
+   * Get a new TAR pack stream
+   */
+  public async getPackStream(): Promise<plugins.tarStream.Pack> {
+    return plugins.tarStream.pack();
   }
 
-  // extracting
-  getDecompressionStream() {
+  /**
+   * Get a TAR extraction stream
+   */
+  public getDecompressionStream(): plugins.tarStream.Extract {
     return plugins.tarStream.extract();
   }
+
+  /**
+   * Pack files into a TAR buffer
+   */
+  public async packFiles(files: IArchiveEntry[]): Promise<Buffer> {
+    const pack = await this.getPackStream();
+
+    for (const file of files) {
+      await this.addFileToPack(pack, {
+        fileName: file.archivePath,
+        content: file.content as string | Buffer | plugins.stream.Readable | plugins.smartfile.SmartFile | plugins.smartfile.StreamFile,
+        byteLength: file.size,
+      });
+    }
+
+    pack.finalize();
+
+    const chunks: Buffer[] = [];
+    return new Promise((resolve, reject) => {
+      pack.on('data', (chunk: Buffer) => chunks.push(chunk));
+      pack.on('end', () => resolve(Buffer.concat(chunks)));
+      pack.on('error', reject);
+    });
+  }
+
+  /**
+   * Pack a directory into a TAR.GZ buffer
+   */
+  public async packDirectoryToTarGz(
+    directoryPath: string,
+    compressionLevel?: TCompressionLevel
+  ): Promise<Buffer> {
+    const pack = await this.packDirectory(directoryPath);
+    pack.finalize();
+
+    const gzipTools = new GzipTools();
+    const gzipStream = gzipTools.getCompressionStream(compressionLevel);
+
+    const chunks: Buffer[] = [];
+    return new Promise((resolve, reject) => {
+      pack
+        .pipe(gzipStream)
+        .on('data', (chunk: Buffer) => chunks.push(chunk))
+        .on('end', () => resolve(Buffer.concat(chunks)))
+        .on('error', reject);
+    });
+  }
+
+  /**
+   * Pack a directory into a TAR.GZ stream
+   */
+  public async packDirectoryToTarGzStream(
+    directoryPath: string,
+    compressionLevel?: TCompressionLevel
+  ): Promise<plugins.stream.Readable> {
+    const pack = await this.packDirectory(directoryPath);
+    pack.finalize();
+
+    const gzipTools = new GzipTools();
+    const gzipStream = gzipTools.getCompressionStream(compressionLevel);
+
+    return pack.pipe(gzipStream);
+  }
+
+  /**
+   * Pack files into a TAR.GZ buffer
+   */
+  public async packFilesToTarGz(
+    files: IArchiveEntry[],
+    compressionLevel?: TCompressionLevel
+  ): Promise<Buffer> {
+    const tarBuffer = await this.packFiles(files);
+    const gzipTools = new GzipTools();
+    return gzipTools.compress(tarBuffer, compressionLevel);
+  }
 }

package/ts/classes.ziptools.ts

@@ -1,83 +1,209 @@
-import type { SmartArchive } from './classes.smartarchive.js';
 import * as plugins from './plugins.js';
+import type { IArchiveEntry, TCompressionLevel } from './interfaces.js';
 
-class DecompressZipTransform extends plugins.smartstream
-  .SmartDuplex<ArrayBufferLike> {
-  private streamtools: plugins.smartstream.IStreamTools;
+/**
+ * Transform stream for ZIP decompression using fflate
+ * Emits StreamFile objects for each file in the archive
+ */
+export class ZipDecompressionTransform extends plugins.smartstream.SmartDuplex<Buffer, plugins.smartfile.StreamFile> {
+  private streamtools!: plugins.smartstream.IStreamTools;
   private unzipper = new plugins.fflate.Unzip(async (fileArg) => {
     let resultBuffer: Buffer;
-    fileArg.ondata = async (flateError, dat, final) => {
+    fileArg.ondata = async (_flateError, dat, final) => {
       resultBuffer
         ? (resultBuffer = Buffer.concat([resultBuffer, Buffer.from(dat)]))
         : (resultBuffer = Buffer.from(dat));
       if (final) {
-        const streamFile =
-          plugins.smartfile.StreamFile.fromBuffer(resultBuffer);
+        const streamFile = plugins.smartfile.StreamFile.fromBuffer(resultBuffer);
         streamFile.relativeFilePath = fileArg.name;
         this.streamtools.push(streamFile);
       }
     };
     fileArg.start();
   });
+
   constructor() {
     super({
       objectMode: true,
       writeFunction: async (chunkArg, streamtoolsArg) => {
         this.streamtools ? null : (this.streamtools = streamtoolsArg);
         this.unzipper.push(
-          Buffer.isBuffer(chunkArg) ? chunkArg : Buffer.from(chunkArg),
-          false,
+          Buffer.isBuffer(chunkArg) ? chunkArg : Buffer.from(chunkArg as unknown as ArrayBuffer),
+          false
         );
+        return null;
       },
       finalFunction: async () => {
         this.unzipper.push(Buffer.from(''), true);
         await plugins.smartdelay.delayFor(0);
         await this.streamtools.push(null);
+        return null;
       },
     });
     this.unzipper.register(plugins.fflate.UnzipInflate);
   }
 }
 
-// This class wraps fflate's zip in a Node.js Transform stream for compression
-export class CompressZipTransform extends plugins.stream.Transform {
-  files: { [fileName: string]: Uint8Array };
+/**
+ * Streaming ZIP compression using fflate
+ * Allows adding multiple entries before finalizing
+ */
+export class ZipCompressionStream extends plugins.stream.Duplex {
+  private files: Map<string, { data: Uint8Array; options?: plugins.fflate.ZipOptions }> = new Map();
+  private finalized = false;
 
   constructor() {
     super();
-    this.files = {};
   }
 
-  _transform(
-    chunk: Buffer,
-    encoding: BufferEncoding,
-    callback: plugins.stream.TransformCallback,
-  ) {
-    // Simple example: storing chunks in memory before finalizing ZIP in _flush
-    this.files['file.txt'] = new Uint8Array(chunk);
-    callback();
-  }
+  /**
+   * Add a file entry to the ZIP archive
+   */
+  public async addEntry(
+    fileName: string,
+    content: Buffer | plugins.stream.Readable,
+    options?: { compressionLevel?: TCompressionLevel }
+  ): Promise<void> {
+    if (this.finalized) {
+      throw new Error('Cannot add entries to a finalized ZIP archive');
+    }
 
-  _flush(callback: plugins.stream.TransformCallback) {
-    plugins.fflate.zip(this.files, (err, zipped) => {
-      if (err) {
-        callback(err);
-      } else {
-        this.push(Buffer.from(zipped));
-        callback();
+    let data: Buffer;
+    if (Buffer.isBuffer(content)) {
+      data = content;
+    } else {
+      // Collect stream to buffer
+      const chunks: Buffer[] = [];
+      for await (const chunk of content) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
       }
+      data = Buffer.concat(chunks);
+    }
+
+    this.files.set(fileName, {
+      data: new Uint8Array(data),
+      options: options?.compressionLevel !== undefined ? { level: options.compressionLevel } : undefined,
+    });
+  }
+
+  /**
+   * Finalize the ZIP archive and emit the compressed data
+   */
+  public async finalize(): Promise<void> {
+    if (this.finalized) {
+      return;
+    }
+    this.finalized = true;
+
+    const filesObj: plugins.fflate.Zippable = {};
+    for (const [name, { data, options }] of this.files) {
+      filesObj[name] = options ? [data, options] : data;
+    }
+
+    return new Promise((resolve, reject) => {
+      plugins.fflate.zip(filesObj, (err, result) => {
+        if (err) {
+          reject(err);
+        } else {
+          this.push(Buffer.from(result));
+          this.push(null);
+          resolve();
+        }
+      });
     });
   }
+
+  _read(): void {
+    // No-op: data is pushed when finalize() is called
+  }
+
+  _write(
+    _chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null) => void
+  ): void {
+    // Not used for ZIP creation - use addEntry() instead
+    callback(new Error('Use addEntry() to add files to the ZIP archive'));
+  }
 }
 
+/**
+ * ZIP compression and decompression utilities
+ */
 export class ZipTools {
-  constructor() {}
+  /**
+   * Get a streaming compression object for creating ZIP archives
+   */
+  public getCompressionStream(): ZipCompressionStream {
+    return new ZipCompressionStream();
+  }
 
-  public getCompressionStream() {
-    return new CompressZipTransform();
+  /**
+   * Get a streaming decompression transform for extracting ZIP archives
+   */
+  public getDecompressionStream(): ZipDecompressionTransform {
+    return new ZipDecompressionTransform();
   }
 
-  public getDecompressionStream() {
-    return new DecompressZipTransform();
+  /**
+   * Create a ZIP archive from an array of entries
+   */
+  public async createZip(entries: IArchiveEntry[], compressionLevel?: TCompressionLevel): Promise<Buffer> {
+    const filesObj: plugins.fflate.Zippable = {};
+
+    for (const entry of entries) {
+      let data: Uint8Array;
+
+      if (typeof entry.content === 'string') {
+        data = new TextEncoder().encode(entry.content);
+      } else if (Buffer.isBuffer(entry.content)) {
+        data = new Uint8Array(entry.content);
+      } else if (entry.content instanceof plugins.smartfile.SmartFile) {
+        data = new Uint8Array(entry.content.contents);
+      } else if (entry.content instanceof plugins.smartfile.StreamFile) {
+        const buffer = await entry.content.getContentAsBuffer();
+        data = new Uint8Array(buffer);
+      } else {
+        // Readable stream
+        const chunks: Buffer[] = [];
+        for await (const chunk of entry.content as plugins.stream.Readable) {
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        data = new Uint8Array(Buffer.concat(chunks));
+      }
+
+      if (compressionLevel !== undefined) {
+        filesObj[entry.archivePath] = [data, { level: compressionLevel }];
+      } else {
+        filesObj[entry.archivePath] = data;
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      plugins.fflate.zip(filesObj, (err, result) => {
+        if (err) reject(err);
+        else resolve(Buffer.from(result));
+      });
+    });
+  }
+
+  /**
+   * Extract a ZIP buffer to an array of entries
+   */
+  public async extractZip(data: Buffer): Promise<Array<{ path: string; content: Buffer }>> {
+    return new Promise((resolve, reject) => {
+      plugins.fflate.unzip(data, (err, result) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+
+        const entries: Array<{ path: string; content: Buffer }> = [];
+        for (const [path, content] of Object.entries(result)) {
+          entries.push({ path, content: Buffer.from(content) });
+        }
+        resolve(entries);
+      });
+    });
   }
 }

package/ts/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * Base error class for smartarchive
+ */
+export class SmartArchiveError extends Error {
+  public readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = 'SmartArchiveError';
+    this.code = code;
+    // Maintains proper stack trace for where error was thrown (V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * BZIP2-specific decompression errors
+ */
+export class Bzip2Error extends SmartArchiveError {
+  constructor(message: string, code: string = 'BZIP2_ERROR') {
+    super(message, code);
+    this.name = 'Bzip2Error';
+  }
+}
+
+/**
+ * Archive format detection errors
+ */
+export class ArchiveFormatError extends SmartArchiveError {
+  constructor(message: string) {
+    super(message, 'ARCHIVE_FORMAT_ERROR');
+    this.name = 'ArchiveFormatError';
+  }
+}
+
+/**
+ * Stream processing errors
+ */
+export class StreamError extends SmartArchiveError {
+  constructor(message: string) {
+    super(message, 'STREAM_ERROR');
+    this.name = 'StreamError';
+  }
+}
+
+/**
+ * BZIP2 error codes for programmatic error handling
+ */
+export const BZIP2_ERROR_CODES = {
+  NO_MAGIC_NUMBER: 'BZIP2_NO_MAGIC',
+  INVALID_ARCHIVE: 'BZIP2_INVALID_ARCHIVE',
+  CRC_MISMATCH: 'BZIP2_CRC_MISMATCH',
+  INVALID_BLOCK_DATA: 'BZIP2_INVALID_BLOCK',
+  BUFFER_OVERFLOW: 'BZIP2_BUFFER_OVERFLOW',
+  INVALID_HUFFMAN: 'BZIP2_INVALID_HUFFMAN',
+  INVALID_SELECTOR: 'BZIP2_INVALID_SELECTOR',
+  INVALID_POSITION: 'BZIP2_INVALID_POSITION',
+  PREMATURE_END: 'BZIP2_PREMATURE_END',
+} as const;
+
+export type TBzip2ErrorCode = typeof BZIP2_ERROR_CODES[keyof typeof BZIP2_ERROR_CODES];
+
+/**
+ * Throw a BZIP2 error with a specific code
+ */
+export function throwBzip2Error(message: string, code: TBzip2ErrorCode): never {
+  throw new Bzip2Error(message, code);
+}

package/ts/index.ts

@@ -1,4 +1,15 @@
+// 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';
+export * from './classes.bzip2tools.js';
+
+// Archive analysis
+export * from './classes.archiveanalyzer.js';