zip

Provides functions to zip and unzip files and directories securely. This module allows you to create zip archives from files or directories, and extract zip files to specified locations. It ensures that all file operations are performed within the secure boundaries defined by the Gingee framework. NOTE: path with leading slash indicates path from scope root, path without leading slash indicates path relative to the executing script IMPORTANT: Requires explicit permission to use the module. See docs/permissions-guide for more details.
Description:
  • Provides functions to zip and unzip files and directories securely. This module allows you to create zip archives from files or directories, and extract zip files to specified locations. It ensures that all file operations are performed within the secure boundaries defined by the Gingee framework. NOTE: path with leading slash indicates path from scope root, path without leading slash indicates path relative to the executing script IMPORTANT: Requires explicit permission to use the module. See docs/permissions-guide for more details.

Methods

(static) unzip(sourceScope, sourcePath, destScope, destPath) → {Promise.<void>}

Description:
  • Unzips a source zip file to a destination folder.
Example
const fs = require('fs'); // Gingee secure fs module
const zip = require('zip');
await zip.unzip(fs.BOX, '/path/to/source.zip', fs.BOX, '/path/to/destination');
if(fs.existsSync(fs.BOX, '/path/to/destination')) {
    console.log("Unzip operation completed successfully.");
}
Parameters:
Name Type Description
sourceScope string The scope of the source (fs.BOX or fs.WEB).
sourcePath string The path to the source zip file.
destScope string The scope of the destination (fs.BOX or fs.WEB).
destPath string The path to the destination folder.
Throws:
If the source zip file does not exist, or if the path traversal is detected, or if unzipping between scopes is attempted without the allowCrossOrigin option.
Type
Error
Returns:
A promise that resolves when the unzip operation is complete.
Type
Promise.<void>

(static) zip(scope, sourcePath, optionsopt) → {Promise.<Buffer>}

Description:
  • Zips a file or directory into an in-memory buffer. This function allows you to create a zip archive from a single file or an entire directory.
Example
const zip = require('zip');
const zipBuffer = await zip.zip(fs.BOX, '/path/to/source');
console.log(zipBuffer); // Outputs a Buffer containing the zip file data
Parameters:
Name Type Attributes Description
scope string The scope of the source (fs.BOX or fs.WEB).
sourcePath string The path to the file or directory to zip.
options object <optional>
 Optional settings.
Properties
Name Type Attributes Default Description
includeRootFolder boolean <optional>
 false If true and source is a directory, the directory itself is included at the root of the zip.
Throws:
If the source file or directory does not exist, or if the path traversal is detected.
Type
Error
Returns:
A promise that resolves with the zip file data as a Buffer.
Type
Promise.<Buffer>

(static) zipToFile(sourceScope, sourcePath, destScope, destPath, optionsopt) → {Promise.<void>}

Description:
  • Zips a file or directory to a destination zip file.
Example
const fs = require('fs'); // Gingee secure fs module
const zip = require('zip');
await zip.zipToFile(fs.BOX, '/path/to/source', fs.BOX, '/path/to/destination.zip');
if(fs.existsSync(fs.BOX, '/path/to/destination.zip')) {
    console.log("Zip file created successfully.");
}
Parameters:
Name Type Attributes Description
sourceScope string The scope of the source (fs.BOX or fs.WEB).
sourcePath string The path to the file or directory to zip.
destScope string The scope of the destination (fs.BOX or fs.WEB).
destPath string The path to the destination zip file.
options object <optional>
 Optional settings.
Properties
Name Type Attributes Default Description
includeRootFolder boolean <optional>
 false If true and source is a directory, the directory itself is included at the root of the zip.
Throws:
If the source file or directory does not exist, or if the path traversal is detected, or if zipping between scopes is attempted without the allowCrossOrigin option.
Type
Error
Returns:
A promise that resolves when the zip file is created.
Type
Promise.<void>