Reference

`ZipEntry`

A single entry (a file or a directory) in a ZIP file, and its properties.

export type ZipEntry = {
	name: string,
	versionMadeBy: { software: string, os: MadeByOS },
	compressedSize: number,
	size: number,
	offset: number,
	timestamp: number,
	method: CompressionMethod,
	crc: number,
	isDirectory: boolean,
	isText: boolean,
	attributes: number,
	parent: ZipEntry?,
	children: { ZipEntry },
}

Properties

name - File path within ZIP, '/' suffix indicates directory
versionMadeBy - Version of software and OS that created the ZIP
compressedSize - Compressed size in bytes
size - Uncompressed size in bytes
offset - Absolute position of local header in ZIP
timestamp - MS-DOS format timestamp
method - Method used to compress the file
crc - CRC32 checksum of the uncompressed data
isDirectory - Whether the entry is a directory or not
isText - Whether the entry is plain ASCII text or binary
attributes - File attributes
parent - Parent directory entry, nil if entry is root
children - Children of the entry, if it was a directory, empty array for files

API

`new`

Info

This is a private API. It may be exported publicly, but try to avoid using this API, since it can have breaking changes at any time without warning.

ZipEntry.new(
	offset: number, -- Offset of the entry in the ZIP file
	name: string, -- File path within ZIP, '/' suffix indicates directory
	properties: ZipEntryProperties, -- Properties of the entry
): ZipEntry

`isSymlink`

Returns whether the entry is a symlink.

ZipEntry:isSymlink(): boolean

`getPath`

Resolves the path of the entry based on its relationship with other entries. It is recommended to use this method instead of accessing the name property directly, although they should be equivalent.

Warning

Never use this method when extracting files from the ZIP, since it can contain absolute paths (say /etc/passwd) referencing directories outside the current directory (say /tmp/extracted), causing unintended overwrites of files.

ZipEntry:getPath(): string

`getSafePath`

Resolves the path of the entry based on its relationship with other entries and returns it only if it is safe to use for extraction, otherwise returns nil.

ZipEntry:getSafePath(): string?

`sanitizePath`

Sanitizes the path of the entry, potentially losing information, but ensuring the path is safe to use for extraction.

ZipEntry:sanitizePath(): string

`compressionEfficiency`

Calculates the compression efficiency of the entry, or nil if the entry is a directory.

Uses the formula: round((1 - compressedSize / size) * 100) and outputs a percentage.

ZipEntry:compressionEfficiency(): number?

`isFile`

Returns whether the entry is a file, i.e., not a directory or symlink.

ZipEntry:isFile(): boolean

`unixMode`

Parses the entry's attributes to extract a UNIX mode, represented as a UnixMode.

ZipEntry:unixMode(): UnixMode?

Types

`MadeByOS`

The OS that created the ZIP.

export type MadeByOS = "FAT" | "AMIGA" | "VMS" | "UNIX" | "VM/CMS" | "Atari ST" | "OS/2" | "MAC" | "Z-System" | "CP/M" | "NTFS" | "MVS" | "VSE" | "Acorn RISCOS" | "VFAT" | "Alternate MVS" | "BeOS" | "TANDEM" | "OS/400" | "OS/X" | "Unknown"

`CompressionMethod`

The method used to compress the file:

STORE - No compression
DEFLATE - Compressed raw deflate chunks

export type CompressionMethod = "STORE" | "DEFLATE"

`ZipEntryProperties`

Info

This is a private type. It may be exported publicly, but try to avoid using it, since its definition can have a breaking change at any time without warning.

A set of properties that describe a ZIP entry. Used internally for construction of ZipEntry objects.

export type ZipEntryProperties = {
	versionMadeBy: number,
	compressedSize: number,
	size: number,
	attributes: number,
	timestamp: number,
	method: CompressionMethod?,
	crc: number,
}

versionMadeBy - Version of software and OS that created the ZIP
compressedSize - Compressed size in bytes
size - Uncompressed size in bytes
attributes - File attributes
timestamp - MS-DOS format timestamp
method - Method used
crc - CRC32 checksum of the uncompressed data

`UnixMode`

A object representation of the UNIX mode.

export type UnixMode = {
	perms: string,
	typeFlags: string,
}

perms - The permission octal
typeFlags - The type flags octal

`ZipReader`

The main class which represents a decoded state of a ZIP file, holding references to its entries. This is the primary point of interaction with the ZIP file's contents.

export type ZipReader = {
	data: buffer,
	comment: string,
	entries: { ZipEntry },
	directories: { [string]: ZipEntry },
	root: ZipEntry,
}

Properties

data - The buffer containing the raw bytes of the ZIP
comment - Comment associated with the ZIP
entries - The decoded entries present
directories - The directories and their respective entries
root - The entry of the root directory

API

`new`

Creates a new ZipReader instance from the raw bytes of a ZIP file.

Errors if the ZIP file is invalid.

ZipReader.new(
	data: buffer, -- The buffer containing the raw bytes of the ZIP
): ZipReader

`parseCentralDirectory`

Info

This is a private API. It may be exported publicly, but try to avoid using this API, since it can have breaking changes at any time without warning.

Parses the central directory of the ZIP file and populates the entries and directories fields. Used internally during initialization of the ZipReader.

Errors if the ZIP file is invalid.

ZipReader:parseCentralDirectory()

`buildDirectoryTree`

Info

This is a private API. It may be exported publicly, but try to avoid using this API, since it can have breaking changes at any time without warning.

Builds the directory tree from the entries. Used internally during initialization of the ZipReader.

ZipReader:buildDirectoryTree()

`findEntry`

Finds a ZipEntry by its path in the ZIP archive.

ZipReader:findEntry(
	path: string, -- Path to the entry to find
): ZipEntry?

`extract`

Extracts the specified ZipEntry from the ZIP archive. See ZipReader

for extracting directories.

ZipReader:extract(
	entry: ZipEntry, -- The entry to extract
	options: ExtractionOptions?, -- Options for the extraction
): buffer | string

`extractDirectory`

Extracts all the files in a specified directory, skipping any directory entries.

Errors if ZipReader

errors on an entry in the directory.

ZipReader:extractDirectory(
	path: string, -- The path to the directory to extract
	options: ExtractionOptions?, -- Options for the extraction
): { [string]: buffer } | { [string]: string }

`listDirectory`

Lists the entries within a specified directory path.

ZipReader:listDirectory(
	path: string, -- The path to the directory to list
): { ZipEntry }

`walk`

Recursively walks through the ZIP file, calling the provided callback for each entry with the current entry and its depth.

ZipReader:walk(
	callback: (entry: ZipEntry, depth: number) -> (), -- The function to call for each entry
)

`getStats`

Retrieves statistics about the ZIP file.

ZipReader:getStats(): ZipStatistics

Types

`ZipStatistics`

export type ZipStatistics = {
	fileCount: number,
	dirCount: number,
	totalSize: number,
}

fileCount - The number of files in the ZIP
dirCount - The number of directories in the ZIP
totalSize - The total size of all files in the ZIP