Skip to content

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.

Signaturepack(source: string, destination: string, options?: PackOptions): Promise<Result<ArchiveSummary, ArchiveError>>

Minimal example ​

tyrus
import { ArchiveError, ArchiveSummary, pack } from "tyrus:archive";

async function packRelease(): Promise<Result<ArchiveSummary, ArchiveError>> {
    return await pack("./release", "./release.tar.gz");
}

Every option ​

tyrus
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();
}
OptionTypeDefaultEffect
leveli326Compression level from 0 (store only) to 9 (smallest output). Not accepted for .tar.
overwritebooleanfalseReplaces an existing destination file. A directory is never replaced.
excludestring[]noneGlob patterns, relative to the source, for files and directories to leave out. ** spans any number of directories.
prefixstringnoneDirectory that holds every entry, such as release-1.0.0.
reproduciblebooleanfalseWrites fixed timestamps and normalized permissions, so the same input produces the same bytes.
timeoutMsu64600000 (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

tyrus
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.