README.md

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.629 (specifically requires leading |, buffer built-in and idiv operator support).

License

This project is licensed under the MIT license.