zip-lib

A zip and unzip library for Node.js with promise-based APIs, support for compressing to Buffer or extracting from Buffer, and advanced features like entry filtering, cancellation, and symlink-aware handling.

Install

npm install zip-lib

Quick Start

• Zip
  • Zip single file
  • Zip single folder
• Unzip
• Advanced usage
  • Sets the compression level
  • Zip multiple files and folders
  • Zip with metadata
  • Unzip with entry callback
  • Unzip and exclude specified entries
  • Cancel zip
  • Cancel unzip
• API
  • Method: archiveFile
  • Method: archiveFolder
  • Method: extract
  • Class: Zip
  • Class: Unzip
  • Options: IZipOptions
  • Options: IExtractOptions
  • Event: IEntryEvent

Zip

You can use zip-lib to compress files or folders.

Zip single file

import * as zl from "zip-lib";

async function zipToFile() {
	try {
		await zl.archiveFile("path/to/file.txt", "path/to/target.zip");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

async function zipToBuffer() {
	try {
		const buffer = await zl.archiveFile("path/to/file.txt");
		console.log("done", buffer.byteLength);
	} catch (error) {
		console.error(error);
	}
}

Zip single folder

import * as zl from "zip-lib";

async function zipToFile() {
	try {
		await zl.archiveFolder("path/to/folder", "path/to/target.zip");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

async function zipToBuffer() {
	try {
		const buffer = await zl.archiveFolder("path/to/folder");
		console.log("done", buffer.byteLength);
	} catch (error) {
		console.error(error);
	}
}

Unzip

import * as zl from "zip-lib";

async function unzipFromFile() {
	try {
		await zl.extract("path/to/target.zip", "path/to/target");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

async function unzipFromBuffer(zipBuffer: Buffer) {
	try {
		await zl.extract(zipBuffer, "path/to/target");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

Advanced usage

Set the compression level

import * as zl from "zip-lib";

async function zipToFile() {
	try {
		await zl.archiveFolder("path/to/folder", "path/to/target.zip", {
			compressionLevel: 9,
		});
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

Zip multiple files and folders

import * as zl from "zip-lib";

async function zipToFile() {
	try {
		const zip = new zl.Zip();
		// Adds a file from the file system
		zip.addFile("path/to/file.txt");
		// Adds a folder from the file system, putting its contents at the root of the archive
		zip.addFolder("path/to/folder");
		// Generate the zip file.
		await zip.archive("path/to/target.zip");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

The path/to/folder directory is as follows:

path/to/folder
.
├── dir1
│   ├── file.ext
├── dir2
└── file_in_root.ext

And the contents of the generated path/to/target.zip archive will be as follows:

path/to/target.zip
.
├── file.txt
├── dir1
│   ├── file.ext
├── dir2
└── file_in_root.ext

Zip with metadata

import * as zl from "zip-lib";

async function zipToFile() {
	try {
		const zip = new zl.Zip();
		// Adds a file from the file system
		zip.addFile("path/to/file.txt", "renamedFile.txt");
		zip.addFile("path/to/file2.txt", "folder/file.txt");
		// Adds a folder from the file system and names it `new folder` within the archive
		zip.addFolder("path/to/folder", "new folder");
		// Generate the zip file.
		zip.archive("path/to/target.zip");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

The path/to/folder directory is as follows:

path/to/folder
.
├── dir1
│   ├── file.ext
├── dir2
└── file_in_root.ext

And the contents of the generated path/to/target.zip archive 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 the onEntry callback, we can track extraction progress and control the extraction process. See IExtractOptions.

import * as zl from "zip-lib";

async function unzipFromFile() {
	try {
		const unzip = new zl.Unzip({
			// Called before an item is extracted.
			onEntry: (event) => {
				console.log(event.entryCount, event.entryName);
			},
		});
		await unzip.extract("path/to/target.zip", "path/to/target");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

Unzip and exclude specified entries

The following code shows how to exclude the __MACOSX folder in the zip file when extracting. See IExtractOptions.

import * as zl from "zip-lib";

async function unzipFromFile() {
	try {
		const unzip = new zl.Unzip({
			// Called before an item is extracted.
			onEntry: (event) => {
				if (/^__MACOSX\//.test(event.entryName)) {
					// entry name starts with __MACOSX/
					event.preventDefault();
				}
			},
		});
		await unzip.extract("path/to/target.zip", "path/to/target");
		console.log("done");
	} catch (error) {
		console.error(error);
	}
}

Cancel zip

If the cancel method is called after the archive is complete, nothing will happen.

import * as zl from "zip-lib";

const zip = new zl.Zip();
async function zipToFile() {
	try {
		zip.addFile("path/to/file.txt");
		await zip.archive("path/to/target.zip");
		console.log("done");
	} catch (error) {
		if (error instanceof Error && error.name === "Canceled") {
			console.log("cancel");
		} else {
			console.log(error);
		}
	}
}

function cancel() {
	zip.cancel();
}

Cancel unzip

If the cancel method is called after the extract is complete, nothing will happen.

import * as zl from "zip-lib";

const unzip = new zl.Unzip();
async function unzipFromFile() {
	try {
		await unzip.extract("path/to/target.zip", "path/to/target");
		console.log("done");
	} catch (error) {
		if (error instanceof Error && error.name === "Canceled") {
			console.log("cancel");
		} else {
			console.log(error);
		}
	}
}

function cancel() {
	unzip.cancel();
}

API

Choose the API based on how much control you need:

• Use archiveFile, archiveFolder, and extract for simple one-shot operations.
• Use Zip when you need to add multiple files or folders, rename entries, or cancel compression.
• Use Unzip when you need to filter entries with onEntry or cancel extraction.

Method: archiveFile

Compress a single file.

archiveFile(file: string, options?: IZipOptions): Promise<Buffer>
archiveFile(file: string, zipFile: string, options?: IZipOptions): Promise<void>

• file: Path to the source file.
• zipFile: Optional output zip file path.
• options: Optional IZipOptions.

If zipFile is provided, the archive is written to disk and the method returns Promise<void>. Otherwise it returns the generated zip as a Buffer.

Method: archiveFolder

Compress all contents of a folder.

archiveFolder(folder: string, options?: IZipOptions): Promise<Buffer>
archiveFolder(folder: string, zipFile: string, options?: IZipOptions): Promise<void>

• folder: Path to the source folder.
• zipFile: Optional output zip file path.
• options: Optional IZipOptions.

If zipFile is provided, the archive is written to disk and the method returns Promise<void>. Otherwise it returns the generated zip as a Buffer.

Method: extract

Extract a zip file or zip buffer to a target folder.

extract(zipFile: string, targetFolder: string, options?: IExtractOptions): Promise<void>
extract(zipBuffer: Buffer, targetFolder: string, options?: IExtractOptions): Promise<void>

• zipFile: Path to a zip file on disk.
• zipBuffer: A zip archive in memory.
• targetFolder: Destination folder.
• options: Optional IExtractOptions.

Class: Zip

Build an archive incrementally when the top-level helpers are not enough.

Constructor

new Zip(options?: IZipOptions)

• options: Optional IZipOptions.

Methods

addFile(file: string, metadataPath?: string): void
addFolder(folder: string, metadataPath?: string): void
archive(): Promise<Buffer>
archive(zipFile: string): Promise<void>
cancel(): void

• addFile: Adds one file to the archive.
• addFolder: Adds one folder to the archive.
• metadataPath: Optional path stored inside the zip. A valid metadataPath must not start with / or /[A-Za-z]:\//, and must not contain ...
• archive(): Returns the zip as a Buffer.
• archive(zipFile): Writes the zip directly to disk.
• cancel(): Cancels compression. Calling it after completion has no effect.

Use metadataPath to rename files or folders inside the archive. It is typically computed with path.relative(root, realPath).

Class: Unzip

Extract with entry filtering and cancellation support.

Constructor

new Unzip(options?: IExtractOptions)

• options: Optional IExtractOptions.

Methods

extract(zipFile: string, targetFolder: string): Promise<void>
extract(zipBuffer: Buffer, targetFolder: string): Promise<void>
cancel(): void

• extract(...): Extracts from a zip file path or a Buffer.
• cancel(): Cancels extraction. Calling it after completion has no effect.

Options: IZipOptions

interface IZipOptions {
  followSymlinks?: boolean;
  compressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
}

• followSymlinks: Default false. If true, adds the target of a symbolic link. If false, adds the symbolic link itself.
• compressionLevel: Default 6. Use 0 to store file data without compression, or 1-9 to deflate file data.

Options: IExtractOptions

interface IExtractOptions {
  overwrite?: boolean;
  safeSymlinksOnly?: boolean;
  symlinkAsFileOnWindows?: boolean;
  onEntry?: (event: IEntryEvent) => void;
}

• overwrite: Default false. If true, deletes the target directory before extraction.
• safeSymlinksOnly: Default false. If true, refuses to create symlinks whose targets are outside the extraction root.
• symlinkAsFileOnWindows: Default true. On Windows, if true, symbolic links are extracted as regular files. If false, the library tries to create real symbolic links instead. This may fail with EPERM when the current process is not allowed to create symlinks. Keep the default for better compatibility; set this to false only if you want to preserve symlinks as symlinks.
• onEntry: Called before an entry is extracted. Use it to inspect or skip entries.

WARNING: On Windows, creating symbolic links may require administrator privileges, depending on system policy. If Windows Developer Mode is enabled, non-administrator processes can usually create symlinks as well. If symlinkAsFileOnWindows is false and the current process is not allowed to create symlinks, extraction may fail with EPERM.

Event: IEntryEvent

interface IEntryEvent {
  readonly entryName: string;
  readonly entryCount: number;
  preventDefault(): void;
}

• entryName: The current entry name.
• entryCount: The total number of entries in the archive.
• preventDefault(): Skips the current entry.

License

Licensed under the MIT license.