Why another one?!
I was working on a project and I needed something to zip and unzip local directories, so I went and searched on npm. I got quite a lot of results and all of them worked perfectly with files, but it when it came to directories each of them suffered from at least one of these three problems:
- not being asynchronous
- not being developer-friendly
- having odd behaviors (like zipping the whole path to root along with the directory)
So I wrote this to provide something free of the three problems!
npm install zip-local
The API comes in two versions: an asynchrnous version and a synchronous one. This gives you the choice to use whichever suitable for your application.
Zipping is done through
ZipLocal.zip or its synchronous version
ZipLocal.sync.zip by passing the path to the file or directory that needs to be zipped. In the asynchrnous version, the callback is passed an instance of
ZipExport object that contains the APIs to export the
zipped file. In the synchronous version, the
ZipExport object is returned.
Here's an example of asynchronous zipping,
var zipper = ;// zipping a filezipper;
and here's synchronous zipping,
var zipper = ;// zipping a file to memory without compressionvar buff = zippersync;// zipping a directory to disk with compression// the directory has the following structure// |-- hello-world.txt// |-- cpp// |-- hello-world.cpp// |-- java// |--hello-world.javazippersync;
Similiarly, unzipping is done through
ZipLocal.unzip or the synchronous
ZipLocal.sync.unzip by passing the path to the zip file. Like the zipping functions, these functions also use the
ZipExport object for exporting your unzipped file, but in case of exporting in memory the
memory function returns a
ZippedFS object instead of a buffer. This objects servers as a mini-filesystem for the unzipped file.
An example for asynchronous unzipping,
var zipper = ;zipper;
and the synchronous unzipping,
var zipper = ;// extract to an existing directoryzippersync;// export in memoryvar unzippedfs = zippersync;// logs ['hello-world.txt', 'cpp/hello-world.cpp', 'java/hello-world.java']console;// read file in buffervar buff = unzippedfs;
Zipping/Unzipping directly from memory
Imagine a serevr that needs to zip files it receives through its clients and send the zipped file to the client. When the file is received it resides in a buffer in memory, and to be able to zip it with the library (using the methods described so far) we must first save the file to local storage then zip it using its path so that the library would read it back to memory and zip it. This is definitely ineffcient and wasteful of the serevr's time and resources.
To solve this issue, starting from v0.2.0 you can zip/unzip a file directly from the buffer containing it in memory or zip an entire
ZippedFS object from a previously unzipped file. This could be done simply by passing the bufferto the zip/unzip methods or the
ZippedFS object to zip method instead of the path, and it works for both asynchronous and synchronous versions. Notice that in the case of zipping a buffer you'll need to pass an extra argument after the buffer which is the name of the file that will be included in the zip.
Here's an example implementing the above scenario that utilizes the ability to zip buffers :
var zipper = ;var net = ;var server = net;server;
Low Level Operations
While the library was designed to provide a simple high-level APIs to zip/unzip local directories and files, it's sometimes needed to perform some low level operations on the data before exporting it like adding new files to the zip or removing some files form an unzipped file before writing to disk. And since this library is based on JSZip which provides these low level operations, starting from v0.2.0 you can access the underlying
JSZip object and all its low level features through the method
ZipExport#lowLevel(). After you zip/unzip your data and acquire the
ZipExport object, you can call this method from it and retrieve the underlying
JSZip object and play around with it.
Here's an example that utilizes the low level operations to remove files and also utilizes the ability to zip
ZippedFS object. This code cleans zipped files from executables (namely .exe, .bat, and .sh):
var zipper = ;zipper;
read the API documentations for furthur details.