# ZIP Archiver

Links: [Home](../index.md)

ZIP file manipulation module powered by the [JSZip](https://stuk.github.io/jszip/) library. For a dependency-free alternative that also supports TAR, GZIP, 7Z, and RAR, see [Packer](packer.md).

## Loading the Module

```js
Application.require("archiver/zip").then(function (ZipArchiver) {
    // ZipArchiver is a constructor function
});
```

**Dependency:** `thirdparty/archive/jszip` (loaded automatically)

## API

### `ZipArchiver([zipFile])`

Create a new archive or open existing data.

- `zipFile` *(Uint8Array | ArrayBuffer | Blob)* -- optional, existing ZIP data
- Returns: `ApplicationPrototype` instance (sync) or `Promise<app>` if `zipFile` is provided

### Instance Methods

| Method | Returns | Description |
|---|---|---|
| `addFile(path, data)` | jszip ref | Add a file to the archive |
| `remove(path)` | jszip ref | Remove a file from the archive |
| `folder(path)` | `app` | Create a folder in the archive |
| `getFile(path, data, asText)` | `Promise` | Get file content. `asText=true` returns string |
| `files()` | `Object` | Get all file entries in the archive |
| `forEach(callback)` | -- | Iterate through all files |
| `root([rootPath])` | `string` | Get or set the archive root path |
| `generate(type)` | `Promise` | Generate archive. `type`: `'blob'` or `'uint8array'` (default) |

## Use Cases

### Create a ZIP with multiple files

```js
Application.require("archiver/zip").then(function (ZipArchiver) {
    var archive = ZipArchiver();

    archive.addFile('hello.txt', 'Hello World');
    archive.addFile('data/config.json', '{"key": "value"}');
    archive.folder('images');

    archive.generate('blob').then(function (blob) {
        var url = URL.createObjectURL(blob);
        var a = document.createElement('a');
        a.href = url;
        a.download = 'files.zip';
        a.click();
    });
});
```

### Open an existing ZIP and list contents

```js
Application.require("archiver/zip").then(function (ZipArchiver) {
    // fileData is a Uint8Array from a file input or fetch
    ZipArchiver(fileData).then(function (archive) {
        archive.forEach(function (relativePath, file) {
            console.log(relativePath, file);
        });

        archive.getFile('readme.txt', null, true).then(function (text) {
            console.log('README:', text);
        });
    });
});
```

### Generate a ZIP from form data

```js
Application.require("archiver/zip").then(function (ZipArchiver) {
    var archive = ZipArchiver();

    document.querySelectorAll('textarea').forEach(function (el) {
        archive.addFile(el.name + '.txt', el.value);
    });

    archive.generate('blob').then(function (blob) {
        // Upload the blob via fetch
        var fd = new FormData();
        fd.append('archive', blob, 'submission.zip');
        fetch('/api/upload', { method: 'POST', body: fd });
    });
});
```

## Notes

- This module depends on the JSZip library. If you prefer zero dependencies, use [Packer](packer.md) instead.
- The `generate('blob')` method wraps the result in a `Blob` with MIME type `application/zip`.