Archive PRO#

The Archive class provides a comprehensive interface for working with archive files (such as ZIP). It supports reading, creating, updating, and extracting entries from archives, with both asynchronous and synchronous methods.

Overview#

Archive enables flexible management of compressed archive contents, including:

• Opening existing archives or creating new ones
• Adding files, directories, or in-memory data
• Extracting entries to memory or disk
• Deleting specific entries
• Listing archive contents
• Supporting multiple compression methods (e.g. deflate, none)
• Working in either synchronous or asynchronous modes

Static Methods#

static openForMode(path: string, accessMode: "update" | "read", options?: { pathEncoding?: Encoding }): Archive#

Opens an archive file.

Parameters:

Returns: An Archive object.

Example:

1const archive = Archive.openForMode("/tmp/example.zip", "update")

Properties#

path: string#

The path of the archive file.

Example:

1console.log(archive.path)

data: Data | null#

The raw data of the archive (if opened from memory).

Instance Methods#

entries(pathEncoding?: Encoding): ArchiveEntry[]#

Retrieves the entries in the archive.

Parameters:

pathEncoding: Optional. The encoding to use for decoding entry paths (default is "utf-8").

Returns: An array of ArchiveEntry objects.

getEntryPaths(encoding?: Encoding): string[]#

Retrieves the paths of all entries in the archive.

Parameters:

encoding: Optional. The encoding to use for decoding entry paths (default is "utf-8").

Returns: An array of entry paths.

getEntry(path: string): ArchiveEntry | null#

Retrieves an entry by its path.

Parameters:

path: The path of the entry to retrieve.

Returns: The ArchiveEntry object if found; otherwise, null.

contains(path: string): boolean#

Checks whether the archive contains a specific entry.

Parameters:

path: The path of the entry to check.

Returns: true if the path exists; otherwise, false.

Example:

1if (archive.contains("README.md")) {
2  console.log("Archive contains README.md")
3}

addEntry(path: string, toPath: string, options?: { compressionMethod?: "deflate" | "none"; bufferSize?: number }): Promise<void>#

Adds an existing file to the archive (asynchronously).

Parameters:

Example:

1await archive.addEntry("/tmp/input.txt", "docs/input.txt", {
2  compressionMethod: "deflate"
3})

addEntrySync(path: string, toPath: string, options?)#

Synchronous version of addEntry(). Throws an error if the entry cannot be added.

addFileEntry(path: string, uncompressedSize: number, provider: (offset: number, length: number) => Data, options?): Promise<void>#

Adds a file entry to the archive using a data provider function (asynchronous).

Parameters:

Example:

1const data = Data.fromRawString("abcdefg".repeat(100))
2await archive.addFileEntry("fromMemory.txt", data.count, (offset, length) => {
3  return data.slice(offset, offset + length)
4})

addFileEntrySync(...)#

Synchronous version of addFileEntry().

addDirectoryEntry(path: string, options?): Promise<void>#

Adds a directory entry to the archive.

Parameters:

Example:

1await archive.addDirectoryEntry("images/")

addDirectoryEntrySync(...)#

Synchronous version of addDirectoryEntry().

removeEntry(path: string, options?): Promise<void>#

Removes a specific entry from the archive (asynchronously).

Parameters:

Example:

1await archive.removeEntry("old/file.txt")

removeEntrySync(...)#

Synchronous version of removeEntry().

extract(path: string, consumer: (data: Data) => void, options?): Promise<void>#

Extracts a specific entry from the archive and provides its data in chunks via a consumer callback (asynchronous).

Parameters:

Example:

1await archive.extract("docs/manual.txt", (chunk) => {
2  console.log("Received chunk:", chunk.count)
3})

extractSync(...)#

Synchronous version of extract().

extractTo(path: string, to: string, options?): Promise<void>#

Extracts an entry or directory from the archive to a specific file system location (asynchronously).

Parameters:

Example:

1await archive.extractTo("docs/", "/tmp/extracted/")

extractToSync(...)#

Synchronous version of extractTo().

ArchiveEntry Interface#

ArchiveEntry represents a single entry (file, directory, or symbolic link) inside an archive.

Example:

1for (const entry of archive.entries()) {
2  console.log(`[${entry.type}] ${entry.path} (${entry.uncompressedSize} bytes)`)
3}

Examples#

Create a new archive and add files#

1const archive = Archive.openForMode("/tmp/example.zip", "update")
2
3await archive.addEntry(
4  "/tmp/hello.txt",
5  "docs/hello.txt",
6  { compressionMethod: "deflate" }
7)
8
9await archive.addDirectoryEntry("images/")
10await archive.addEntry("/tmp/logo.png", "images/logo.png")
11
12console.log("Archive entries:", archive.entries().length)

Extract a file to disk#

1const archive = Archive.openForMode("/tmp/example.zip", "read")
2await archive.extractTo("docs/hello.txt", "/tmp/unpacked/hello.txt")