@neoware_inc/neozipkit 0.5.0

package/dist/node/ZipDecompressNode.js

@@ -0,0 +1,678 @@
+"use strict";
+// ======================================
+//	ZipDecompressNode.ts - Node.js File-Based Decompression
+//  Copyright (c) 2025 NeoWare, Inc. All rights reserved.
+// ======================================
+//
+// LOGGING INSTRUCTIONS:
+// ---------------------
+// To enable/disable logging, set loggingEnabled to true/false in the class:
+//   private static loggingEnabled: boolean = true;  // Enable logging
+//   private static loggingEnabled: boolean = false; // Disable logging
+//
+// Logging respects the global Logger level (debug, info, warn, error, silent).
+// Logger level is automatically set to 'debug' when loggingEnabled is true.
+//
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipDecompressNode = void 0;
+const pako = require('pako');
+const ZstdManager_1 = require("../core/ZstdManager");
+const Logger_1 = require("../core/components/Logger");
+const Errors_1 = __importDefault(require("../core/constants/Errors"));
+const Headers_1 = require("../core/constants/Headers");
+const HashCalculator_1 = require("../core/components/HashCalculator");
+const ZipCrypto_1 = require("../core/encryption/ZipCrypto");
+const types_1 = require("../core/encryption/types");
+const fs = __importStar(require("fs"));
+/**
+ * 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');
+ * ```
+ */
+class ZipDecompressNode {
+    /**
+     * Creates a new ZipDecompressNode instance
+     * @param zipkitNode - ZipkitNode instance to use for ZIP operations
+     */
+    constructor(zipkitNode) {
+        this.zipkitNode = zipkitNode;
+        // If logging is enabled, ensure Logger level is set to debug
+        if (ZipDecompressNode.loggingEnabled) {
+            Logger_1.Logger.setLevel('debug');
+        }
+    }
+    /**
+     * Internal logging method - only logs if class logging is enabled
+     */
+    log(...args) {
+        if (ZipDecompressNode.loggingEnabled) {
+            Logger_1.Logger.debug(`[ZipDecompressNode]`, ...args);
+        }
+    }
+    // ============================================================================
+    // File-Based Extraction Methods
+    // ============================================================================
+    /**
+     * 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
+     */
+    async extractToFile(entry, outputPath, options) {
+        // Get fileHandle from zipkitNode (merged from ZipLoadEntriesServer)
+        const fileHandle = this.zipkitNode.getFileHandle();
+        // Call internal method with fileHandle
+        await this.extractToFileInternal(fileHandle, entry, outputPath, options);
+    }
+    /**
+     * 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
+     */
+    async extractToBuffer(entry, options) {
+        // Get fileHandle from zipkitNode
+        const fileHandle = this.zipkitNode.getFileHandle();
+        // Call internal extract to buffer method
+        return await this.extractToBufferInternal(fileHandle, entry, options);
+    }
+    /**
+     * 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
+     */
+    async testEntry(entry, options) {
+        // Get fileHandle from zipkitNode
+        const fileHandle = this.zipkitNode.getFileHandle();
+        // Call internal test method with fileHandle
+        return await this.testEntryInternal(fileHandle, entry, options);
+    }
+    // ============================================================================
+    // Internal File-Based Methods
+    // ============================================================================
+    /**
+     * 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
+     */
+    async *readCompressedDataStream(fileHandle, entry, chunkSize) {
+        // Use provided chunkSize or ZipkitServer's default bufferSize
+        const effectiveChunkSize = chunkSize || this.zipkitNode.getBufferSize();
+        // Read local file header
+        const localHeaderBuffer = Buffer.alloc(30);
+        await fileHandle.read(localHeaderBuffer, 0, 30, entry.localHdrOffset);
+        if (localHeaderBuffer.readUInt32LE(0) !== 0x04034b50) { // LOCAL_HDR.SIGNATURE
+            throw new Error(Errors_1.default.INVALID_CEN);
+        }
+        // Calculate data start position
+        const filenameLength = localHeaderBuffer.readUInt16LE(26);
+        const extraFieldLength = localHeaderBuffer.readUInt16LE(28);
+        const dataStart = entry.localHdrOffset + 30 + filenameLength + extraFieldLength;
+        // Yield compressed data in chunks - one block at a time
+        let remaining = entry.compressedSize;
+        let position = dataStart;
+        while (remaining > 0) {
+            const currentChunkSize = Math.min(effectiveChunkSize, remaining);
+            const chunk = Buffer.alloc(currentChunkSize);
+            await fileHandle.read(chunk, 0, currentChunkSize, position);
+            this.log(`readCompressedDataStream: Yielding compressed chunk: ${chunk.length} bytes (${remaining} bytes remaining)`);
+            yield chunk;
+            position += currentChunkSize;
+            remaining -= currentChunkSize;
+        }
+    }
+    /**
+     * Handles: reading compressed data, optional decryption, decompression, hashing, and writing
+     * Internal method that takes fileHandle as parameter
+     */
+    async extractToFileInternal(fileHandle, entry, outputPath, options) {
+        this.log(`extractToFileInternal called for entry: ${entry.filename}`);
+        this.log(`Entry isEncrypted: ${entry.isEncrypted}, has password: ${!!this.zipkitNode?.password}`);
+        try {
+            // Create output stream with overwrite flag to truncate existing files
+            const writeStream = fs.createWriteStream(outputPath, { flags: 'w' });
+            // Build compressed data stream - yields one block at a time
+            let dataStream = this.readCompressedDataStream(fileHandle, entry);
+            // Decrypt if needed using password on zipkitNode instance
+            // Decryption maintains state across blocks via updateKeys()
+            const isEncrypted = entry.isEncrypted && this.zipkitNode?.password;
+            if (isEncrypted) {
+                this.log(`Starting decryption for entry: ${entry.filename}`);
+                // Prepare entry for decryption by parsing local header
+                await ZipCrypto_1.DecryptionStream.prepareEntryForDecryption(fileHandle, entry);
+                const encryptionMethod = entry.encryptionMethod || types_1.EncryptionMethod.ZIP_CRYPTO;
+                this.log(`Creating DecryptionStream with method: ${encryptionMethod}`);
+                const decryptor = new ZipCrypto_1.DecryptionStream({
+                    password: this.zipkitNode.password,
+                    method: encryptionMethod,
+                    entry: entry
+                });
+                this.log(`DecryptionStream created, calling decrypt()...`);
+                // Decryption processes one block at a time, maintaining state across blocks
+                dataStream = decryptor.decrypt(dataStream);
+                this.log(`decrypt() returned, dataStream is now a generator that yields one decrypted block at a time`);
+            }
+            // Pipeline: readCompressedDataStream() → DecryptionStream.decrypt() → decompressStream() → writeStream
+            // Each stage processes one block at a time without accumulation
+            await this.unCompressToFile(dataStream, entry, writeStream, {
+                skipHashCheck: options?.skipHashCheck,
+                onProgress: options?.onProgress,
+                outputPath
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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.
+     */
+    async extractToBufferInternal(fileHandle, entry, options) {
+        this.log(`extractToBufferInternal called for entry: ${entry.filename}`);
+        this.log(`Entry isEncrypted: ${entry.isEncrypted}, has password: ${!!this.zipkitNode?.password}`);
+        try {
+            // Build compressed data stream - yields one block at a time
+            let dataStream = this.readCompressedDataStream(fileHandle, entry);
+            // Decrypt if needed using password on zipkitNode instance
+            const isEncrypted = entry.isEncrypted && this.zipkitNode?.password;
+            if (isEncrypted) {
+                this.log(`Starting decryption for entry: ${entry.filename}`);
+                // Prepare entry for decryption by parsing local header
+                await ZipCrypto_1.DecryptionStream.prepareEntryForDecryption(fileHandle, entry);
+                const encryptionMethod = entry.encryptionMethod || types_1.EncryptionMethod.ZIP_CRYPTO;
+                this.log(`Creating DecryptionStream with method: ${encryptionMethod}`);
+                const decryptor = new ZipCrypto_1.DecryptionStream({
+                    password: this.zipkitNode.password,
+                    method: encryptionMethod,
+                    entry: entry
+                });
+                this.log(`DecryptionStream created, calling decrypt()...`);
+                dataStream = decryptor.decrypt(dataStream);
+                this.log(`decrypt() returned, dataStream is now a generator that yields one decrypted block at a time`);
+            }
+            // Pipeline: readCompressedDataStream() → DecryptionStream.decrypt() → decompressStream() → accumulate to Buffer
+            return await this.unCompressToBuffer(dataStream, entry, {
+                skipHashCheck: options?.skipHashCheck,
+                onProgress: options?.onProgress
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Test entry integrity without writing to disk
+     * Internal method that takes fileHandle as parameter
+     */
+    async testEntryInternal(fileHandle, entry, options) {
+        this.log(`testEntryInternal called for entry: ${entry.filename}`);
+        this.log(`Entry isEncrypted: ${entry.isEncrypted}, has password: ${!!this.zipkitNode?.password}`);
+        try {
+            // Build compressed data stream - yields one block at a time
+            let dataStream = this.readCompressedDataStream(fileHandle, entry);
+            // Decrypt if needed using password on zipkitNode instance
+            const isEncrypted = entry.isEncrypted && this.zipkitNode?.password;
+            if (isEncrypted) {
+                this.log(`Starting decryption for entry: ${entry.filename}`);
+                // Prepare entry for decryption by parsing local header
+                await ZipCrypto_1.DecryptionStream.prepareEntryForDecryption(fileHandle, entry);
+                const encryptionMethod = entry.encryptionMethod || types_1.EncryptionMethod.ZIP_CRYPTO;
+                this.log(`Creating DecryptionStream with method: ${encryptionMethod}`);
+                const decryptor = new ZipCrypto_1.DecryptionStream({
+                    password: this.zipkitNode.password,
+                    method: encryptionMethod,
+                    entry: entry
+                });
+                this.log(`DecryptionStream created, calling decrypt()...`);
+                dataStream = decryptor.decrypt(dataStream);
+                this.log(`decrypt() returned, dataStream is now a generator that yields one decrypted block at a time`);
+            }
+            // Pipeline: readCompressedDataStream() → DecryptionStream.decrypt() → decompressStream() → hash validation
+            // Data is discarded after validation, no file writing
+            return await this.unCompressToTest(dataStream, entry, {
+                skipHashCheck: options?.skipHashCheck,
+                onProgress: options?.onProgress
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async unCompressToFile(compressedStream, entry, writeStream, // Node.js WriteStream
+    options) {
+        this.log(`unCompressToFile() called for entry: ${entry.filename}, method: ${entry.cmpMethod}`);
+        // Decompress stream - processes one block at a time
+        const decompressedStream = this.decompressStream(compressedStream, entry.cmpMethod);
+        // Process and write chunks - one block at a time
+        const hashCalc = new HashCalculator_1.HashCalculator({ useSHA256: !!entry.sha256 });
+        let totalBytes = 0;
+        try {
+            for await (const chunk of decompressedStream) {
+                this.log(`unCompressToFile: Processing decompressed chunk: ${chunk.length} bytes`);
+                hashCalc.update(chunk);
+                writeStream.write(chunk);
+                totalBytes += chunk.length;
+                if (options?.onProgress) {
+                    options.onProgress(totalBytes);
+                }
+            }
+            // Close stream
+            await new Promise((resolve, reject) => {
+                writeStream.end(() => resolve(undefined));
+                writeStream.on('error', reject);
+            });
+            // Verify hash
+            if (!options?.skipHashCheck) {
+                if (entry.sha256) {
+                    const calculatedHash = hashCalc.finalizeSHA256();
+                    this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
+                    if (calculatedHash !== entry.sha256) {
+                        if (options?.outputPath && fs) {
+                            fs.unlinkSync(options.outputPath);
+                        }
+                        throw new Error(Errors_1.default.INVALID_SHA256);
+                    }
+                    this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
+                }
+                else {
+                    const calculatedCRC = hashCalc.finalizeCRC32();
+                    this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
+                    if (calculatedCRC !== entry.crc) {
+                        if (options?.outputPath && fs) {
+                            fs.unlinkSync(options.outputPath);
+                        }
+                        throw new Error(Errors_1.default.INVALID_CRC);
+                    }
+                    this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
+                }
+            }
+        }
+        catch (error) {
+            // Cleanup file on error
+            if (options?.outputPath && fs) {
+                try {
+                    fs.unlinkSync(options.outputPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            throw error;
+        }
+    }
+    // ============================================================================
+    // Decompression Methods
+    // ============================================================================
+    /**
+     * 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
+     */
+    async unCompressToBuffer(compressedStream, entry, options) {
+        this.log(`unCompressToBuffer() called for entry: ${entry.filename}, method: ${entry.cmpMethod}`);
+        // Decompress stream - processes one block at a time
+        const decompressedStream = this.decompressStream(compressedStream, entry.cmpMethod);
+        // Accumulate chunks into Buffer
+        const hashCalc = new HashCalculator_1.HashCalculator({ useSHA256: !!entry.sha256 });
+        const chunks = [];
+        let totalBytes = 0;
+        try {
+            for await (const chunk of decompressedStream) {
+                this.log(`unCompressToBuffer: Processing decompressed chunk: ${chunk.length} bytes`);
+                hashCalc.update(chunk);
+                chunks.push(chunk);
+                totalBytes += chunk.length;
+                if (options?.onProgress) {
+                    options.onProgress(totalBytes);
+                }
+            }
+            // Concatenate all chunks into a single Buffer
+            const result = Buffer.concat(chunks);
+            // Verify hash
+            if (!options?.skipHashCheck) {
+                if (entry.sha256) {
+                    const calculatedHash = hashCalc.finalizeSHA256();
+                    this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
+                    if (calculatedHash !== entry.sha256) {
+                        throw new Error(Errors_1.default.INVALID_SHA256);
+                    }
+                    this.log(`SHA-256 verification passed`);
+                }
+                else {
+                    const calculatedCRC = hashCalc.finalizeCRC32();
+                    this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
+                    if (calculatedCRC !== entry.crc) {
+                        throw new Error(Errors_1.default.INVALID_CRC);
+                    }
+                    this.log(`CRC-32 verification passed`);
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async unCompressToTest(compressedStream, entry, options) {
+        this.log(`unCompressToTest() called for entry: ${entry.filename}, method: ${entry.cmpMethod}`);
+        // Decompress stream - processes one block at a time
+        const decompressedStream = this.decompressStream(compressedStream, entry.cmpMethod);
+        // Process and validate chunks - one block at a time
+        const hashCalc = new HashCalculator_1.HashCalculator({ useSHA256: !!entry.sha256 });
+        let totalBytes = 0;
+        try {
+            for await (const chunk of decompressedStream) {
+                this.log(`unCompressToTest: Processing decompressed chunk: ${chunk.length} bytes`);
+                hashCalc.update(chunk);
+                // Discard chunk - don't write to disk
+                totalBytes += chunk.length;
+                if (options?.onProgress) {
+                    options.onProgress(totalBytes);
+                }
+            }
+            // Verify hash and return verified hash if SHA-256
+            if (!options?.skipHashCheck) {
+                if (entry.sha256) {
+                    const calculatedHash = hashCalc.finalizeSHA256();
+                    this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
+                    if (calculatedHash !== entry.sha256) {
+                        throw new Error(Errors_1.default.INVALID_SHA256);
+                    }
+                    this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
+                    // Return the verified hash
+                    return { verifiedHash: calculatedHash };
+                }
+                else {
+                    const calculatedCRC = hashCalc.finalizeCRC32();
+                    this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
+                    if (calculatedCRC !== entry.crc) {
+                        throw new Error(Errors_1.default.INVALID_CRC);
+                    }
+                    this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
+                    // No hash to return for CRC-32 only entries
+                    return { verifiedHash: undefined };
+                }
+            }
+            else {
+                // Hash check skipped - return undefined
+                return { verifiedHash: undefined };
+            }
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async *decompressStream(compressedStream, method, chunkSize) {
+        // chunkSize parameter is currently unused but kept for API consistency
+        if (method === Headers_1.CMP_METHOD.STORED) {
+            // Pass through unchanged - one block at a time
+            for await (const chunk of compressedStream) {
+                yield chunk;
+            }
+        }
+        else if (method === Headers_1.CMP_METHOD.DEFLATED) {
+            // Use pako streaming inflate - maintains state across chunks
+            yield* this.inflateStream(compressedStream);
+        }
+        else if (method === Headers_1.CMP_METHOD.ZSTD) {
+            // Use ZSTD streaming decompression - note: ZSTD requires full buffer
+            yield* this.zstdDecompressStream(compressedStream);
+        }
+        else {
+            throw new Error(`Unsupported compression method: ${method}`);
+        }
+    }
+    /**
+     * 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)
+     */
+    async *inflateStream(compressedStream) {
+        const inflator = new pako.Inflate({ raw: true });
+        const decompressedChunks = [];
+        inflator.onData = (chunk) => {
+            decompressedChunks.push(Buffer.from(chunk));
+        };
+        // Process each compressed chunk one at a time
+        for await (const compressedChunk of compressedStream) {
+            this.log(`inflateStream: Processing compressed chunk: ${compressedChunk.length} bytes`);
+            inflator.push(compressedChunk, false);
+            // Yield accumulated decompressed chunks immediately (no accumulation)
+            for (const chunk of decompressedChunks) {
+                yield chunk;
+            }
+            decompressedChunks.length = 0;
+        }
+        // Finalize decompression
+        inflator.push(new Uint8Array(0), true);
+        for (const chunk of decompressedChunks) {
+            yield chunk;
+        }
+    }
+    /**
+     * Streaming ZSTD decompression
+     */
+    async *zstdDecompressStream(compressedStream) {
+        // ZSTD is guaranteed to be initialized via factory method
+        // Collect all compressed chunks first (ZSTD needs complete data)
+        const compressedChunks = [];
+        for await (const chunk of compressedStream) {
+            compressedChunks.push(chunk);
+        }
+        const compressedData = Buffer.concat(compressedChunks);
+        try {
+            // Use global ZstdManager for decompression
+            const decompressed = await ZstdManager_1.ZstdManager.decompress(compressedData);
+            const decompressedBuffer = Buffer.from(decompressed);
+            // Yield decompressed data in chunks using ZipkitServer's bufferSize
+            const chunkSize = this.zipkitNode.getBufferSize();
+            let offset = 0;
+            while (offset < decompressedBuffer.length) {
+                const end = Math.min(offset + chunkSize, decompressedBuffer.length);
+                yield decompressedBuffer.slice(offset, end);
+                offset = end;
+            }
+        }
+        catch (error) {
+            throw new Error(`ZSTD streaming decompression failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Inflate data using pako (internal use only)
+     */
+    inflate(data) {
+        this.log(`inflate() called with ${data.length} bytes`);
+        const result = pako.inflateRaw(data);
+        return Buffer.from(result.buffer, result.byteOffset, result.byteLength);
+    }
+    /**
+     * Zstd decompress method (now async with ZstdManager)
+     * Internal method only
+     */
+    async zstdDecompressSync(data) {
+        this.log(`zstdDecompressSync() called with ${data.length} bytes`);
+        try {
+            // Use global ZstdManager for decompression
+            const decompressed = await ZstdManager_1.ZstdManager.decompress(data);
+            this.log(`ZSTD decompression successful: ${data.length} bytes -> ${decompressed.length} bytes`);
+            return Buffer.from(decompressed);
+        }
+        catch (error) {
+            this.log(`ZSTD decompression failed: ${error}`);
+            throw new Error(`ZSTD decompression failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Uncompress compressed data buffer (now async for Zstd)
+     * Handles decompression and hash verification
+     * Internal method only
+     */
+    async unCompress(compressedData, entry, skipHashCheck) {
+        this.log(`unCompress() called for entry: ${entry.filename}, method: ${entry.cmpMethod}, data length: ${compressedData.length}`);
+        if (compressedData.length === 0) {
+            return Buffer.alloc(0);
+        }
+        let outBuf;
+        if (entry.cmpMethod === Headers_1.CMP_METHOD.STORED) {
+            outBuf = compressedData;
+        }
+        else if (entry.cmpMethod === Headers_1.CMP_METHOD.DEFLATED) {
+            // Use synchronous inflate for deflate
+            outBuf = this.inflate(compressedData);
+        }
+        else if (entry.cmpMethod === Headers_1.CMP_METHOD.ZSTD) {
+            // Use ZSTD decompression (now async with ZstdManager)
+            outBuf = await this.zstdDecompressSync(compressedData);
+        }
+        else {
+            throw new Error(`Unsupported compression method: ${entry.cmpMethod}`);
+        }
+        // Verify hash
+        if (!skipHashCheck) {
+            if (entry.sha256) {
+                const isValid = this.zipkitNode.testSHA256(entry, outBuf);
+                if (!isValid) {
+                    throw new Error(Errors_1.default.INVALID_SHA256);
+                }
+            }
+            else {
+                const isValid = this.zipkitNode.testCRC32(entry, outBuf);
+                if (!isValid) {
+                    throw new Error(Errors_1.default.INVALID_CRC);
+                }
+            }
+        }
+        return outBuf;
+    }
+}
+exports.ZipDecompressNode = ZipDecompressNode;
+// Class-level logging control - set to true to enable logging
+ZipDecompressNode.loggingEnabled = false;
+//# sourceMappingURL=ZipDecompressNode.js.map