yauzl

Before using yauzl, be aware of the following technical limitations:

• No Streaming Unzip API: Due to the ZIP specification (where the Central Directory is at the end of the file), yauzl does not support streaming the entire archive from start to finish. It prioritizes correctness over the convenience of a streaming interface.
• Node.js Version: Requires Node.js version 12 or higher.
• ZIP64 Support: Supports ZIP64 files up to 8PiB. It does not support the full 16EiB range due to JavaScript's IEEE 754 double precision float limitations.
• Compression Methods: Only supports method 0 (stored) and method 8 (deflated). Other methods will cause openReadStream() to return an error.
• Encryption:
  • Traditional Encryption: Can be detected via generalPurposeBitFlag, but yauzl does not decrypt it. Use the decodeFileData option in openReadStream() to manage this.
  • Strong Encryption: Emits an error.
  • Encrypted Central Directory: Emits an error.
• Multi-Disk Archives: Not supported. If the "number of this disk" field in the End of Central Directory Record is not 0, the opening methods will return an err.
• Ignored Fields/Features:
  • Local File Headers (ignored to ensure spec compliance).
  • CRC-32 (provided in Entry but not used for validation).
  • versionNeededToExtract.
  • Data Descriptors.
  • Archive Extra Data Records.
  • Language Encoding Flags.
  • ZIP64 Extensible Data Sectors.

If you prefer a callback-based approach, use yauzl.open(). When using callbacks, you must set {lazyEntries: true} in the options to manually control the entry reading process via zipfile.readEntry().

In the entry event listener, check if entry.fileName ends with / to identify directories. For file entries, use zipfile.openReadStream(entry, callback) to obtain a stream. You must call zipfile.readEntry() again after a stream ends (or after processing a directory) to continue reading the next entry.

var yauzl = require("yauzl");

yauzl.open("path/to/file.zip", {lazyEntries: true}, function(err, zipfile) {
  if (err) throw err;
  zipfile.readEntry();
  zipfile.on("entry", function(entry) {
    if (entry.fileName.endsWith("/")) {
      // Ignore directory entry.
      zipfile.readEntry();
    } else {
      // file entry
      zipfile.openReadStream(entry, function(err, readStream) {
        if (err) throw err;
        readStream.on("end", function() {
          zipfile.readEntry();
        });
        readStream.pipe(somewhere);
      });
    }
  });
});

You can use the Promise-based API to iterate through a ZIP file's entries using await and for await...of. This is the recommended way to handle ZIP files without blocking the JavaScript thread.

When iterating, directory entries are identified by a trailing slash (/) in their fileName. To extract a file, use openReadStreamPromise(entry) to get a readable stream for that specific entry.

const yauzl = require("yauzl");

(async () => {
  try {
    const zipfile = await yauzl.openPromise("path/to/file.zip");
    for await (let entry of zipfile.eachEntry()) {
      if (entry.fileName.endsWith("/")) {
        // Directory file names end with '/'.
        continue;
      } else {
        // file entry
        const readStream = await zipfile.openReadStreamPromise(entry);
        await stream.promises.pipeline(readStream, somewhere);
      }
    }
  } catch (err) {
    // Indicates a malformed zipfile or I/O error.
    throw err;
  }
})();

Use openReadStream(entry, [options], callback) to obtain a Readable Stream for a specific Entry object.

Options:

• decodeFileData (boolean, default: true): If true, yauzl attempts to decode file data using a zlib inflate transform. Set to false to get raw bytes.
  • Note: If you specify start or end byte offsets, you should generally set decodeFileData: false unless the entry is uncompressed and unencrypted.
• start (integer): The inclusive byte offset into the entry's file data.
• end (integer): The exclusive byte offset into the entry's file data.
• decompress (deprecated): Use decodeFileData instead.
• decrypt (deprecated): Use decodeFileData instead.

Error Handling:

• The readStream may emit errors if decompression fails (zlib error) or if the actual byte count does not match the uncompressedSize (if validateEntrySizes is enabled).
• To stop reading, call readStream.destroy(). You must unpipe() the stream before destroying it.

zipfile.openReadStream(entry, { decodeFileData: true }, (err, readStream) => {
  if (err) throw err;
  readStream.on('data', (chunk) => { /* ... */ });
  readStream.on('end', () => { /* ... */ });
});