Archive Creation

/**
 * Create empty AdmZip instance
 * @param {object} [options] - Configuration options
 */
function AdmZip(options);

const AdmZip = require("adm-zip");

// Create empty archive
const zip = new AdmZip();

// Create with options
const zip = new AdmZip({
    noSort: false,
    method: 8 // deflate compression
});

/**
 * Add file content to archive
 * @param {string} entryName - File path within archive (use "/" for directories)
 * @param {Buffer|string} content - File content as buffer or string
 * @param {string} [comment] - Optional file comment
 * @param {number|object} [attr] - File attributes, permissions, or Stats object
 * @returns {ZipEntry} Created entry object
 */
addFile(entryName, content, comment, attr);

const zip = new AdmZip();

// Add text file
const textContent = "Hello, World!";
zip.addFile("hello.txt", Buffer.from(textContent, "utf8"), "Greeting file");

// Add JSON data
const jsonData = { name: "John", age: 30 };
zip.addFile("data.json", Buffer.from(JSON.stringify(jsonData), "utf8"));

// Add binary data
const binaryData = Buffer.from([0x89, 0x50, 0x4E, 0x47]); // PNG header
zip.addFile("image.png", binaryData);

// Add directory (empty folder)
zip.addFile("documents/", null, "Document folder");

// Add file with permissions
zip.addFile("script.sh", Buffer.from("#!/bin/bash\necho 'Hello'", "utf8"), "", 0o755);

// Add file with file stats
const fs = require("fs");
const stats = fs.statSync("./existing-file.txt");
const content = fs.readFileSync("./existing-file.txt");
zip.addFile("copied-file.txt", content, "", stats);

/**
 * Add local file from disk
 * @param {string} localPath - Path to local file on disk
 * @param {string} [zipPath] - Directory path within archive
 * @param {string} [zipName] - Custom filename within archive
 * @param {string} [comment] - Optional file comment
 */
addLocalFile(localPath, zipPath, zipName, comment);

const zip = new AdmZip();

// Add file to root of archive
zip.addLocalFile("./document.pdf");

// Add file to specific directory in archive
zip.addLocalFile("./photo.jpg", "images/");

// Add file with custom name
zip.addLocalFile("./config.json", "settings/", "app-config.json");

// Add file with comment
zip.addLocalFile("./readme.txt", "", "", "Project documentation");

// Add multiple files
const filesToAdd = [
    { path: "./src/app.js", zipPath: "source/" },
    { path: "./package.json", zipPath: "", name: "pkg.json" },
    { path: "./docs/api.md", zipPath: "documentation/" }
];

filesToAdd.forEach(file => {
    zip.addLocalFile(file.path, file.zipPath, file.name);
});

/**
 * Add local file asynchronously
 * @param {object|string} options - Options object or local file path
 * @param {string} options.localPath - Path to local file
 * @param {string} [options.zipPath] - Directory path within archive
 * @param {string} [options.zipName] - Custom filename within archive
 * @param {string} [options.comment] - Optional file comment
 * @param {function} callback - Callback function (error, success)
 */
addLocalFileAsync(options, callback);

const zip = new AdmZip();

// Simple async file addition
zip.addLocalFileAsync("./large-file.dat", function(err, success) {
    if (err) {
        console.error("Error adding file:", err);
        return;
    }
    console.log("File added successfully");
});

// Async with options
zip.addLocalFileAsync({
    localPath: "./data/export.csv",
    zipPath: "reports/",
    zipName: "monthly-export.csv",
    comment: "Monthly data export"
}, function(err, success) {
    if (err) {
        console.error("Failed to add file:", err);
    } else {
        console.log("CSV file added to reports folder");
    }
});

/**
 * Add entire local directory recursively
 * @param {string} localPath - Path to local directory
 * @param {string} [zipPath] - Directory path within archive
 * @param {RegExp|function} [filter] - File filter function or regex pattern
 */
addLocalFolder(localPath, zipPath, filter);

const zip = new AdmZip();

// Add entire directory
zip.addLocalFolder("./src");

// Add directory to specific path in archive
zip.addLocalFolder("./assets", "resources/");

// Add directory with file filtering (regex)
zip.addLocalFolder("./project", "", /\.(js|json|md)$/);

// Add directory with custom filter function
zip.addLocalFolder("./data", "dataset/", function(filename) {
    // Only include .csv and .json files, exclude temp files
    return /\.(csv|json)$/.test(filename) && !filename.includes('temp');
});

// Filter to exclude node_modules and .git
zip.addLocalFolder("./project", "", function(filename) {
    return !filename.includes('node_modules') && !filename.includes('.git');
});

/**
 * Add local directory asynchronously
 * @param {string} localPath - Path to local directory
 * @param {function} callback - Callback function (success, error)
 * @param {string} [zipPath] - Directory path within archive
 * @param {RegExp|function} [filter] - File filter function or regex
 */
addLocalFolderAsync(localPath, callback, zipPath, filter);

/**
 * Enhanced async directory addition with options
 * @param {object|string} options - Options object or local directory path
 * @param {string} options.localPath - Path to local directory
 * @param {string} [options.zipPath] - Directory path within archive
 * @param {RegExp|function} [options.filter] - File filter
 * @param {function|string} [options.namefix] - Filename processing function
 * @param {function} callback - Callback function (error, success)
 */
