Low-level Libzip Interface

/**
 * Get synchronous libzip instance (Node.js)
 * @returns The libzip interface instance
 */
function getLibzipSync(): Libzip;

/**
 * Get asynchronous libzip instance (Browser)
 * @returns Promise resolving to the libzip interface instance
 */
function getLibzipPromise(): Promise<Libzip>;

import { getLibzipSync, getLibzipPromise } from "@yarnpkg/libzip";

// Node.js synchronous usage
const libzip = getLibzipSync();
const archive = libzip.openFromSource(sourcePtr, libzip.ZIP_RDONLY, errorPtr);

// Browser asynchronous usage
const libzip = await getLibzipPromise();
const archive = libzip.openFromSource(sourcePtr, libzip.ZIP_RDONLY, errorPtr);

interface Libzip {
  // Memory management
  readonly HEAPU8: Uint8Array;
  malloc(size: number): number;
  free(ptr: number): void;
  getValue(ptr: number, type: string): number;
  
  // Error handling
  readonly errors: typeof Errors;
  
  // Constants
  readonly SEEK_SET: 0;
  readonly SEEK_CUR: 1;
  readonly SEEK_END: 2;
  
  readonly ZIP_CHECKCONS: 4;
  readonly ZIP_EXCL: 2;
  readonly ZIP_RDONLY: 16;
  
  readonly ZIP_FL_OVERWRITE: 8192;
  readonly ZIP_FL_COMPRESSED: 4;
  
  // Compression methods
  readonly ZIP_CM_DEFAULT: -1;
  readonly ZIP_CM_STORE: 0;
  readonly ZIP_CM_DEFLATE: 8;
  
  // Operating system constants
  readonly ZIP_OPSYS_DOS: 0x00;
  readonly ZIP_OPSYS_UNIX: 0x03;
  readonly ZIP_OPSYS_WINDOWS_NTFS: 0x0a;
  // ... additional OS constants
  
  // Archive operations
  openFromSource(source: number, flags: number, error: number): number;
  close(archive: number): number;
  discard(archive: number): void;
  getError(archive: number): number;
  getName(archive: number, index: number, flags: number): string;
  getNumEntries(archive: number, flags: number): number;
  
  // Entry operations
  delete(archive: number, index: number): number;
  statIndex(archive: number, indexLow: number, indexHigh: number, flags: number, stat: number): number;
  
  // File operations
  fopenIndex(archive: number, indexLow: number, indexHigh: number, flags: number): number;
  fread(file: number, buffer: number, length: number, archive: number): number;
  fclose(file: number): number;
  
  // Directory operations
  dir: {
    add(archive: number, path: string): number;
  };
  
  // File management
  file: {
    add(archive: number, path: string, source: number, flags: number): number;
    getError(file: number): number;
    getExternalAttributes(archive: number, indexLow: number, indexHigh: number, flags: number, opsys: number, attributes: number): number;
    setExternalAttributes(archive: number, indexLow: number, indexHigh: number, flags: number, opsys: number, attributes: number): number;
    setMtime(archive: number, indexLow: number, indexHigh: number, mtime: number, flags: number): number;
    setCompression(archive: number, indexLow: number, indexHigh: number, comp: number, flags: number): number;
  };
  
  // Source management
  source: {
    fromUnattachedBuffer(buffer: number, sizeLow: number, sizeHigh: number, freep: number, error: number): number;
    fromBuffer(archive: number, buffer: number, sizeLow: number, sizeHigh: number, freep: number): number;
    free(source: number): void;
    keep(source: number): void;
    open(source: number): number;
    close(source: number): number;
    seek(source: number, offsetLow: number, offsetHigh: number, whence: number): number;
    tell(source: number): number;
    read(source: number, buffer: number, length: number): number;
    error(source: number): number;
  };
  
  // Name operations
  name: {
    locate(archive: number, path: string, flags: number): number;
  };
  
  // Error operations
  error: {
    initWithCode(error: number, code: number): void;
    strerror(error: number): string;
  };
  
  // Extension operations
  ext: {
    countSymlinks(archive: number): number;
  };
  
  // Structure field accessors
  struct: {
    statS(): number;
    statSize(stat: number): number;
    statCompSize(stat: number): number;
    statCompMethod(stat: number): number;
    statMtime(stat: number): number;
    statCrc(stat: number): number;
    
