Stability: 2 - Stable

The Zip module is used for compressing and extracting files, and supports encrypted ZIP archives.

ZIP functionality is provided by zip4j. Read its docs for more details.

$zip.zipDir(dir, dest[, options])

• dir {string} Folder path to compress. Subfolders will be included.

• dest {string} Output zip file path

• options {object} Optional. Options include (see also the full option list below):

  Compression options:

  • password {string} Password for encryption. If set without specifying encryption method, AES is used by default.
  • compressionMethod {string} Compression method: COMP_STORE store only (no compression), COMP_DEFLATE compress (default)
  • encryptionMethod {string} Encryption method: ENC_NO_ENCRYPTION (default), ENC_METHOD_STANDARD, ENC_METHOD_AES
  • compressionLevel {number} Compression level 0~9. 0 means no compression; 9 means best compression (slower). Before v8.7 default was 0; since v8.7 default is 5.
  • aesKeyStrength {string} AES key strength: AES_STRENGTH_128, AES_STRENGTH_192, AES_STRENGTH_256
  • readHiddenFiles {boolean} Whether to include hidden files when zipping folders
  • includeRootFolder {boolean} Whether to include the parent folder in the zip. Default true
  • rootFolderInZip {string} Root folder name inside the zip. If none exists, create it.

Compress all files/folders under dir and write to dest.

A simple example compressing a folder:

// Folder to compress
let dir = "./zipExample2/";
if (!$files.exists(dir)) {
  // Create folder if not exists
  $files.create(dir);
}
// Create a file (add more files/folders to see the effect)
$files.create($files.join(dir, "test.js"));
// Output zip path
let zipFile = $files.join(dir, "zip_no_encryption.zip");
// Remove same-name file
$files.remove(zipFile);
// Zip
$zip.zipDir(dir, zipFile);
log("Zip finished. Zip path: " + zipFile);

Encrypted ZIP example:

// Folder to compress
let dir = "./zipExample2/";
if (!$files.exists(dir)) {
    // Create folder if not exists
    $files.create(dir);
}
// Create a file (add more files/folders to see the effect)
 $files.create($files.join(dir, "test.js"));
// Output zip path
let encryptedZipFile = $files.join(dir, "zip_encrypted.zip");
$files.remove(encryptedZipFile); // Remove same-name file
// Zip
$zip.zipDir(dir, encryptedZipFile, {
    password: "Auto.js Pro", // Password
    compressionLevel: 5, // Compression level
    aesKeyStrength: 'AES_STRENGTH_256', // AES strength
    readHiddenFiles: false, // Do not include hidden files
    includeRootFolder: false, // Do not include parent folder
    rootFolderInZip: "test_root" // Add a root folder inside ZIP
});
log("Encrypted zip finished. Zip path: " + encryptedZipFile);

$zip.zipFile(file, dest[, options])

• file {string} Single file path to compress
• dest {string} Output zip file path
• options {object} Options. See Compression options

Compress one file file to dest.

let path = "./zipExample/test.js";
if (!$files.exists(path)) {
  $files.create(path);
}
let zipFilePath = "./zipExample/test.zip";
$zip.zipFile(path, zipFilePath);
log("Single-file zip finished. Zip path: " + zipFilePath);

$zip.zipFiles(fileList, dest[, options])

• fileList {string[]} Array of file paths to compress
• dest {string} Output zip file path
• options {object} Options. See Compression options

Compress multiple files fileList to dest. fileList must not contain folders.

let dir = "./zipExample3/";
if (!$files.exists(dir)) {
  $files.create(dir);
}
let fileList = ["file1.js", "file2.js", "file3.js"].map((p) =>
  $files.join(dir, p),
);
fileList.forEach((file) => {
  $files.create(file);
});

let zipMultiFile = $files.join(dir, "zip_multiple_files.zip");
$files.remove(zipMultiFile); // Remove same-name file
$zip.zipFiles(fileList, zipMultiFile); // Zip
log("Multi-file zip finished. Zip path: " + zipMultiFile);

$zip.unzip(zipFile, dest[, options])

• zipFile {string} Zip file path to extract
• dest {string} Destination folder
• options {object} Optional. See Extraction options

Extract the zip file. If dest does not exist, it will be created and contents extracted into it. If dest already exists, a subfolder named after zipFile will be created under dest and contents extracted there.

// Prepare an encrypted zip
let dir = "./zipExample2/";
if (!$files.exists(dir)) {
  $files.create(dir);
}
// Output zip path
let encryptedZipFile = $files.join(dir, "zip_encrypted.zip");
$files.remove(encryptedZipFile); // Remove same-name file
// Zip
$zip.zipDir(dir, encryptedZipFile, {
  password: "Auto.js Pro", // Zip password
});

