@neoware_inc/neozipkit 0.5.0

package/dist/node/ZipDecompressNode.d.ts

@@ -0,0 +1,197 @@
+import ZipkitNode from './ZipkitNode';
+import ZipEntry from '../core/ZipEntry';
+/**
+ * ZipDecompressNode - Node.js file-based decompression operations
+ *
+ * Independent decompression implementation for Node.js environments.
+ * All decompression logic is implemented directly without delegating to ZipDecompress.
+ *
+ * @example
+ * ```typescript
+ * const zipkitNode = new ZipkitNode();
+ * const decompressNode = new ZipDecompressNode(zipkitNode);
+ * await decompressNode.extractToFile(entry, './output/file.txt');
+ * ```
+ */
+export declare class ZipDecompressNode {
+    private zipkitNode;
+    private static loggingEnabled;
+    /**
+     * Creates a new ZipDecompressNode instance
+     * @param zipkitNode - ZipkitNode instance to use for ZIP operations
+     */
+    constructor(zipkitNode: ZipkitNode);
+    /**
+     * Internal logging method - only logs if class logging is enabled
+     */
+    private log;
+    /**
+     * Extract file directly to disk with true streaming (no memory buffering)
+     * Public method that validates file mode and extracts entry to file
+     *
+     * This method processes chunks as they are decompressed and writes them
+     * directly to disk, maintaining minimal memory footprint regardless of file size.
+     * This is the recommended method for file extraction to avoid memory issues.
+     *
+     * @param entry ZIP entry to extract
+     * @param outputPath Path where the file should be written
+     * @param options Optional extraction options including progress callback
+     * @throws Error if not a File-based ZIP
+     */
+    extractToFile(entry: ZipEntry, outputPath: string, options?: {
+        skipHashCheck?: boolean;
+        onProgress?: (bytes: number) => void;
+    }): Promise<void>;
+    /**
+     * Extract file to Buffer (in-memory) for file-based ZIP
+     *
+     * This method extracts a ZIP entry directly to a Buffer without writing to disk.
+     * This is ideal for reading metadata files (like NZIP.TOKEN) that don't need
+     * to be written to temporary files.
+     *
+     * @param entry ZIP entry to extract
+     * @param options Optional extraction options including progress callback
+     * @returns Promise that resolves to Buffer containing the extracted file data
+     * @throws Error if not a File-based ZIP or if extraction fails
+     */
+    extractToBuffer(entry: ZipEntry, options?: {
+        skipHashCheck?: boolean;
+        onProgress?: (bytes: number) => void;
+    }): Promise<Buffer>;
+    /**
+     * Test entry integrity without extracting to disk
+     * Validates CRC-32 or SHA-256 hash without writing decompressed data
+     *
+     * This method processes chunks as they are decompressed and validates them,
+     * but discards the decompressed data instead of writing to disk. This is useful
+     * for verifying ZIP file integrity without extracting files.
+     *
+     * @param entry ZIP entry to test
+     * @param options Optional test options including progress callback
+     * @returns Promise that resolves to an object containing the verified hash (if SHA-256) or undefined
+     * @throws Error if validation fails (INVALID_CRC or INVALID_SHA256) or if not a File-based ZIP
+     */
+    testEntry(entry: ZipEntry, options?: {
+        skipHashCheck?: boolean;
+        onProgress?: (bytes: number) => void;
+    }): Promise<{
+        verifiedHash?: string;
+    }>;
+    /**
+     * Read compressed data from file and yield one block at a time
+     *
+     * MEMORY EFFICIENCY: Yields compressed data chunks one at a time without accumulation.
+     * Each chunk is read from disk and yielded immediately, allowing downstream processing
+     * (decryption, decompression) to handle one block at a time.
+     *
+     * @param fileHandle - File handle to read from
+     * @param entry - ZIP entry to read compressed data for
+     * @param chunkSize - Optional chunk size override (defaults to ZipkitServer's bufferSize)
+     * @returns Async generator yielding compressed data chunks one at a time
+     */
+    private readCompressedDataStream;
+    /**
+     * Handles: reading compressed data, optional decryption, decompression, hashing, and writing
+     * Internal method that takes fileHandle as parameter
+     */
+    private extractToFileInternal;
+    /**
+     * Extract file to Buffer (in-memory) for file-based ZIP
+     * Internal method that takes fileHandle as parameter
+     *
+     * MEMORY EFFICIENCY: Accumulates decompressed chunks into a Buffer.
+     * For small files (like metadata), this is acceptable. For large files,
+     * consider using extractToFile() instead.
+     */
+    private extractToBufferInternal;
+    /**
+     * Test entry integrity without writing to disk
+     * Internal method that takes fileHandle as parameter
+     */
+    private testEntryInternal;
+    /**
+     * Decompress data stream and write to file
+     *
+     * MEMORY EFFICIENCY: Processes decompressed chunks one at a time.
+     * Pipeline: compressedStream → decompressStream() → hashCalc → writeStream
+     * - Each decompressed chunk is written immediately without accumulation
+     * - Hash calculation is incremental (HashCalculator)
+     * - Progress callbacks are invoked per chunk
+     *
+     * Handles decompression, hash calculation, file writing, and verification.
+     * Internal method only
+     */
+    private unCompressToFile;
+    /**
+     * Decompress data stream and accumulate to Buffer
+     *
+     * MEMORY EFFICIENCY: Accumulates decompressed chunks into a Buffer.
+     * For small files (like metadata), this is acceptable. For large files,
+     * consider using unCompressToFile() instead.
+     *
+     * Pipeline: compressedStream → decompressStream() → hashCalc → Buffer accumulation
+     * - Each decompressed chunk is accumulated into a Buffer
+     * - Hash calculation is incremental (HashCalculator)
+     * - Progress callbacks are invoked per chunk
+     *
+     * Handles decompression, hash calculation, and Buffer accumulation.
+     * Internal method only
+     */
+    private unCompressToBuffer;
+    /**
+     * Decompress data stream and validate hash without writing to disk
+     *
+     * MEMORY EFFICIENCY: Processes decompressed chunks one at a time.
+     * Pipeline: compressedStream → decompressStream() → hashCalc → validation
+     * - Each decompressed chunk is validated immediately without accumulation
+     * - Hash calculation is incremental (HashCalculator)
+     * - Progress callbacks are invoked per chunk
+     * - No file writing - data is discarded after validation
+     *
+     * Handles decompression, hash calculation, and verification.
+     * Internal method only
+     */
+    private unCompressToTest;
+    /**
+     * Decompress data stream chunk by chunk
+     *
+     * MEMORY EFFICIENCY: Processes compressed data one block at a time.
+     * - For STORED: Passes through chunks unchanged (no accumulation)
+     * - For DEFLATED: Uses pako streaming inflate (maintains state across chunks)
+     * - For ZSTD: Collects all chunks (ZSTD limitation - requires full buffer)
+     *
+     * Pipeline: readCompressedDataStream() → DecryptionStream.decrypt() → decompressStream() → writeStream
+     *
+     * Internal method only
+     */
+    private decompressStream;
+    /**
+     * Streaming deflate decompression using pako
+     *
+     * MEMORY EFFICIENCY: Processes compressed chunks one at a time.
+     * - Inflator maintains decompression state across chunks
+     * - Decompressed chunks are yielded immediately after processing each compressed chunk
+     * - No accumulation of compressed data (except in pako's internal buffers)
+     */
+    private inflateStream;
+    /**
+     * Streaming ZSTD decompression
+     */
+    private zstdDecompressStream;
+    /**
+     * Inflate data using pako (internal use only)
+     */
+    private inflate;
+    /**
+     * Zstd decompress method (now async with ZstdManager)
+     * Internal method only
+     */
+    private zstdDecompressSync;
+    /**
+     * Uncompress compressed data buffer (now async for Zstd)
+     * Handles decompression and hash verification
+     * Internal method only
+     */
+    private unCompress;
+}
+//# sourceMappingURL=ZipDecompressNode.d.ts.map

