luau-unzip/docs/intro.md

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

Important

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

Important

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

findEocdPosition

Important

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.

Finds the position of the End of Central Directory (EoCD) signature in the ZIP file. This implementation is inspired by that of async_zip, a Rust library for parsing ZIP files asynchronously.

This method involves buffered reading in reverse and reverse linear searching along those buffers for the EoCD signature. As a result of the buffered approach, we reduce individual reads when compared to reading every single byte sequentially, by a factor of the buffer size (4 KB by default). The buffer size of 4 KB was arrived at because it aligns with many systems' page sizes, and also provides a good balance between read efficiency (not too small), memory usage (not too large) and CPU cache performance.

From my primitive benchmarks, this method is ~1.5x faster than the sequential approach.

Errors if the ZIP file is invalid.

ZipReader:findEocdPosition(): number

parseEocdRecord

Important

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 End of Central Directory record at the given position, usually located using the ZipReader:findEocdPosition.

Errors if the ZIP file is invalid.

ZipReader:parseEocdRecord(
	pos: number, -- The offset to the End of Central Directory record
): EocdRecord

parseCentralDirectory

Important

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

Important

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:extractDirectory 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:extract 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

EocdRecord

Important

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 parsed End of Central Directory record.

export type EocdRecord = {
	diskNumber: number,
	diskWithCD: number,
	cdEntries: number,
	totalCDEntries: number,
	cdSize: number,
	cdOffset: number,
	comment: string,
}

• diskNumber - The disk number
• diskWithCD - The disk number of the disk with the Central Directory
• cdEntries - The number of entries in the Central Directory
• totalCDEntries - The total number of entries in the Central Directory
• cdSize - The size of the Central Directory
• cdOffset - The offset of the Central Directory
• comment - The comment associated with the ZIP

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