$zip.unzip(encryptedZipFile, "./zipExample5", {
  password: "Auto.js Pro", // Unzip password
});
log("Encrypted zip extracted successfully. Path: " + "./zipExample5/");

$zip.open(file)

• file {string} Zip file path
• Returns {ZipFile} ZipFile object

Open a zip file and return a ZipFile object for further operations.

ZipFile

The object returned by $zip.open(), used to add/remove files, read file headers, extract, etc.

ZipFile.getPath()

• Returns {string} Path

Get the current zip file path.

let path = "./test.zip";
let zipFile = $zip.open(path);
log(zipFile.getPath());
// Output: "./test.zip"

ZipFile.isValidZipFile()

• Returns {boolean} Whether the zip is valid

Whether the current zip is a valid zip archive.

Returns false if the path is not a zip archive or the file does not exist.

ZipFile.setPassword(password)

• password {string} Password

If the archive is encrypted, you must set the correct password before extracting encrypted entries.

Extracting encrypted archives without a password will throw. If the chosen zip file does not exist, calling this may throw ZipException.

ZipFile.isEncrypted()

• Returns {boolean} Whether encrypted

Whether the current archive is encrypted.

ZipFile.addFile(file[, options])

• file {string} Local file path
• options {object} Optional. See Compression options

Add a file to the zip.

let zipFile = $zip.open("./app.apk");
zipFile.addFile(file);

ZipFile.addFiles(fileList, options)

• fileList {string[]} Array of local file paths to add
• options {object} Optional. See Compression options

Add multiple files to the zip.

ZipFile.addFolder(folder[, options])

• folder {string} Folder path
• options {object} Optional. See Compression options

Add a folder to the zip.

Note

Do not add the parent directory of the zip file itself, otherwise it may cause an infinite recursive add loop.

A simple backup example:

let zipFile = "/sdcard/scripts.zip";
// Zip file path
let zip = $zip.open(zipFile);
log("Backup started (time depends on number of scripts)");
// Add current folder into zip
zip.addFolder("./");
log("Backup finished. Zip path: " + zipFile);

ZipFile.removeFile(file)

• file {string} File to remove

Remove the specified file from the zip. It finds the file header then removes the entry. If the file does not exist, it throws.

If the zip is a split archive, this will throw because the ZIP spec does not allow updating split archives.

let zipFile = $zip.open("./app.apk");
zipFile.removeFile("res/drawable/logo.png");

ZipFile.extractFile(file, dest[, options, newFileName])

• file {string} File to extract
• dest {string} Destination path
• options {Object} Optional. See Extraction options
• newFileName {string} New file name after extraction (optional)

Extract a specific file entry to the destination. If the destination is invalid, it throws.

ZipFile.extractAll(dest{, options})

• dest {string} Destination folder
• options {Object} Optional. See Extraction options

Extract all files to dest.

let zip = $zip.open("./test.zip");
zip.addFiles(["./test.js", "./test.txt"]);
zip.extractAll("./test");

ZipFile.getFileHeader(file)

• file {string} File path inside the zip
• Returns {FileHeader}

Get the file header of a specific entry. Includes CRC, encryption status, comment, etc.

ZipFile.getFileHeaders()

• Returns {Array<FileHeader>}

Get file headers for all entries. Includes CRC, encryption status, comment, etc.

Compression options

options {object} includes:

• aesKeyStrength {string} AES key strength: AES_STRENGTH_128, AES_STRENGTH_192, AES_STRENGTH_256
• compressionLevel {number} Compression level 0~9. 0 means no compression; 9 means best compression (slower). Before v8.7 default was 0; since v8.7 default is 5.
• compressionMethod {string} COMP_STORE store only (no compression), COMP_DEFLATE compress (default)
• defaultFolderPath {string} Default folder path inside zip when compressing/adding files
• encryptionMethod {string} ENC_NO_ENCRYPTION (default), ENC_METHOD_STANDARD, ENC_METHOD_AES
• fileNameInZip {string} Entry path/name inside zip when compressing/adding files
• includeRootFolder {boolean} Whether to include the parent folder in the zip. Default true
• password {string} Password for encryption. If set without specifying encryption method, AES is used by default.
• readHiddenFiles {boolean} Whether to include hidden files when zipping folders
• rootFolderInZip {string} Root folder name inside the zip. If none exists, create it.

Extraction options

options {object} includes:

• ignoreAttribute {string[]} File attributes to ignore when writing extracted files to disk:
  • alls All attributes
  • archive Archive attribute
  • dateTime Date/time
  • hidden Hidden
  • readOnly Read-only
  • system System file