    errorS(): number;
    errorCodeZip(error: number): number;
  };
}

import { getLibzipSync, Errors } from "@yarnpkg/libzip";

const libzip = getLibzipSync();

// Create a buffer source
const data = Buffer.from("Hello, ZIP!");
const bufferPtr = libzip.malloc(data.length);
libzip.HEAPU8.set(data, bufferPtr);

const sourcePtr = libzip.source.fromUnattachedBuffer(
  bufferPtr, 
  data.length, 
  0, // size high (for 64-bit)
  0, // freep
  0  // error
);

// Create new archive
const errorPtr = libzip.malloc(4);
const archivePtr = libzip.openFromSource(sourcePtr, 0, errorPtr);

if (archivePtr === 0) {
  const errorCode = libzip.getValue(errorPtr, "i32");
  console.error("Failed to create archive:", errorCode);
  libzip.free(errorPtr);
  return;
}

// Add file to archive
const fileSourcePtr = libzip.source.fromBuffer(
  archivePtr,
  bufferPtr,
  data.length,
  0,
  0
);

libzip.file.add(archivePtr, "hello.txt", fileSourcePtr, 0);

// Close and cleanup
libzip.close(archivePtr);
libzip.free(bufferPtr);
libzip.free(errorPtr);

enum Errors {
  ZIP_ER_OK = 0,           // No error
  ZIP_ER_MULTIDISK = 1,    // Multi-disk zip archives not supported
  ZIP_ER_RENAME = 2,       // Renaming temporary file failed
  ZIP_ER_CLOSE = 3,        // Closing zip archive failed
  ZIP_ER_SEEK = 4,         // Seek error
  ZIP_ER_READ = 5,         // Read error
  ZIP_ER_WRITE = 6,        // Write error
  ZIP_ER_CRC = 7,          // CRC error
  ZIP_ER_ZIPCLOSED = 8,    // Containing zip archive was closed
  ZIP_ER_NOENT = 9,        // No such file
  ZIP_ER_EXISTS = 10,      // File already exists
  ZIP_ER_OPEN = 11,        // Can't open file
  ZIP_ER_TMPOPEN = 12,     // Failure to create temporary file
  ZIP_ER_ZLIB = 13,        // Zlib error
  ZIP_ER_MEMORY = 14,      // Memory allocation failure
  ZIP_ER_CHANGED = 15,     // Entry has been changed
  ZIP_ER_COMPNOTSUPP = 16, // Compression method not supported
  ZIP_ER_EOF = 17,         // Premature EOF
  ZIP_ER_INVAL = 18,       // Invalid argument
  ZIP_ER_NOZIP = 19,       // Not a zip archive
  ZIP_ER_INTERNAL = 20,    // Internal error
  ZIP_ER_INCONS = 21,      // Zip archive inconsistent
  ZIP_ER_REMOVE = 22,      // Can't remove file
  ZIP_ER_DELETED = 23,     // Entry has been deleted
  ZIP_ER_ENCRNOTSUPP = 24, // Encryption method not supported
  ZIP_ER_RDONLY = 25,      // Read-only archive
  ZIP_ER_NOPASSWD = 26,    // No password provided
  ZIP_ER_WRONGPASSWD = 27, // Wrong password provided
  ZIP_ER_OPNOTSUPP = 28,   // Operation not supported
  ZIP_ER_INUSE = 29,       // Resource still in use
  ZIP_ER_TELL = 30,        // Tell error
  ZIP_ER_COMPRESSED_DATA = 31 // Compressed data invalid
}

interface LibzipEmscriptenModule extends EmscriptenModule {
  cwrap: typeof cwrap;
  getValue: typeof getValue;
}

/**
 * Set factory function for creating libzip instances
 * @param factory - Function that creates and returns a Libzip instance
 */
function setFactory(factory: () => Libzip): void;

/**
 * Get current libzip instance, creating one if needed
 * @returns The current Libzip instance
 */
function getInstance(): Libzip;

/**
 * Try to get existing instance without creating a new one
 * @returns The current Libzip instance or undefined if none exists
 */
function tryInstance(): Libzip | undefined;