agaziper

Capacitor plugin for zipping and unzipping files.

Framework Support

This plugin is fully compatible with Ionic and Angular applications using Capacitor. It provides a seamless native interface for zip operations on both iOS and Android platforms.

Install

npm install agaziper

npx cap sync

## Usage

### Download and Extract a Zip File

Here is an example of how to download a zip file using `fetch` and `@capacitor/filesystem`, then extract it using `agaziper`.

```typescript
import { Filesystem, Directory } from '@capacitor/filesystem';
import { Zip, ArchiveType } from 'agaziper';

const downloadAndExtract = async (url: string) => {
  try {
    // 1. Download the file
    const response = await fetch(url);
    const blob = await response.blob();

    // 2. Convert Blob to Base64
    const convertBlobToBase64 = (blob: Blob) => new Promise<string>((resolve, reject) => {
        const reader = new FileReader();
        reader.onerror = reject;
        reader.onload = () => {
            resolve(reader.result as string);
        };
        reader.readAsDataURL(blob);
    });

    const base64Data = await convertBlobToBase64(blob);
    const fileName = 'archive.zip';

    // 3. Save the file to the device
    const savedFile = await Filesystem.writeFile({
      path: fileName,
      data: base64Data,
      directory: Directory.Cache
    });

    // 4. Get the absolute path for destination
    // We'll extract to a subdirectory named 'extracted' in the Cache directory
    const extractPath = 'extracted';
    const destDir = await Filesystem.getUri({
        path: extractPath,
        directory: Directory.Cache
    });
    
    // 5. Extract the archive
    const result = await Zip.extract({
      source: savedFile.uri,
      destination: destDir.uri,
      type: ArchiveType.ZIP, // Optional, will auto-detect if omitted
      overwrite: true
    });

    console.log('Extraction complete:', result);
    console.log('Extracted to:', result.path);
    console.log('Files:', result.files);

  } catch (error) {
    console.error('Error downloading or extracting:', error);
  }
};

API

• compress(...)
• extract(...)
• isValidArchive(...)
• zip(...)
• unzip(...)
• isValidZip(...)
• Interfaces
• Enums

compress(...)

compress(options: CompressOptions) => Promise<CompressResult>

Compress files or directories into an archive

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | CompressOptions |

Returns: Promise<CompressResult>

extract(...)

extract(options: ExtractOptions) => Promise<ExtractResult>

Extract files from an archive

| Param | Type | | ------------- | --------------------------------------------------------- | | options | ExtractOptions |

Returns: Promise<ExtractResult>

isValidArchive(...)

isValidArchive(options: { source: string; type?: ArchiveType; }) => Promise<{ valid: boolean; }>

Check if a file is a valid archive

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | { source: string; type?: ArchiveType; } |

Returns: Promise<{ valid: boolean; }>

zip(...)

zip(options: ZipOptions) => Promise<ZipResult>

| Param | Type | | ------------- | ------------------------------------------------- | | options | ZipOptions |

Returns: Promise<ZipResult>

unzip(...)

unzip(options: UnzipOptions) => Promise<UnzipResult>

| Param | Type | | ------------- | ----------------------------------------------------- | | options | UnzipOptions |

Returns: Promise<UnzipResult>

isValidZip(...)

isValidZip(options: { source: string; }) => Promise<{ valid: boolean; }>

| Param | Type | | ------------- | -------------------------------- | | options | { source: string; } |

Returns: Promise<{ valid: boolean; }>

Interfaces

CompressResult

| Prop | Type | Description | | --------------- | --------------------------------------------------- | ----------------------------------------- | | path | string | Path to the created archive file | | size | number | Size of the created archive file in bytes | | fileCount | number | Number of files compressed | | type | ArchiveType | Archive type used |

CompressOptions

| Prop | Type | Description | | ---------------------- | --------------------------------------------------- | ------------------------------------------------ | | source | string | Source file or directory path to compress | | destination | string | Destination path for the archive file | | type | ArchiveType | Archive type (zip, tar, tar.gz, tar.bz2, tar.xz) | | password | string | Optional password for zip encryption (ZIP only) | | compressionLevel | number | Compression level (1-9, default: 6) |

ExtractResult

| Prop | Type | Description | | --------------- | --------------------------------------------------- | ------------------------------- | | path | string | Path where files were extracted | | fileCount | number | Number of files extracted | | files | string[] | List of extracted file paths | | type | ArchiveType | Archive type that was extracted |

ExtractOptions

| Prop | Type | Description | | ----------------- | --------------------------------------------------- | ------------------------------------------------------ | | source | string | Source archive file path | | destination | string | Destination directory path for extraction | | type | ArchiveType | Archive type - if not specified, will be auto-detected | | password | string | Password for encrypted zip files (ZIP only) | | overwrite | boolean | Overwrite existing files (default: true) |

ZipResult

ZipOptions

UnzipResult

UnzipOptions

Enums

ArchiveType

| Members | Value | | ------------- | ---------------------- | | ZIP | 'zip' | | TAR | 'tar' | | TAR_GZ | 'tar.gz' | | TAR_BZ2 | 'tar.bz2' | | TAR_XZ | 'tar.xz' |