luau-unzip

A Luau library to unzip and extract files from ZIP archives. The implementation is based on the PKZip APPNOTE v6.3.9.

Features

• Extract files from ZIP archives.
• Supports INFLATE and STORE decompression methods.
• Traverse and list archive contents.
• Retrieve archive statistics (file count, directory count, total size) and metadata.

Usage

local fs = require("@lune/fs")
local zip = require("luau-unzip")

-- Read the ZIP file
local file = fs.readFile("test.zip")

-- Load the ZIP archive
local reader = zip.load(buffer.fromstring(file))

-- Print directory structure
print("Directory structure:")
reader:walk(function(entry, depth)
    local prefix = string.rep("  ", depth)
    local suffix = if not entry.isDirectory
        then string.format(" (%d bytes), content: %s", entry.size, reader:extract(entry, { type = "text" }) :: string)
        else ""
    print(prefix .. entry.name .. suffix)
end)

-- List children of root directory
print("\nChildren of `/`:")
local assets = reader:listDirectory("/")
for _, entry in assets do
    print(string.format("    %s - %s (%s)", entry.name, if entry.isDirectory then "DIR" else "FILE", entry.method))
end

-- Get archive statistics
local stats = reader:getStats()
print("\nArchive stats:")
print("Files:", stats.fileCount)
print("Directories:", stats.dirCount)
print("Total size:", stats.totalSize, "bytes")

MSLV (Minimum Supported Luau Version)

This library requires at least Luau 0.669 (specifically requires the new require-by-string semantics, leading |, buffer built-in and idiv operator support).

Contributing

Contributions are heavily welcomed! We use Nix Flakes to manage a reproducible development environment. To get started, run exec nix develop -c $SHELL, after installing Nix. This is recommended for tests to be consistent, since we rely on InfoZIP implementations as sanity checks, although different distributions supply differently patched versions of it.

• We utilize pesde for package management. Run pesde install to install all dependencies.
• Before submitting a pull request, make sure you include comprehensive test cases for new features, and make sure all tests pass. Tests can be run with lune run tests. Refer to other test suites for examples of how to write your own tests.

License

This project is licensed under the MIT license.