or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

filesystem.mdimplementations.mdindex.mdlibzip-interface.mdutilities.md
tile.json

tessl/npm-yarnpkg--libzip

WebAssembly-compiled version of the libzip C library providing ZIP archive manipulation capabilities for JavaScript and TypeScript applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@yarnpkg/libzip@3.2.x

To install, run

npx @tessl/cli install tessl/npm-yarnpkg--libzip@3.2.0

index.mddocs/

@yarnpkg/libzip

@yarnpkg/libzip is a WebAssembly-compiled version of the libzip C library that provides ZIP archive manipulation capabilities for JavaScript and TypeScript applications. It offers both synchronous and asynchronous APIs for creating, reading, and modifying ZIP files, with specialized exports for browser and Node.js environments.

Package Information

  • Package Name: @yarnpkg/libzip
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @yarnpkg/libzip

Core Imports

For Node.js (synchronous API):

import { ZipFS, ZipOpenFS, getLibzipSync, mountMemoryDrive } from "@yarnpkg/libzip";

For browsers (asynchronous API):

import { ZipFS, ZipOpenFS, getLibzipPromise, mountMemoryDrive } from "@yarnpkg/libzip";

CommonJS:

const { ZipFS, ZipOpenFS, getLibzipSync, mountMemoryDrive } = require("@yarnpkg/libzip");

Basic Usage

import { ZipFS, ZipOpenFS, getLibzipSync } from "@yarnpkg/libzip";
import { ppath } from "@yarnpkg/fslib";

// High-level filesystem approach with ZipFS
const zipFs = new ZipFS("/path/to/archive.zip" as ppath.PortablePath, {
  create: true
});

// Write files to the ZIP archive
zipFs.writeFileSync("/hello.txt" as ppath.PortablePath, "Hello, World!");
zipFs.mkdirSync("/documents" as ppath.PortablePath);
zipFs.writeFileSync("/documents/readme.md" as ppath.PortablePath, "# Readme");

// Read files from the ZIP archive
const content = zipFs.readFileSync("/hello.txt" as ppath.PortablePath, "utf8");
const files = zipFs.readdirSync("/" as ppath.PortablePath);

// Automatic ZIP mounting with ZipOpenFS
const zipOpenFs = new ZipOpenFS();
const stat = zipOpenFs.statSync("/path/to/archive.zip/inner/file.txt" as ppath.PortablePath);

// Low-level libzip access
const libzip = getLibzipSync();
// Use libzip.* methods for direct ZIP manipulation

Architecture

@yarnpkg/libzip is built around several key components:

  • WebAssembly Core: Emscripten-compiled libzip C library providing native ZIP functionality
  • High-level API: ZipFS and ZipOpenFS classes implementing familiar filesystem interfaces
  • Dual Entry Points: Synchronous (Node.js) and asynchronous (browser) module loading
  • Implementation Flexibility: Multiple ZIP implementations (LibZipImpl, JsZipImpl) for different use cases
  • Memory Management: Direct memory access and buffer manipulation for performance

Capabilities

Filesystem Operations

High-level filesystem interface for ZIP archives supporting standard file operations like read, write, mkdir, and stat. Integrates seamlessly with the Yarn package manager ecosystem.

class ZipFS extends BasePortableFakeFS {
  constructor(source: PortablePath | Buffer, options?: ZipBufferOptions | ZipPathOptions);
  
  readFileSync(p: PortablePath, encoding?: BufferEncoding): string | Buffer;
  writeFileSync(p: PortablePath, data: string | Buffer): void;
  mkdirSync(p: PortablePath, options?: MkdirOptions): void;
  statSync(p: PortablePath): Stats;
  readdirSync(p: PortablePath): string[];
}

class ZipOpenFS extends MountFS<ZipFS> {
  constructor(opts?: ZipOpenFSOptions);
  static openPromise<T>(fn: (zipOpenFs: ZipOpenFS) => Promise<T>, opts?: ZipOpenFSOptions): Promise<T>;
}

Filesystem Operations

Low-level Libzip Interface

Direct access to the WebAssembly-compiled libzip C library for advanced ZIP manipulation and fine-grained control over archive operations.

function getLibzipSync(): Libzip;
function getLibzipPromise(): Promise<Libzip>;

interface Libzip {
  // Memory management
  HEAPU8: Uint8Array;
  malloc(size: number): number;
  free(ptr: number): void;
  
  // Archive operations
  openFromSource(source: number, flags: number, error: number): number;
  close(archive: number): number;
  getNumEntries(archive: number, flags: number): number;
  getName(archive: number, index: number, flags: number): string;
}

Low-level Libzip Interface

ZIP Implementation Classes

Pluggable ZIP implementations providing different performance and compatibility characteristics for various environments and use cases.

class LibZipImpl implements ZipImpl {
  constructor(opts: ZipImplInput);
  getFileSource(index: number): {data: Buffer, compressionMethod: number};
  setFileSource(target: PortablePath, compression: CompressionData, buffer: Buffer): number;
}

class JsZipImpl implements ZipImpl {
  constructor(opts: ZipImplInput);
  // Read-only pure JavaScript implementation
}

Implementation Classes

Utility Functions

Helper functions for memory mounting, archive creation, and path manipulation to support common ZIP operations and integration patterns.

function mountMemoryDrive(
  origFs: typeof fs, 
  mountPoint: PortablePath, 
  source?: Buffer | null, 
  opts?: MemoryDriveOpts
): ZipFS;

function makeEmptyArchive(): Buffer;

function getArchivePart(path: string, extension: string): PortablePath | null;

Utility Functions

Types

type ZipCompression = "mixed" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
type CompressionData = [compressionMethod: number, level: number] | null;

interface ZipBufferOptions {
  customZipImplementation?: ZipImplementationClass;
  readOnly?: boolean;
  stats?: Stats;
  level?: ZipCompression;
}

interface ZipPathOptions extends ZipBufferOptions {
  baseFs?: FakeFS<PortablePath>;
  create?: boolean;
}

interface ZipOpenFSOptions {
  libzip?: Libzip | (() => Libzip);
  readOnlyArchives?: boolean;
  customZipImplementation?: ZipImplementationClass;
  fileExtensions?: Array<string> | null;
}

interface MemoryDriveOpts {
  typeCheck?: number | null;
}

enum Errors {
  ZIP_ER_OK = 0,
  ZIP_ER_MULTIDISK = 1,
  ZIP_ER_RENAME = 2,
  // ... 30 additional error codes
}