AES-256 ZIP Archives# PRO

The Archive class provides interfaces for working with ZIP and 7z files. ZIP archives can be edited entry by entry or created and extracted with AES-256 encryption. The 7z methods support AES-256 encryption, progress, and cancellation.

#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
• Creating and extracting AES-256 encrypted ZIP archives
• Creating, listing, and extracting AES-256 encrypted 7z archives

#Static Methods

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

Opens a ZIP archive file. The returned instance methods apply to ZIP archives only.

Parameters:

Returns: An Archive object.

Example:

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

#static createZip(options: ZipCreateOptions): Promise<ZipArchiveResult>

Creates a ZIP archive. When password is provided, file contents use WinZip AES-256 encryption. Without a password, the method creates a regular ZIP. The destination must not already exist.

const result = await Archive.createZip({
  sourcePath: "/tmp/photos",
  destinationPath: "/tmp/photos.zip",
  password: "a-strong-password",
  shouldKeepParent: true
})

console.log(result.entryCount, result.outputBytes)

ZIP encryption does not hide file names stored in the archive. To hide file names and archive metadata as well, use create7z() with encryptHeader: true.

#static extractZip(options: ZipExtractOptions): Promise<ZipArchiveResult>

Extracts a regular or password-protected ZIP into a new directory. An existing destination, invalid password, or configured limit failure rejects the operation without leaving an incomplete destination.

try {
  const result = await Archive.extractZip({
    sourcePath: "/tmp/photos.zip",
    destinationPath: "/tmp/restored-photos",
    password: "a-strong-password"
  })
  console.log(`Extracted ${result.entryCount} entries`)
} catch (error) {
  if (error.name === "ArchiveError") {
    console.log(error.code, error.message)
  }
}

#static create7z(options: SevenZipCreateOptions): SevenZipTask

Creates a new AES-256 encrypted 7z archive. The destination must not already exist. Content is always encrypted; file names are encrypted by default.

const task = Archive.create7z({
  sources: [
    "/tmp/report.pdf",
    { path: "/tmp/photos", archivePath: "attachments/photos" }
  ],
  destinationPath: "/tmp/backup.7z",
  password: "a-strong-password"
})

task.onProgress = progress => {
  console.log(`${Math.round(progress.fractionCompleted * 100)}% ${progress.path}`)
}

const result = await task.result
console.log(result.destinationPath, result.outputBytes)

Empty source directories and symbolic links are not supported.

#static list7z(options: SevenZipListOptions): Promise<ArchiveEntry[]>

Lists the entries in a 7z archive. A password is required when the archive header is encrypted.

const entries = await Archive.list7z({
  sourcePath: "/tmp/backup.7z",
  password: "a-strong-password"
})

for (const entry of entries) {
  console.log(entry.path, entry.uncompressedSize, entry.isEncrypted)
}

#static extract7z(options: SevenZipExtractOptions): SevenZipTask

Extracts a 7z archive into a new directory. Unsafe entry paths and archives that exceed the configured limits are rejected. Existing destinations are not overwritten.

const task = Archive.extract7z({
  sourcePath: "/tmp/backup.7z",
  destinationPath: "/tmp/restored",
  password: "a-strong-password"
})

try {
  const result = await task.result
  console.log(`Extracted ${result.entryCount} entries`)
} catch (error) {
  if (error.name === "ArchiveError") {
    console.log(error.code, error.message)
  }
}

#SevenZipTask Interface

create7z() and extract7z() return a task that reports progress and can be cancelled.

ArchiveError.code is one of invalidArguments, permissionDenied, sourceNotFound, destinationExists, invalidPasswordOrCorruptArchive, unsafeEntryPath, unsupportedEntryType, archiveLimitExceeded, cancelled, outOfSpace, ioError, or internalError.

#Properties

#path: string

The path of the archive file.

Example:

console.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:

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

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

Adds an existing file to the archive (asynchronously).

Parameters:

Example:

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

#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:

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

#addFileEntrySync(...)

Synchronous version of addFileEntry().

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

Adds a directory entry to the archive.

Parameters:

Example:

await archive.addDirectoryEntry("images/")

#addDirectoryEntrySync(...)

Synchronous version of addDirectoryEntry().

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

Removes a specific entry from the archive (asynchronously).

Parameters:

Example:

await 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:

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

#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:

await 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:

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

#Examples

#Create a new archive and add files

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

await archive.addEntry(
  "/tmp/hello.txt",
  "docs/hello.txt",
  { compressionMethod: "deflate" }
)

await archive.addDirectoryEntry("images/")
await archive.addEntry("/tmp/logo.png", "images/logo.png")

console.log("Archive entries:", archive.entries().length)

#Extract a file to disk

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