zip-lib
zip and unzip library for node.
Install
npm install zip-lib
Quick Start
Zip
You can use zip-lib to compress files or folders.
Zip single file
const zl = require("zip-lib");
zl.archiveFile("path/to/file.txt", "path/to/target.zip").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
Zip single folder
const zl = require("zip-lib");
zl.archiveFolder("path/to/folder", "path/to/target.zip").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
Unzip
const zl = require("zip-lib");
zl.extract("path/to/target.zip", "path/to/target").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
Advanced usage
Zip multiple files and folders
const zl = require("zip-lib");
const zip = new zl.Zip();
zip.addFile("path/to/file.txt");
zip.addFolder("path/to/folder");
zip.archive("path/to/target.zip").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
The path/to/folder
directory is as follows:
path/to/folder
.
├── dir1
│ ├── file.ext
├── dir2
└── file_in_root.ext
And the generated path/to/target.zip
archive file directory will be as follows:
path/to/target.zip
.
├── file.txt
├── dir1
│ ├── file.ext
├── dir2
└── file_in_root.ext
Zip with metadata
const zl = require("zip-lib");
const zip = new zl.Zip();
zip.addFile("path/to/file.txt", "renamedFile.txt");
zip.addFile("path/to/file2.txt", "folder/file.txt");
zip.addFolder("path/to/folder", "new folder");
zip.archive("path/to/target.zip").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
The path/to/folder
directory is as follows:
path/to/folder
.
├── dir1
│ ├── file.ext
├── dir2
└── file_in_root.ext
And the generated path/to/target.zip
archive file directory will be as follows:
path/to/target.zip
.
├── renamedFile.txt
├── folder
│ ├── file.txt
│── new folder
├── dir1
│ ├── file.ext
├── dir2
└── file_in_root.ext
Unzip with entry callback
Using onEntry
callback we can know the current progress of extracting and control the extraction operation. See IExtractOptions.
const zl = require("zip-lib");
const unzip = new zl.Unzip({
onEntry: function (event) {
console.log(event.entryCount, event.entryName);
}
})
unzip.extract("path/to/target.zip", "path/to/target").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
Unzip and exclude specified entries
The following code shows how to exclude the __MACOSX
folder in the zip file when extracting. See IExtractOptions.
const zl = require("zip-lib");
const unzip = new zl.Unzip({
onEntry: function (event) {
if (/^__MACOSX\//.test(event.entryName)) {
event.preventDefault();
}
}
})
unzip.extract("path/to/target.zip", "path/to/target").then(function () {
console.log("done");
}, function (err) {
console.log(err);
});
Cancel zip
If the cancel
method is called after the archive is complete, nothing will happen.
const zl = require("zip-lib");
const zip = new zl.Zip();
zip.addFile("path/to/file.txt");
zip.archive("path/to/target.zip").then(function () {
console.log("done");
}, function (err) {
if (err.name === "Canceled") {
console.log("cancel");
} else {
console.log(err);
}
});
zip.cancel();
Cancel unzip
If the cancel
method is called after the extract is complete, nothing will happen.
const zl = require("zip-lib");
const unzip = new zl.Unzip();
unzip.extract("path/to/target.zip", "path/to/target").then(function () {
console.log("done");
}, function (err) {
if (err.name === "Canceled") {
console.log("cancel");
} else {
console.log(err);
}
});
unzip.cancel();
API
Method: archiveFile
archiveFile(file, zipFile, [options])
Compress a single file to zip.
file
: StringzipFile
: Stringoptions?
: IZipOptions (optional)
Returns: Promise<viod>
Method: archiveFolder
archiveFolder(folder, zipFile, [options])
Compress all the contents of the specified folder to zip.
folder
: StringzipFile
: Stringoptions?
: IZipOptions (optional)
Returns: Promise<void>
extract(zipFile, targetFolder, [options])
Extract the zip file to the specified location.
Returns: Promise<void>
Class: Zip
Compress files or folders to a zip file.
Constructor: new Zip([options])
Method: addFile(file, [metadataPath])
Adds a file from the file system at realPath into the zipfile as metadataPath.
file
: StringmetadataPath?
: String (optional) - Typically metadataPath would be calculated as path.relative(root, realPath). A valid metadataPath must not start with /
or /[A-Za-z]:\//
, and must not contain ..
.
Returns: void
Method: addFolder(folder, [metadataPath])
Adds a folder from the file system at realPath into the zipfile as metadataPath.
folder
: StringmetadataPath?
: String (optional) - Typically metadataPath would be calculated as path.relative(root, realPath). A valid metadataPath must not start with /
or /[A-Za-z]:\//
, and must not contain ..
.
Returns: void
Method: archive(zipFile)
Generate zip file.
Returns: Promise<viod>
Method: cancel()
Cancel compression. If the cancel
method is called after the archive is complete, nothing will happen.
Returns: void
Class: Unzip
Extract the zip file.
Constructor: new Unzip([options])
Method: extract(zipFile, targetFolder)
Extract the zip file to the specified location.
zipFile
: StringtargetFolder
: String
Returns: Promise<void>
Method: cancel()
If the cancel
method is called after the extract is complete, nothing will happen.
Returns: void
Options: IZipOptions
Object
followSymlinks?
: Boolean (optional) - Indicates how to handle when the given path is a symbolic link. The default value is false
.
true
: add the target of the symbolic link to the zip.
false
: add symbolic link itself to the zip.
Object
-
overwrite?
: String (optional) - If it is true, the target directory will be deleted before extract. The default value is false
.
-
symlinkAsFileOnWindows?
: Boolean (optional) - Extract symbolic links as files on Windows. This value is only available on Windows and ignored on other platforms. The default value is true
.
If true
, the symlink in the zip will be extracted as a normal file on Windows.
If false
, the symlink in the zip will be extracted as a symlink correctly on Windows, but an EPERM
error will be thrown under non-administrators.
⚠WARNING: On Windows, the default security policy allows only administrators to create symbolic links. If you set symlinkAsFileOnWindows
to false
and the zip contains symlink, be sure to run the code under the administrator, otherwise an EPERM
error will be thrown.
-
onEntry?
: Function (optional) - Called before an item is extracted.
Arguments:
event
: Object - Represents an event that an entry is about to be extracted.
entryName
: String (readonly) - Entry name.entryCount
: Number (readonly) - Total number of entries.preventDefault()
: Function - Prevent extracting current entry. This method can be used to prevent extraction of the current item. By calling this method we can control which items can be extracted.
License
Licensed under the MIT license.