package/dist/node/ZipDecompressNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipDecompressNode.d.ts","sourceRoot":"","sources":["../../src/node/ZipDecompressNode.ts"],"names":[],"mappings":"AAiBA,OAAO,UAAU,MAAM,cAAc,CAAC;AAEtC,OAAO,QAAQ,MAAM,kBAAkB,CAAC;AASxC;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAa;IAG/B,OAAO,CAAC,MAAM,CAAC,cAAc,CAAkB;IAE/C;;;OAGG;gBACS,UAAU,EAAE,UAAU;IAQlC;;OAEG;IACH,OAAO,CAAC,GAAG;IAUX;;;;;;;;;;;;OAYG;IACG,aAAa,CACjB,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QACR,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACtC,GACA,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;;;;;;OAWG;IACG,eAAe,CACnB,KAAK,EAAE,QAAQ,EACf,OAAO,CAAC,EAAE;QACR,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACtC,GACA,OAAO,CAAC,MAAM,CAAC;IAQlB;;;;;;;;;;;;OAYG;IACG,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,OAAO,CAAC,EAAE;QACR,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KACtC,GACA,OAAO,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYrC;;;;;;;;;;;OAWG;YACY,wBAAwB;IAqCvC;;;OAGG;YACW,qBAAqB;IAyDnC;;;;;;;OAOG;YACW,uBAAuB;IAiDrC;;;OAGG;YACW,iBAAiB;IAkD/B;;;;;;;;;;;OAWG;YACW,gBAAgB;IA8E9B;;;;;;;;;;;;;;OAcG;YACW,kBAAkB;IA0DhC;;;;;;;;;;;;OAYG;YACW,gBAAgB;IA2D9B;;;;;;;;;;;OAWG;YACY,gBAAgB;IAsB/B;;;;;;;OAOG;YACY,aAAa;IA6B5B;;OAEG;YACY,oBAAoB;IA+BnC;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;;OAGG;YACW,kBAAkB;IAchC;;;;OAIG;YACW,UAAU;CAyCzB"}