The yazl npm package is a library for creating ZIP archives in a straightforward and efficient manner. It allows you to add files, directories, and even raw data to a ZIP archive, and then output the archive to a writable stream.
Creating a ZIP Archive
This feature allows you to create a ZIP archive and add a file to it. The code sample demonstrates how to add a file from the filesystem to the ZIP archive and then write the archive to a file named 'output.zip'.
const yazl = require('yazl');
const fs = require('fs');
let zipfile = new yazl.ZipFile();
zipfile.addFile('path/to/file.txt', 'file.txt');
zipfile.outputStream.pipe(fs.createWriteStream('output.zip')).on('close', function() {
console.log('ZIP file created successfully');
});
zipfile.end();Adding a Directory to a ZIP Archive
This feature allows you to add an entire directory to a ZIP archive. The code sample demonstrates how to recursively add all files and subdirectories from a specified directory to the ZIP archive.
const yazl = require('yazl');
const fs = require('fs');
const path = require('path');
let zipfile = new yazl.ZipFile();
function addDirectoryToZip(zipfile, dirPath, zipPath) {
fs.readdirSync(dirPath).forEach(file => {
const fullPath = path.join(dirPath, file);
const zipFilePath = path.join(zipPath, file);
if (fs.statSync(fullPath).isDirectory()) {
addDirectoryToZip(zipfile, fullPath, zipFilePath);
} else {
zipfile.addFile(fullPath, zipFilePath);
}
});
}
addDirectoryToZip(zipfile, 'path/to/directory', 'directory');
zipfile.outputStream.pipe(fs.createWriteStream('output.zip')).on('close', function() {
console.log('ZIP file created successfully');
});
zipfile.end();Adding Raw Data to a ZIP Archive
This feature allows you to add raw data to a ZIP archive. The code sample demonstrates how to create a buffer from a string and add it to the ZIP archive as a file named 'hello.txt'.
const yazl = require('yazl');
const fs = require('fs');
let zipfile = new yazl.ZipFile();
let rawData = Buffer.from('Hello, world!', 'utf-8');
zipfile.addBuffer(rawData, 'hello.txt');
zipfile.outputStream.pipe(fs.createWriteStream('output.zip')).on('close', function() {
console.log('ZIP file created successfully');
});
zipfile.end();The archiver package is a versatile library for creating ZIP and other archive formats. It offers a higher-level API compared to yazl and supports additional formats like TAR. Archiver is more feature-rich but may be more complex to use for simple ZIP creation tasks.
The adm-zip package is another library for handling ZIP archives. It provides both creation and extraction functionalities, making it a more comprehensive solution compared to yazl, which focuses solely on ZIP creation. ADM-ZIP is user-friendly and suitable for both simple and complex ZIP operations.
The node-stream-zip package is designed for working with ZIP archives in a streaming manner. It is particularly useful for handling large ZIP files efficiently. While yazl focuses on creating ZIP files, node-stream-zip excels in reading and extracting them, making it a complementary tool rather than a direct competitor.
yet another zip library for node. For unzipping, see yauzl.
Design principles:
var yazl = require("yazl");
var zipfile = new yazl.ZipFile();
zipfile.addFile("file1.txt", "file1.txt");
// (add only files, not directories)
zipfile.addFile("path/to/file.txt", "path/in/zipfile.txt");
// pipe() can be called any time after the constructor
zipfile.outputStream.pipe(fs.createWriteStream("output.zip")).on("close", function() {
console.log("done");
});
// alternate apis for adding files:
zipfile.addReadStream(process.stdin, "stdin.txt", {
mtime: new Date(),
mode: parseInt("0100664", 8), // -rw-rw-r--
});
zipfile.addBuffer(new Buffer("hello"), "hello.txt", {
mtime: new Date(),
mode: parseInt("0100664", 8), // -rw-rw-r--
});
// call end() after all the files have been added
zipfile.end();
No parameters. Nothing can go wrong.
Adds a file from the file system at realPath into the zipfile as metadataPath.
Typically metadataPath would be calculated as path.relative(root, realPath).
Unzip programs would extract the file from the zipfile as metadataPath.
realPath is not stored in the zipfile.
A valid metadataPath must not be blank.
If a metadataPath contains "\\" characters, they will be replaced by "/" characters.
After this substitution, a valid metadataPath must not start with "/" or /[A-Za-z]:\//,
and must not contain ".." path segments.
File paths must not end with "/".
options may be omitted or null and has the following structure and default values:
{
mtime: stats.mtime,
mode: stats.mode,
compress: true,
forceZip64Format: false,
}
Use mtime and/or mode to override the values
that would normally be obtained by the fs.Stats for the realPath.
The mode is the unix permission bits and file type.
The mtime and mode are stored in the zip file in the fields "last mod file time",
"last mod file date", and "external file attributes".
yazl does not store group and user ids in the zip file.
If compress is true, the file data will be deflated (compression method 8).
If compress is false, the file data will be stored (compression method 0).
If forceZip64Format is true, yazl will use ZIP64 format in this entry's Data Descriptor
and Central Directory Record regardless of if it's required or not (this may be useful for testing.).
Otherwise, yazl will use ZIP64 format where necessary.
Internally, fs.stat() is called immediately in the addFile function,
and fs.createReadStream() is used later when the file data is actually required.
Throughout adding and encoding n files with addFile(),
the number of simultaneous open files is O(1), probably just 1 at a time.
Adds a file to the zip file whose content is read from readStream.
See addFile() for info about the metadataPath parameter.
options may be omitted or null and has the following structure and default values:
{
mtime: new Date(),
mode: parseInt("0100664", 8),
compress: true,
forceZip64Format: false,
size: 12345, // example value
}
See addFile() for the meaning of mtime, mode, compress, and forceZip64Format.
If size is given, it will be checked against the actual number of bytes in the readStream,
and an error will be emitted if there is a mismatch.
Note that yazl will .pipe() data from readStream, so be careful using .on('data').
In certain versions of node, .on('data') makes .pipe() behave incorrectly.
Adds a file to the zip file whose content is buffer.
See below for info on the limitations on the size of buffer.
See addFile() for info about the metadataPath parameter.
options may be omitted or null and has the following structure and default values:
{
mtime: new Date(),
mode: parseInt("0100664", 8),
compress: true,
forceZip64Format: false,
}
See addFile() for the meaning of mtime, mode, compress, and forceZip64Format.
This method has the unique property that General Purpose Bit 3 will not be used in the Local File Header.
This doesn't matter for unzip implementations that conform to the Zip File Spec.
However, 7-Zip 9.20 has a known bug where General Purpose Bit 3 is declared an unsupported compression method
(note that it really has nothing to do with the compression method.).
See issue #11.
If you would like to create zip files that 7-Zip 9.20 can understand,
you must use addBuffer() instead of addFile() or addReadStream() for all entries in the zip file
(and addEmptyDirectory() is fine too).
Note that even when yazl provides the file sizes in the Local File Header,
yazl never uses ZIP64 format for Local File Headers due to the size limit on buffer (see below).
In order to require the ZIP64 format for a local file header,
the provided buffer parameter would need to exceed 0xfffffffe in length.
Alternatively, the buffer parameter might not exceed 0xfffffffe in length,
but zlib compression fails to compress the buffer and actually inflates the data to more than 0xfffffffe in length.
Both of these scenarios are not allowed by yazl, and those are enforced by a size limit on the buffer parameter.
According to this zlib documentation,
the worst case compression results in "an expansion of at most 13.5%, plus eleven bytes".
Furthermore, some configurations of Node.js impose a size limit of 0x3fffffff on every Buffer object.
Running this size through the worst case compression of zlib still produces a size less than 0xfffffffe bytes,
Therefore, yazl enforces that the provided buffer parameter must be at most 0x3fffffff bytes long.
Adds an entry to the zip file that indicates a directory should be created, even if no other items in the zip file are contained in the directory. This method is only required if the zip file is intended to contain an empty directory.
See addFile() for info about the metadataPath parameter.
If metadataPath does not end with a "/", a "/" will be appended.
options may be omitted or null and has the following structure and default values:
{
mtime: new Date(),
mode: 040775,
}
See addFile() for the meaning of mtime and mode.
Indicates that no more files will be added via addFile(), addReadStream(), or addBuffer().
options may be omitted or null and has the following structure and default values:
{
forceZip64Format: false,
}
If forceZip64Format is true, yazl will include the ZIP64 End of Central Directory Locator
and ZIP64 End of Central Directory Record regardless of whether or not they are required
(this may be useful for testing.).
Otherwise, yazl will include these structures if necessary.
If specified and non-null, finalSizeCallback is given the parameters (finalSize)
sometime during or after the call to end().
finalSize is of type Number and can either be -1
or the guaranteed eventual size in bytes of the output data that can be read from outputStream.
Note that finalSizeCallback is usually called well before outputStream has piped all its data;
this callback does not mean that the stream is done.
If finalSize is -1, it means means the final size is too hard to guess before processing the input file data.
This will happen if and only if the compress option is true on any call to addFile(), addReadStream(), or addBuffer(),
or if addReadStream() is called and the optional size option is not given.
In other words, clients should know whether they're going to get a -1 or a real value
by looking at how they are using this library.
The call to finalSizeCallback might be delayed if yazl is still waiting for fs.Stats for an addFile() entry.
If addFile() was never called, finalSizeCallback will be called during the call to end().
It is not required to start piping data from outputStream before finalSizeCallback is called.
finalSizeCallback will be called only once, and only if this is the first call to end().
A readable stream that will produce the contents of the zip file.
It is typical to pipe this stream to a writable stream created from fs.createWriteStream().
Internally, large amounts of file data are piped to outputStream using pipe(),
which means throttling happens appropriately when this stream is piped to a slow destination.
Data becomes available in this stream soon after calling one of addFile(), addReadStream(), or addBuffer().
Clients can call pipe() on this stream at any time,
such as immediately after getting a new ZipFile instance, or long after calling end().
As a reminder, be careful using both .on('data') and .pipe() with this stream.
In certain versions of node, you cannot use both .on('data') and .pipe() successfully.
jsDate is a Date instance.
Returns {date: date, time: time}, where date and time are unsigned 16-bit integers.
yazl automatically uses ZIP64 format to support files and archives over 2^32 - 2 bytes (~4GB) in size
and to support archives with more than 2^16 - 2 (65534) files.
(See the forceZip64Format option in the API above for more control over this behavior.)
ZIP64 format is necessary to exceed the limits inherent in the original zip file format.
ZIP64 format is supported by most popular zipfile readers, but not by all of them. Notably, the Mac Archive Utility does not understand ZIP64 format (as of writing this), and will behave very strangely when presented with such an archive.
The Zip File Spec leaves a lot of flexibility up to the zip file creator. This section explains and justifies yazl's interpretation and decisions regarding this flexibility.
This section is probably not useful to yazl clients, but may be interesting to unzip implementors and zip file enthusiasts.
All values related to disk numbers are 0,
because yazl has no multi-disk archive support.
(The exception being the Total Number of Disks field in
the ZIP64 End of Central Directory Locator, which is always 1.)
Always 0x033f == (3 << 8) | 63, which means UNIX (3)
and made from the spec version 6.3 (63).
Note that the "UNIX" and has implications in the External File Attributes.
Usually 20, meaning 2.0. This allows filenames to be UTF-8 encoded.
When ZIP64 format is used, some of the Version Needed to Extract values will be 45, meaning 4.5.
When this happens, there may be a mix of 20 and 45 values throughout the zipfile.
Bit 8 is always set.
Filenames are always encoded in utf8, even if the result is indistinguishable from ascii.
Bit 3 is usually set in the Local File Header.
To support both a streaming input and streaming output api,
it is impossible to know the crc32 before processing the file data.
When bit 3 is set, data Descriptors are given after each file data with this information, as per the spec.
But remember a complete metadata listing is still always available in the central directory record,
so if unzip implementations are relying on that, like they should,
none of this paragraph will matter anyway.
Even so, some popular unzip implementations do not follow the spec.
The Mac Archive Utility requires Data Descriptors to include the optional signature,
so yazl includes the optional data descriptor signature.
When bit 3 is not used, the Mac Archive Utility requires there to be no data descriptor, so yazl skips it in that case.
Additionally, 7-Zip 9.20 does not seem to support bit 3 at all
(see issue #11).
All other bits are unset.
Always 0.
The "apparently an ASCII or text file" bit is always unset meaning "apparently binary".
This kind of determination is outside the scope of yazl,
and is probably not significant in any modern unzip implementation.
Always stats.mode << 16.
This is apparently the convention for "version made by" = 0x03xx (UNIX).
Note that for directory entries (see addEmptyDirectory()),
it is conventional to use the lower 8 bits for the MS-DOS directory attribute byte.
However, the spec says this is only required if the Version Made By is DOS,
so this library does not do that.
When adding a metadataPath such as "parent/file.txt", yazl does not add a directory entry for "parent/",
because file entries imply the need for their parent directories.
Unzip clients seem to respect this style of pathing,
and the zip file spec does not specify what is standard in this regard.
In order to create empty directories, use addEmptyDirectory().
.npmignore from npm package. pull #22metadataPath can have \ characters now; they will be replaced with /. issue #18addBuffer() calls. issue #13addEmptyDirectory().options is now optional for addReadStream() and addBuffer().FAQs
yet another zip library for node
The npm package yazl receives a total of 926,354 weekly downloads. As such, yazl popularity was classified as popular.
We found that yazl demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.