pack
pack creates an archive from a file or a directory. The destination's lowercase extension decides the format: .zip, .tar, .tar.gz, or .tgz.
Entries are written in a stable order with / separators, and the archive is first written to a temporary file next to the destination, then renamed into place, so a failure never leaves a truncated archive behind. When the destination lies inside the source directory, it is left out of the archive.
pack(source: string, destination: string, options?: PackOptions): Promise<Result<ArchiveSummary, ArchiveError>>Minimal example
import { ArchiveError, ArchiveSummary, pack } from "tyrus:archive";
async function packRelease(): Promise<Result<ArchiveSummary, ArchiveError>> {
return await pack("./release", "./release.tar.gz");
}Every option
import { ArchiveError, ArchiveSummary, PackOptions, pack } from "tyrus:archive";
async function packRelease(): Promise<Result<void, ArchiveError>> {
const summary: ArchiveSummary = await pack("./release", "./release-1.0.0.tar.gz", {
level: 9, // 0 (store only) to 9 (smallest output); default 6
overwrite: true, // replace an existing file; default false
exclude: ["**/*.map", "tmp"], // globs relative to the source; default none
prefix: "release-1.0.0", // directory that holds every entry; default none
reproducible: true, // zero timestamps and normalize permissions; default false
timeoutMs: 120_000, // give up after this many milliseconds; default 600000 (10 minutes)
})?;
print(summary.entries); // 42
print(summary.bytes); // 1048576
return Ok();
}| Option | Type | Default | Effect |
|---|---|---|---|
level | i32 | 6 | Compression level from 0 (store only) to 9 (smallest output). Not accepted for .tar. |
overwrite | boolean | false | Replaces an existing destination file. A directory is never replaced. |
exclude | string[] | none | Glob patterns, relative to the source, for files and directories to leave out. ** spans any number of directories. |
prefix | string | none | Directory that holds every entry, such as release-1.0.0. |
reproducible | boolean | false | Writes fixed timestamps and normalized permissions, so the same input produces the same bytes. |
timeoutMs | u64 | 600000 (10 minutes) | Gives up with ERR_ARCHIVE_TIMEOUT when packing takes longer, leaving no partial archive behind. 0 fails with ERR_ARCHIVE_INVALID_OPTION. |
Symbolic links and special files in the source are refused with ERR_ARCHIVE_UNSUPPORTED_ENTRY, which names the offending path in entry, instead of being silently skipped.
Error Handling
error
import { ArchiveError, ArchiveSummary, pack } from "tyrus:archive";
async function packTwice(): Promise<void> {
const first = await pack("./release", "./release.zip");
match (await pack("./release", "./release.zip")) {
Ok(summary) => { print(summary.entries); }
Err(error) => { printError(error.code); } // ERR_ARCHIVE_DESTINATION_EXISTS
}
}A literal destination with an unknown or uppercase extension, and a literal level the format cannot use, are reported by the compiler before the program runs.
