@gmaclennan/zip-fs

Extract individual files from a zipfile on disk

I wanted a way to read individual files efficiently from a zipfile without extracting the whole zipfile, and couldn't find an existing library with an API that I liked. The API is similar to the Node fs module. Uses yauzl under the hood. This might be slow for zip files with hundreds of entries, because it reads through the entire central directory before returning any files. The entire central directory is also stored in memory, but the zipfile is not stored in memory and files are streamed from disk, so memory usage should be low. See all the limitations of yauzl which also apply to this library.

Table of Contents

• Install
• Usage
• API
• Maintainers
• Contributing
• License

Install

npm install zip-fs

Usage

Works similarly to fs.createReadStream() and fs.readFile().

const ZipFs = require("zip-fs");

const zip = new ZipFs("my_zip_file.zip");

const rs = zip.createReadStream("a.txt", "utf8");
// Pipe to console
rs.pipe(process.stdout);
// Cleanup after
rs.on("end", () => zip.close());

API

const zip = new ZipFs(path[, cb])

Create a new random access zipfile reader for a zipfile at path. The optional callback will be called when the zipfile is ready to read, or if there is an error reading the zipfile. However, you do not need to wait for this in order to call the read methods.

zip.createReadStream(filename[, opts])

Returns a ReadableStream with the contents of the file filename in the zipfile. opts can be a string encoding option, or an object with the property opts.encoding. If no encoding is specified, then the raw buffer is returned.

zip.readFile(filename[, opts], callback)

callback is passed two arguments (err, data) where data is the contents of the file filename in the zipfile. opts can be a string encoding option, or an object with the property opts.encoding. If no encoding is specified, then the raw buffer is returned.

zip.readdir(path[, opts], callback)

Similar to fs.readdir(). Reads the contents of a directory in the zip file. The callback gets two arguments (err, files) where files is an array of the names of the files in the directory excluding '.' and '..'.

All paths are relative to the "root" of the zip file. readdir('/folder'), readdir('folder'), readdir('folder/') and readdir('./folder') are all functionally equivalent.

If options.withFileTypes is set to true, the files array will contain fs.Dirent objects.

zip.close(callback)

Close the zipfile (cleans up the file descriptor). callback is called once the file descriptor is actually closed.

Maintainers

@gmaclennan

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2019 Gregor MacLennan