addLocalFolderAsync2(options, callback);

const zip = new AdmZip();

// Basic async directory addition
zip.addLocalFolderAsync("./src", function(success, error) {
    if (error) {
        console.error("Error adding folder:", error);
        return;
    }
    console.log("Folder added successfully");
}, "source/");

// Enhanced async with options
zip.addLocalFolderAsync2({
    localPath: "./content",
    zipPath: "site/",
    filter: /\.(html|css|js|png|jpg)$/,
    namefix: "latin1" // handle special characters
}, function(error, success) {
    if (error) {
        console.error("Failed:", error);
    } else {
        console.log("Content folder added");
    }
});

// Custom name fixing function
zip.addLocalFolderAsync2({
    localPath: "./uploads",
    zipPath: "media/",
    namefix: function(filename) {
        // Convert to lowercase and replace spaces
        return filename.toLowerCase().replace(/\s+/g, '-');
    }
}, function(error, success) {
    console.log(success ? "Success" : "Failed");
});

/**
 * Add local directory with Promise support
 * @param {string} localPath - Path to local directory
 * @param {object} [props] - Additional properties
 * @param {string} [props.zipPath] - Directory path within archive
 * @param {RegExp|function} [props.filter] - File filter
 * @param {function|string} [props.namefix] - Filename processing
 * @returns {Promise<AdmZip>} Promise resolving to the zip instance
 */
addLocalFolderPromise(localPath, props);

const zip = new AdmZip();

// Basic promise usage
zip.addLocalFolderPromise("./documents")
    .then(() => {
        console.log("Documents added successfully");
        return zip.writeZipPromise("./archive.zip");
    })
    .catch(error => {
        console.error("Error:", error);
    });

// Using async/await
async function createArchive() {
    try {
        const zip = new AdmZip();
        
        await zip.addLocalFolderPromise("./src", {
            zipPath: "source/",
            filter: /\.(js|ts|json)$/
        });
        
        await zip.addLocalFolderPromise("./docs", {
            zipPath: "documentation/",
            namefix: filename => filename.toLowerCase()
        });
        
        await zip.writeZipPromise("./release.zip");
        console.log("Archive created successfully");
    } catch (error) {
        console.error("Failed to create archive:", error);
    }
}

/**
 * Write archive to file
 * @param {string} [targetFileName] - Output file path (optional if opened from file)
 * @param {function} [callback] - Optional callback function
 */
writeZip(targetFileName, callback);

/**
 * Write archive to file with Promise support
 * @param {string} targetFileName - Output file path
 * @param {object} [props] - Additional properties
 * @param {boolean} [props.overwrite] - Overwrite existing file (default: true)
 * @param {boolean} [props.perm] - Set file permissions
 * @returns {Promise<void>} Promise that resolves when file is written
 */
writeZipPromise(targetFileName, props);

const zip = new AdmZip();
zip.addFile("readme.txt", Buffer.from("Hello World", "utf8"));

// Synchronous write
zip.writeZip("./output.zip");

// With callback
zip.writeZip("./output.zip", function(err) {
    if (err) {
        console.error("Write failed:", err);
    } else {
        console.log("Archive saved successfully");
    }
});

// Promise-based write
zip.writeZipPromise("./output.zip")
    .then(() => console.log("Archive saved"))
    .catch(err => console.error("Save failed:", err));

// Promise with options
zip.writeZipPromise("./protected.zip", {
    overwrite: false,
    perm: 0o600
}).then(() => {
    console.log("Protected archive created");
});

/**
 * Get archive as Buffer
 * @param {function} [onSuccess] - Success callback (makes operation async)
 * @param {function} [onFail] - Failure callback
 * @param {function} [onItemStart] - Item processing start callback
 * @param {function} [onItemEnd] - Item processing end callback
 * @returns {Buffer|null} Archive buffer (sync) or null (async)
 */
toBuffer(onSuccess, onFail, onItemStart, onItemEnd);

/**
 * Get archive as Buffer with Promise support
 * @returns {Promise<Buffer>} Promise resolving to archive buffer
 */
toBufferPromise();

const zip = new AdmZip();
zip.addFile("data.txt", Buffer.from("Sample data", "utf8"));

// Synchronous buffer generation
const buffer = zip.toBuffer();
console.log("Archive size:", buffer.length);

// Write buffer to file manually
const fs = require("fs");
fs.writeFileSync("./manual.zip", buffer);

// Asynchronous with callbacks
zip.toBuffer(
    function(buffer) {
        console.log("Archive generated, size:", buffer.length);
        // Send buffer over network, save to database, etc.
    },
    function(error) {
        console.error("Failed to generate archive:", error);
    },
    function(filename) {
        console.log("Processing:", filename);
    },
    function(filename) {
        console.log("Completed:", filename);
    }
);

// Promise-based buffer generation
zip.toBufferPromise()
    .then(buffer => {
        console.log("Archive ready, size:", buffer.length);
        return sendToServer(buffer);
    })
    .catch(error => {
        console.error("Buffer generation failed:", error);
    });