yazl

yazl is a Node.js library for creating ZIP files. It is designed with three core principles to ensure performance and stability in Node.js environments:

1. Non-blocking: Uses asynchronous APIs to avoid blocking the JavaScript thread.
2. Memory Efficient: Avoids buffering entire files in RAM; it processes data in a streaming fashion.
3. Resource Conscious: Prefers opening input files one at a time to avoid hitting OS limits on simultaneous open file handles.

yazl handles directory structures in two ways:

1. Implicit Directories: When you add a file using a metadataPath like "parent/file.txt", yazl does not automatically create a directory entry for "parent/". It assumes the unzip client will handle the creation of parent directories implied by the file paths.
2. Explicit Empty Directories: If you need to include a directory that contains no files, you must explicitly call addEmptyDirectory().

If you use metadataPath with backslashes (\), yazl will automatically replace them with forward slashes (/) to ensure standard pathing.

Since version 3.3.0, yazl includes the Info-ZIP "universal timestamp" extended field (0x5455 or "UT") to encode mtime. This is the recommended modern encoding.

Benefits:

• Timezone is explicitly UTC (ideal for cloud/multi-timezone teams).
• Can encode the Unix epoch (1970) accurately.
• 1-second precision (vs. rounding to the nearest even second in DOS).

Trade-offs:

• Adds 9 bytes of metadata per entry.
• If you need to revert to the older DOS-only behavior, set forceDosTimestamp: true in your file options.

yazl automatically switches to the ZIP64 format when an archive exceeds the limits of the original ZIP specification. This occurs if:

• Files or the total archive size exceeds 2^32 - 2 bytes (~4GB).
• The archive contains more than 2^16 - 2 (65,534) files.

Note on Compatibility: While most modern zipfile readers support ZIP64, some tools like the Mac Archive Utility may not handle ZIP64 archives correctly. You can use the forceZip64Format option in the API to manually control this behavior.

The ZipFile class is the primary interface for creating ZIP archives. You instantiate it with new ZipFile() and then add files, buffers, or streams to it. The resulting archive is produced via the outputStream property, which is a readable stream. It is common practice to pipe this outputStream to a writable stream, such as one created by fs.createWriteStream().

Important Note on Streams: Avoid using both .on('data') and .pipe() on the outputStream simultaneously, as this can cause incorrect behavior in certain Node.js versions.

const yazl = require('yazl');
const fs = require('fs');

const zipfile = new yazl.ZipFile();
zipfile.addFile('/path/to/real/file.txt', 'relative/path/in/zip.txt');
zipfile.end();

zipfile.outputStream.pipe(fs.createWriteStream('archive.zip'));

Adds a file to the zip archive using a provided Buffer.

Compatibility Note: If you need to create zip files that are compatible with the bug in 7-Zip 9.20 (which incorrectly handles General Purpose Bit 3), use addBuffer() for all entries in your archive.

Size Limitation: To prevent issues with zlib inflation and Node.js buffer limits, yazl enforces that the provided buffer must be at most 0x3fffffff bytes long.

Options:

• All options available in addFile() (except size).

const buf = Buffer.from('hello world');
zipfile.addBuffer(buf, 'hello.txt', { compress: true });

To avoid holding many system resources open for long periods, it is recommended to use addReadStreamLazy() instead of addReadStream(). This method takes a function that provides the read stream only when needed.

Usage: Pass a function getReadStreamFunction(cb) where cb is a callback that receives (err, readStream). If an error is passed to the callback, it will be emitted from the ZipFile object.

Options:

• All options available in addFile().
• size: The expected size in bytes. If provided, yazl will emit an error if the actual number of bytes read from the stream does not match this value.

zipfile.addReadStreamLazy("path/in/archive.txt", function(cb) {
  var readStream = getTheReadStreamSomehow();
  cb(null, readStream);
});

Adds an entry to the zip file that represents a directory. This is required if you want the archive to contain a directory that has no files inside it.

Note: If the metadataPath does not end with a /, yazl will automatically append one.

Options:

• mtime: Modification time.
• mode: Unix permissions (default 040775).
• forceDosTimestamp: Boolean.

zipfile.addEmptyDirectory('my-empty-folder/');