Utility Functions

/**
 * Mount an in-memory ZIP filesystem at a specific mount point
 * Patches the provided fs object to handle ZIP operations transparently
 * @param origFs - Original fs module to patch
 * @param mountPoint - Filesystem path where ZIP should be mounted
 * @param source - ZIP archive buffer (defaults to empty archive)
 * @param opts - Configuration options
 * @returns ZipFS instance for the mounted archive
 */
function mountMemoryDrive(
  origFs: typeof fs, 
  mountPoint: PortablePath, 
  source?: Buffer | null, 
  opts?: MemoryDriveOpts
): ZipFS;

interface MemoryDriveOpts {
  /** Type checking flags for mount validation */
  typeCheck?: number | null;
}

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

// Mount empty ZIP at /virtual
const zipFs = mountMemoryDrive(
  fs,
  "/virtual" as ppath.PortablePath
);

// Now fs operations work transparently with the ZIP
fs.writeFileSync("/virtual/hello.txt", "Hello from memory ZIP!");
fs.mkdirSync("/virtual/docs");
fs.writeFileSync("/virtual/docs/readme.md", "# Documentation");

// Read back through fs
const content = fs.readFileSync("/virtual/hello.txt", "utf8");
const files = fs.readdirSync("/virtual");

// Mount existing ZIP archive
const existingZipBuffer = fs.readFileSync("existing.zip");
const existingZipFs = mountMemoryDrive(
  fs,
  "/mounted-archive" as ppath.PortablePath,
  existingZipBuffer,
  { typeCheck: 21 }
);

// Access files in the mounted archive
const archivedFiles = fs.readdirSync("/mounted-archive");

/**
 * Create an empty ZIP archive buffer
 * Contains minimal ZIP structure with no entries
 * @returns Buffer containing empty ZIP archive data
 */
function makeEmptyArchive(): Buffer;

import { makeEmptyArchive, ZipFS } from "@yarnpkg/libzip";

// Create empty archive buffer
const emptyZip = makeEmptyArchive();

// Use as starting point for new ZipFS
const zipFs = new ZipFS(emptyZip, {
  level: 6
});

// Add content to the initially empty archive
zipFs.writeFileSync("/first-file.txt" as ppath.PortablePath, "First content!");

// Save the archive
const finalArchive = zipFs.getBufferAndClose();

/**
 * Extracts the archive part (ending in the first instance of extension) from a path
 * Used by ZipOpenFS to detect ZIP files within filesystem paths
 * @param path - The full filesystem path potentially containing an archive
 * @param extension - The archive file extension to look for (e.g., ".zip")
 * @returns The archive path portion or null if no archive detected
 */
function getArchivePart(path: string, extension: string): PortablePath | null;

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

// Detect ZIP in path
const zipPath = getArchivePart(
  "/home/user/documents/project.zip/src/index.js", 
  ".zip"
);
// Returns: "/home/user/documents/project.zip"

const innerPath = "/home/user/documents/project.zip/src/index.js".slice(zipPath.length);
// innerPath: "/src/index.js"

// No archive in path
const regularPath = getArchivePart("/home/user/documents/regular.txt", ".zip");
// Returns: null

// Multiple extensions
const jarPath = getArchivePart("/apps/myapp.jar/META-INF/MANIFEST.MF", ".jar");
// Returns: "/apps/myapp.jar"

// Edge cases handled correctly
const noMatch = getArchivePart("/path/to/.zip", ".zip"); // Returns: null (disallows files named ".zip")
const multipleZips = getArchivePart("/path/first.zip/nested.zip/file.txt", ".zip");
// Returns: "/path/first.zip" (returns first match)

/**
 * Unix timestamp conversion utility
 * Handles various time formats and converts to Unix timestamps for ZIP files
 * @param time - Time value as Date, string, or number
 * @returns Unix timestamp (seconds since epoch)
 */
function toUnixTimestamp(time: Date | string | number): number;

// Used internally but available for custom implementations
const now = toUnixTimestamp(new Date());
const fromString = toUnixTimestamp("1640995200"); // Unix timestamp string
const fromNumber = toUnixTimestamp(1640995200000); // Milliseconds since epoch

/** 
 * ZIP compression level specification
 * Numbers 0-9 represent standard compression levels
 * "mixed" allows different compression per file
 */
type ZipCompression = "mixed" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;

/**
 * Compression method and level tuple
 * First element: compression method (0=store, 8=deflate, etc.)
 * Second element: compression level (0-9)
 * null indicates no compression data
 */
type CompressionData = [compressionMethod: number, level: number] | null;

/** Default compression level for new archives */
const DEFAULT_COMPRESSION_LEVEL: ZipCompression = "mixed";

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

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

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

import { ZIP_UNIX, DEFLATE } from "@yarnpkg/libzip";

// Set Unix file permissions in ZIP
const fileAttributes = 0o644 << 16; // rw-r--r-- permissions
zipImpl.setExternalAttributes(fileIndex, ZIP_UNIX, fileAttributes);

// Use deflate compression
const compressionData: CompressionData = [DEFLATE, 6]; // Deflate level 6
zipImpl.setFileSource("file.txt" as ppath.PortablePath, compressionData, buffer);

interface MemoryDriveOpts {
  /** 
   * Type checking configuration for mount validation
   * Used internally by MountFS for magic byte detection
   */
  typeCheck?: number | null;
}