Registry / serialization / yazl

yazl

JSON →
library3.3.1jsnpmunverified

yazl (yet another zip library) is a Node.js-specific package designed for creating ZIP archives with an emphasis on asynchronous operations, controlled memory usage, and avoiding excessive file handle consumption. It provides a stream-based API, allowing users to pipe the output directly to a writable stream without buffering entire files in memory. Key features include adding files from the filesystem, buffers, or readable streams, with options for compression, custom modification times, and file permissions. It aims to be non-blocking and efficient, making it suitable for server-side archiving tasks. The current stable version is 3.3.1. Release cadence is infrequent, focusing on stability and targeted improvements rather than rapid feature additions. It differentiates itself by its stream-first, async design, which is crucial for high-performance Node.js applications.

serializationdata
npm install yazl
github ↗package ↗
INSTALL
IMPORT
SIG · YAZL
Y
yazl
serializationjavascriptv3.3.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZipFile
✓ const { ZipFile } = require('yazl');
✗ import { ZipFile } from 'yazl';
yazl is a CommonJS-only package. ESM imports are not supported.
yazl (full module)
✓ const yazl = require('yazl');
✗ import yazl from 'yazl';
This imports the entire module object, which contains the ZipFile class.
addFile / addBuffer / addReadStreamLazy
✓ zipfile.addFile('realPath', 'metadataPath');
These are methods of a ZipFile instance, not directly importable symbols.

Demonstrates how to create a zip archive using yazl, adding files from the filesystem and a buffer, and piping the resulting output stream to a physical .zip file. It also includes cleanup for the temporary files.

const fs = require('fs'); const path = require('path'); const { ZipFile } = require('yazl'); const outputPath = path.join(__dirname, 'output.zip'); const file1Path = path.join(__dirname, 'file1.txt'); const file2DirPath = path.join(__dirname, 'temp_files'); const file2Path = path.join(file2DirPath, 'nested_file.txt'); // Create dummy files and directory for the example to work fs.writeFileSync(file1Path, 'This is the content of file1.txt.'); fs.mkdirSync(file2DirPath, { recursive: true }); fs.writeFileSync(file2Path, 'Content for nested_file.txt inside a directory.'); const zipfile = new ZipFile(); // Add files from the filesystem zipfile.addFile(file1Path, 'file1.txt', { compress: true }); zipfile.addFile(file2Path, 'directory/nested_file.txt', { compressionLevel: 9 }); // Add content directly from a buffer zipfile.addBuffer(Buffer.from('Hello from a buffer! This will be zipped.'), 'hello_buffer.txt', { fileComment: 'A dynamically added buffer file', mtime: new Date() }); // Pipe the output stream to a file zipfile.outputStream.pipe(fs.createWriteStream(outputPath)) .on('close', function() { console.log(`Zip archive created successfully at ${outputPath}`); // Clean up dummy files and directory fs.unlinkSync(file1Path); fs.unlinkSync(file2Path); fs.rmdirSync(file2DirPath); }) .on('error', function(err) { console.error('Error writing zip file:', err); }); // Call end() after all files have been added to finalize the archive zipfile.end();
Debug
Known issues
breakingSince version 3.3.0, yazl includes the Info-ZIP "universal timestamp" extended field (0x5455) for `mtime` encoding. While generally an improvement, applications relying on byte-for-byte identical zip metadata or specific older zip tool compatibility might need to explicitly disable this feature.
fix
To revert to pre-3.3.0 timestamp encoding (DOS timestamp only), set `forceDosTimestamp: true` in the options object for `addFile`, `addBuffer`, or `addReadStreamLazy` methods.
affects: >=3.3.0
gotchayazl only supports adding individual files (from disk, buffer, or readable streams), not entire directories directly. To add a directory structure, you must recursively iterate through its contents and call `addFile` for each file.
fix
Manually traverse the directory tree using `fs.readdir` and `fs.stat` (or `glob` packages) and call `zipfile.addFile(realPath, metadataPath)` for each individual file, ensuring correct `metadataPath` construction.
affects: >=1.0.0
gotchaThe `metadataPath` argument (the path inside the zip file) has strict validation rules. It must not be blank, cannot start with a `/` or `/[A-Za-z]:\/` (absolute path indicators), and cannot contain `..` path segments.
fix
Always provide a relative, non-blank path for `metadataPath`, e.g., 'my-folder/my-file.txt'. Backslashes `\` in `metadataPath` will be automatically converted to forward slashes `/`.
affects: >=1.0.0
gotchaFailing to call `zipfile.end()` after all files have been added will result in an incomplete or corrupted zip archive. The `end()` method is responsible for writing the central directory and the archive footer, which are crucial for a valid ZIP file.
fix
Ensure `zipfile.end()` is called only once, after all `addFile`, `addBuffer`, or `addReadStreamLazy` operations have been initiated. For asynchronous file additions, consider using a counter or Promise.allSettled to track completion before calling `end()`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Metadata path must not be blank
An empty string was provided for the `metadataPath` argument when adding a file or buffer.
fix
Ensure `metadataPath` is a non-empty string representing the desired path for the item within the zip file.
Error: Metadata path must not start with '/' or /[A-Za-z]:\/
The `metadataPath` provided begins with an absolute path indicator (e.g., `/my/file.txt` or `C:/my/file.txt`), which is invalid for paths within a zip archive.
fix
Provide a relative path for `metadataPath`, such as `my-folder/my-file.txt`.
The `callback` argument must be of type function
When using `addReadStreamLazy`, a direct Readable stream object was passed instead of a callback function that resolves to a Readable stream.
fix
Wrap the stream source in a function: `zipfile.addReadStreamLazy('stdin.txt', cb => cb(null, process.stdin));`
Output zip file is corrupted or incomplete / unzip error: bad zipfile offset (common symptom)
The `zipfile.end()` method was not called, preventing the central directory and archive footer from being written to the output stream.
fix
Confirm that `zipfile.end()` is explicitly called only after all files have been fully added to the zipfile instance. For asynchronous operations, ensure all additions are complete before calling `end()`.
Upgrade
Version history
3.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
38 hits · last 30 days
node
32
OpenAI (training)
1
Resources
githubhttps://github.com/thejoshwolfe/yazl ↗
packagehttps://www.npmjs.com/package/yazl ↗
yazl — npm install yazl · libregistry