API Reference

Complete API documentation for ZIGX.

Core Functions

Compression

Function	Alias	Description
compress	bundle	Create an archive
compressData	-	Compress raw data

Extraction

Function	Alias	Description
extract	unbundle	Extract an archive
extractWithResult	unbundleWithResult	Extract with details
listFiles	list	List files in archive

Archive Info

Function	Description
getArchiveInfo	Get archive metadata
isValidArchive	Quick validity check

Validation

Function	Alias	Description
validate	verify	Validate archive
validateDetailed	verifyDetailed	Detailed validation
detectCorruption	-	Detect corruption type

Management

Function	Alias	Description
manager.update	update	Add/remove files
manager.repair	repair	Repair corrupted archive
manager.getMetadata	-	Get specific metadata value
manager.getAllMetadata	-	Get all metadata
manager.updateMetadata	-	Key-value CRUD for metadata
manager.setSignature	-	Sign an archive

Constants

// Library version
pub const VERSION = "0.0.1";

// Archive format version
pub const FORMAT_VERSION: u16 = 0x0001;  // v1

// Compression algorithm version
pub const COMPRESSION_VERSION: u8 = 1;

// File extension
pub const FILE_EXTENSION = ".zigx";

Types

CompressionLevel

pub const CompressionLevel = enum(u8) {
    none = 0,      // Store only, no compression
    fast = 1,      // Speed optimized (zstd 1)
    default = 3,   // Balanced (zstd 3)
    balanced = 6,  // Good balance (zstd 6)
    best = 19,     // High compression (zstd 19)
    ultra = 22,    // Maximum compression (zstd 22)
    
    // Fine-grained levels: level_2 through level_22
    
    pub fn custom(level: u8) CompressionLevel;  // Any level 1-22
    pub fn toInt(self: CompressionLevel) u8;    // Get raw value
    pub fn fromInt(level: u8) CompressionLevel; // From integer
};

CompressOptions

pub const CompressOptions = struct {
    allocator: Allocator,                    // Required
    include: ?[]const []const u8 = null,     // Files/directories
    exclude: []const []const u8 = &.{},      // Exclude patterns
    output_path: ?[]const u8 = null,         // Output file
    level: CompressionLevel = .best,         // Compression level
    compression_enabled: bool = true,        // Enable compression
    auto_metadata: bool = true,              // Auto-generate metadata
    progress_callback: ?ProgressCallback = null,    // Progress tracking
    progress_context: ?*anyopaque = null,           // Callback context
    adaptive_compression: bool = false,      // Auto-detect content type
    long_distance_matching: bool = false,    // Better for large files
};

ExtractOptions

pub const ExtractOptions = struct {
    archive_path: []const u8,                // Required
    output_dir: []const u8,                  // Required
    allocator: Allocator,                    // Required
    validate: bool = true,                   // Validate checksums
    overwrite: bool = false,                 // Overwrite existing
    progress_callback: ?ExtractProgressCallback = null,  // Progress tracking
    progress_context: ?*anyopaque = null,                // Callback context
};

Progress Types

// Bundle progress
pub const ProgressEvent = enum { scanning, reading_file, compressing, writing, finalizing };
pub const ProgressInfo = struct {
    event: ProgressEvent,
    current_file: ?[]const u8,
    files_processed: usize,
    total_files: usize,
    bytes_processed: u64,
    total_bytes: u64,
    pub fn getPercent(self: *const ProgressInfo) f64;
};
pub const ProgressCallback = *const fn (info: ProgressInfo, context: ?*anyopaque) void;

// Extract progress
pub const ExtractProgressEvent = enum { started, reading_archive, decompressing, extracting_file, verifying, completed };
pub const ExtractProgressInfo = struct {
    event: ExtractProgressEvent,
    current_file: ?[]const u8,
    files_extracted: usize,
    total_files: usize,
    bytes_written: u64,
    total_bytes: u64,
    pub fn getPercent(self: *const ExtractProgressInfo) f64;
};
pub const ExtractProgressCallback = *const fn (info: ExtractProgressInfo, context: ?*anyopaque) void;

ArchiveInfo

pub const ArchiveInfo = struct {
    format_version: u16,
    compression_version: u8,
    file_count: u32,
    original_size: u64,
    compressed_size: u64,
    payload_hash: [64]u8,
    archive_hash: [64]u8,
    metadata: Metadata,
    checksums: ChecksumList,

    pub fn deinit(self: *ArchiveInfo) void;
    pub fn getCompressionRatio(self: *const ArchiveInfo) f64;
    pub fn getSavedPercent(self: *const ArchiveInfo) f64;
};