File and Folder Operations

/**
 * Add a file to the ZIP archive or retrieve existing file(s)
 * @param path - File path within the ZIP
 * @param data - File content (optional, for adding files)
 * @param options - File options (optional)
 * @returns JSZip instance (when adding), JSZipObject (when retrieving single file), or JSZipObject[] (when retrieving with RegExp)
 */
file(path: string): JSZipObject | null;
file(path: RegExp): JSZipObject[];
file<T extends InputType>(path: string, data: InputByType[T] | Promise<InputByType[T]>, options?: JSZipFileOptions): this;
file<T extends InputType>(path: string, data: null, options?: JSZipFileOptions & { dir: true }): this;

/**
 * Remove a file or folder from the ZIP archive
 * @param path - Path to remove
 * @returns JSZip instance for chaining
 */
remove(path: string): JSZip;

import JSZip from "jszip";

const zip = new JSZip();

// Add text file
zip.file("readme.txt", "This is a text file");

// Add binary data
zip.file("image.png", imageBuffer, {binary: true});

// Add file with metadata
zip.file("document.pdf", pdfData, {
  date: new Date("2023-01-01"),
  comment: "Important document",
  compression: "DEFLATE"
});

// Retrieve a file
const textFile = zip.file("readme.txt");
if (textFile) {
  const content = await textFile.async("string");
}

// Find files matching pattern
const imageFiles = zip.file(/\.(png|jpg|gif)$/i);

// Remove a file
zip.remove("unwanted.txt");

/**
 * Create a folder or navigate to an existing folder
 * @param name - Folder name or path
 * @returns New JSZip instance representing the folder, or null if not found
 */
folder(name: string): JSZip | null;

/**
 * Find folders matching a pattern
 * @param name - RegExp pattern to match folder names
 * @returns Array of JSZipObject instances representing matching folders
 */
folder(name: RegExp): JSZipObject[];

const zip = new JSZip();

// Create a folder
const imagesFolder = zip.folder("images");

// Add files to the folder
imagesFolder.file("logo.png", logoData, {base64: true});
imagesFolder.file("banner.jpg", bannerData, {binary: true});

// Create nested folders
const docsFolder = zip.folder("documents");
const publicDocs = docsFolder.folder("public");
publicDocs.file("readme.md", "# Public Documentation");

// Navigate to existing folder
const existingFolder = zip.folder("images");
if (existingFolder) {
  existingFolder.file("new-image.png", newImageData);
}

// Find folders matching pattern
const allFolders = zip.folder(/.*docs.*/i);

/**
 * Iterate over files at the current folder level
 * @param callback - Function called for each file
 */
forEach(callback: (relativePath: string, file: JSZipObject) => void): void;

/**
 * Filter files based on a predicate function
 * @param predicate - Function to test each file
 * @returns Array of JSZipObject instances matching the predicate
 */
filter(predicate: (relativePath: string, file: JSZipObject) => boolean): JSZipObject[];

const zip = new JSZip();

// Add various files...
zip.file("readme.txt", "Documentation");
zip.file("data.json", JSON.stringify({key: "value"}));
zip.folder("images").file("logo.png", logoData);

// Iterate over all files
zip.forEach((relativePath, file) => {
  console.log(`File: ${relativePath}, Size: ${file.name.length}`);
});

// Filter for text files
const textFiles = zip.filter((relativePath, file) => {
  return relativePath.endsWith('.txt') || relativePath.endsWith('.md');
});

// Filter for files in specific folder
const imageFiles = zip.filter((relativePath, file) => {
  return relativePath.startsWith('images/') && !file.dir;
});

// Filter by file size or date
const recentFiles = zip.filter((relativePath, file) => {
  return file.date > new Date('2023-01-01');
});

/**
 * Create a deep copy of the JSZip instance
 * @returns New JSZip instance with copied files and settings
 */
clone(): JSZip;

const zip = new JSZip();
zip.file("readme.txt", "Hello World");
zip.file("data.json", JSON.stringify({key: "value"}));

// Create a copy of the ZIP instance
const zipCopy = zip.clone();

// Modify the copy without affecting the original
zipCopy.file("new-file.txt", "This is only in the copy");
zipCopy.remove("readme.txt");

// Original ZIP is unchanged
console.log(zip.files["readme.txt"]); // Still exists
console.log(zip.files["new-file.txt"]); // undefined

// Copy has the modifications
console.log(zipCopy.files["readme.txt"]); // undefined (removed)
console.log(zipCopy.files["new-file.txt"]); // Exists in copy

/**
 * Collection of all files and folders in the ZIP
 * Key is the full path, value is the JSZipObject
 */
files: {[key: string]: JSZipObject};

/**
 * Global comment for the ZIP file
 */
comment: string | null;

/**
 * Current working directory path within the ZIP
 */
root: string;

const zip = new JSZip();

// Add files and folders
zip.file("readme.txt", "Hello");
zip.folder("docs").file("guide.md", "# Guide");

// Access all files directly
console.log(Object.keys(zip.files)); // ["readme.txt", "docs/", "docs/guide.md"]

// Access specific file object
const readmeFile = zip.files["readme.txt"];
console.log(readmeFile.name); // "readme.txt"
console.log(readmeFile.dir);  // false

// Set global ZIP comment
zip.comment = "Archive created with JSZip";

// Check current root (useful when working with folder instances)
const docsFolder = zip.folder("docs");
console.log(docsFolder.root); // "docs/"

interface JSZipFileOptions {
  /** Set to true if data is base64 encoded */
  base64?: boolean;
  /** Set to true for binary data, false for text */
  binary?: boolean;
  /** Last modification date */
  date?: Date;
  /** Compression method */
  compression?: Compression;
  /** Compression options for DEFLATE */
  compressionOptions?: CompressionOptions | null;
  /** File comment */
  comment?: string;
  /** Set to true for optimized binary strings */
  optimizedBinaryString?: boolean;
  /** Create intermediate folders automatically */
  createFolders?: boolean;
  /** Set to true to create a directory entry */
  dir?: boolean;
  /** DOS file permissions */
  dosPermissions?: number | null;
  /** UNIX file permissions */
  unixPermissions?: number | string | null;
}

// Add text file with specific date
zip.file("changelog.txt", changelogText, {
  date: new Date("2023-12-01"),
  comment: "Version 1.0 changes"
});

// Add binary file with compression
zip.file("archive.zip", binaryData, {
  binary: true,
  compression: "DEFLATE",
  compressionOptions: { level: 6 }
});

// Add base64 encoded image
zip.file("photo.jpg", base64ImageData, {
  base64: true,
  createFolders: true  // Creates 'photos/' folder if needed
});

// Create directory with permissions
zip.file("scripts/", null, {
  dir: true,
  unixPermissions: "755"
});

// Add file with UNIX permissions
zip.file("run.sh", scriptContent, {
  unixPermissions: 0o755,
  comment: "Executable script"
});