Filesystem Operations

/**
 * Filesystem implementation for ZIP archives
 * Provides standard filesystem operations on ZIP files
 */
class ZipFS extends BasePortableFakeFS {
  constructor(source: PortablePath | Buffer, options?: ZipBufferOptions | ZipPathOptions);
  
  // File operations
  readFileSync(p: PortablePath, encoding?: BufferEncoding): string | Buffer;
  writeFileSync(p: PortablePath, data: string | Buffer, options?: WriteFileOptions): void;
  appendFileSync(p: PortablePath, data: string | Buffer): void;
  
  // Directory operations
  mkdirSync(p: PortablePath, options?: MkdirOptions): void;
  rmdirSync(p: PortablePath, options?: RmdirOptions): void;
  readdirSync(p: PortablePath, options?: ReaddirOptions): string[] | Dirent[];
  
  // Metadata operations
  statSync(p: PortablePath, options?: StatSyncOptions): Stats;
  lstatSync(p: PortablePath, options?: StatSyncOptions): Stats;
  
  // File system operations
  existsSync(p: PortablePath): boolean;
  unlinkSync(p: PortablePath): void;
  renameSync(oldP: PortablePath, newP: PortablePath): void;
  copyFileSync(src: PortablePath, dest: PortablePath): void;
  
  // Stream operations
  createReadStream(p: PortablePath, options?: CreateReadStreamOptions): ReadStream;
  createWriteStream(p: PortablePath, options?: CreateWriteStreamOptions): WriteStream;
  
  // Advanced operations
  openSync(p: PortablePath, flags: string | number, mode?: number): number;
  closeSync(fd: number): void;
  readSync(fd: number, buffer: Buffer, offset: number, length: number, position: number): number;
  writeSync(fd: number, buffer: Buffer, offset?: number, length?: number, position?: number): number;
}

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

// Create new archive
const zipFs = new ZipFS("/path/to/new-archive.zip" as ppath.PortablePath, {
  create: true,
  level: 6 // compression level
});

// Write files and directories
zipFs.mkdirSync("/src" as ppath.PortablePath);
zipFs.writeFileSync("/src/index.js" as ppath.PortablePath, `
  console.log("Hello from ZIP!");
`);

// Read archive contents
const files = zipFs.readdirSync("/" as ppath.PortablePath);
const content = zipFs.readFileSync("/src/index.js" as ppath.PortablePath, "utf8");

// Work with existing archive
const existingZip = new ZipFS("/existing.zip" as ppath.PortablePath, {
  readOnly: true
});

// Check file existence and get stats
if (existingZip.existsSync("/readme.txt" as ppath.PortablePath)) {
  const stats = existingZip.statSync("/readme.txt" as ppath.PortablePath);
  console.log(`File size: ${stats.size} bytes`);
}

/**
 * Automatic ZIP file mounting filesystem
 * Transparently handles ZIP files in filesystem paths
 */
class ZipOpenFS extends MountFS<ZipFS> {
  constructor(opts?: ZipOpenFSOptions);
  
  // All standard filesystem methods inherited from MountFS
  // Automatically detects and mounts ZIP files based on file extensions
  
  saveAndClose(): void;
}

/**
 * Execute a function with a ZipOpenFS instance, automatically cleaning up afterward
 */
static openPromise<T>(
  fn: (zipOpenFs: ZipOpenFS) => Promise<T>, 
  opts?: ZipOpenFSOptions
): Promise<T>;

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

// Automatic mounting approach
const zipOpenFs = new ZipOpenFS({
  readOnlyArchives: true,
  fileExtensions: [".zip", ".jar"] // Support multiple archive types
});

// Access files inside ZIP transparently
const content = zipOpenFs.readFileSync(
  "/path/to/archive.zip/internal/file.txt" as ppath.PortablePath, 
  "utf8"
);

// List contents of ZIP
const zipContents = zipOpenFs.readdirSync(
  "/path/to/archive.zip" as ppath.PortablePath
);

// Temporary scope pattern
await ZipOpenFS.openPromise(async (zipOpenFs) => {
  const stats = zipOpenFs.statSync("/archive.zip/config.json" as ppath.PortablePath);
  const config = JSON.parse(
    zipOpenFs.readFileSync("/archive.zip/config.json" as ppath.PortablePath, "utf8")
  );
  
  return processConfig(config);
}, {
  readOnlyArchives: true
});

/**
 * Extracts the archive part (ending in the first instance of extension) from a path
 * @param path - The full filesystem path
 * @param extension - The archive file extension (e.g., ".zip")
 * @returns The archive path portion or null if not found
 */
function getArchivePart(path: string, extension: string): PortablePath | null;

import { getArchivePart } from "@yarnpkg/libzip";

const archivePath = getArchivePart("/home/user/docs/archive.zip/folder/file.txt", ".zip");
// Returns: "/home/user/docs/archive.zip"

const noArchive = getArchivePart("/home/user/docs/regular/file.txt", ".zip");
// Returns: null

interface ZipBufferOptions {
  /** Custom ZIP implementation class to use instead of default */
  customZipImplementation?: ZipImplementationClass;
  /** Whether the archive should be opened in read-only mode */
  readOnly?: boolean;
  /** Pre-computed file stats to avoid filesystem calls */
  stats?: Stats;
  /** Compression level for new files (0-9 or "mixed") */
  level?: ZipCompression;
}

interface ZipPathOptions extends ZipBufferOptions {
  /** Base filesystem to use for reading the ZIP file */
  baseFs?: FakeFS<PortablePath>;
  /** Whether to create the ZIP file if it doesn't exist */
  create?: boolean;
}

interface ZipOpenFSOptions {
  /** Libzip instance or factory function */
  libzip?: Libzip | (() => Libzip);
  /** Whether mounted archives should be opened read-only */
  readOnlyArchives?: boolean;
  /** Custom ZIP implementation for mounted archives */
  customZipImplementation?: ZipImplementationClass;
  /** File extensions to treat as ZIP archives (defaults to [".zip"]) */
  fileExtensions?: Array<string> | null;
}

/** Unix operating system constant for ZIP file attributes */
const ZIP_UNIX = 3;

/** Store compression method (no compression) */
const STORE = 0;

/** Deflate compression method (standard ZIP compression) */
const DEFLATE = 8;

/** Default compression level setting */
const DEFAULT_COMPRESSION_LEVEL: ZipCompression = "mixed";