# luau-unzip

<a href="https://discord.gg/ATVVsNNv3u"><img alt="Discord" src="https://img.shields.io/discord/385151591524597761?style=plastic&logo=discord&color=%235865F2" /></a>
<a href="https://pesde.daimond113.com/packages/0x5eal/unzip"><img alt="Pesde" src="https://img.shields.io/badge/pesde-0x5eal/unzip-F19D1E?&style=plastic&logo=data:image/svg%2bxml;base64, " /></a>
<a href="https://lune-org.github.io/docs"><img alt="Lune" src="https://raw.githubusercontent.com/0x5eal/semver-luau/refs/heads/main/.lune/assets/powered-by-lune.svg" /></a>

A Luau library to unzip and extract files from ZIP archives. The implementation is based on the [PKZip APPNOTE v6.3.9](https://www.pkware.com/documents/APPNOTE/APPNOTE-6.3.9.TXT).

## 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

```luau
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](https://github.com/luau-lang/luau/releases/tag/0.629) (specifically requires 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](https://nixos.wiki/wiki/Nix_Installation_Guide). 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](https://pesde.dev) 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.

[MIT]: https://compeydev.mit-license.org
