Skip to content

tyrus:archive ​

tyrus:archive creates, inspects, and extracts ZIP, TAR, and TAR.GZ archives from paths on disk. Every operation is asynchronous, streams data through bounded buffers, and never loads a whole file into memory; packStream and unpackStream do the same with a byte stream in place of the archive file.

Extraction is safe by default: an entry can never be written outside the destination directory, links and special files are refused, limits on entry count, extracted size, and compression ratio stop decompression bombs, and every operation gives up after a time limit.

Imports ​

Importsimport { ArchiveEntry, ArchiveEntryKind, ArchiveError, ArchiveFormat, ArchiveSummary, PackOptions, UnpackOptions, list, pack, packStream, unpack, unpackStream } from "tyrus:archive";

Functions ​

ItemSignaturePurpose
pack(source: string, destination: string, options?: PackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Creates an archive from a file or directory.
list(archive: string, options?: UnpackOptions) => Promise<Result<ArchiveEntry[], ArchiveError>>Reads the entries of an archive without extracting it.
unpack(archive: string, destination: string, options?: UnpackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Extracts an archive into a directory.
packStream(source: string, format: ArchiveFormat, options?: PackOptions) => ReadableStream<u8[]>Writes the archive of a file or directory into a byte stream.
unpackStream(archive: ReadableStream<u8[]>, destination: string, options?: UnpackOptions) => Promise<Result<ArchiveSummary, ArchiveError>>Extracts a TAR or TAR.GZ archive from a byte stream.

Formats ​

pack decides the format from the destination's extension, which must be lowercase. list and unpack ignore the file name and identify the format from the content, so a .jar, .epub, or .docx file, which are ZIP archives, extracts like any .zip.

ExtensionFormatCompression
.zipZIPDeflate, levels 0 to 9
.tarTARNone
.tar.gz, .tgzTAR.GZGzip, levels 0 to 9

Error codes ​

Every function resolves with a Result and never rejects: success is Ok with the value, and a failure is Err with an ArchiveError. Its code is stable, its message is readable, and its entry names the archive entry that caused the failure when there is one. Inside a function that returns a Result with the same error, await pack(...)? hands the value over or returns the error.

CodeMeaning
ERR_ARCHIVE_NOT_FOUNDThe archive, the source, or the destination's parent directory does not exist.
ERR_ARCHIVE_IOReading or writing failed.
ERR_ARCHIVE_PERMISSION_DENIEDThe operating system denied access.
ERR_ARCHIVE_UNSUPPORTED_FORMATThe content is not a ZIP, TAR, or TAR.GZ archive.
ERR_ARCHIVE_UNSUPPORTED_EXTENSIONThe destination of pack does not end with .zip, .tar, .tar.gz, or .tgz.
ERR_ARCHIVE_INVALID_ARCHIVEThe archive is malformed or truncated.
ERR_ARCHIVE_CHECKSUM_MISMATCHAn entry's data does not match its checksum.
ERR_ARCHIVE_ENCRYPTEDThe archive contains an encrypted entry.
ERR_ARCHIVE_INVALID_OPTIONAn option has an invalid value, such as a limit of 0.
ERR_ARCHIVE_INVALID_COMPRESSION_LEVELlevel is outside 0 to 9, or was given for a .tar destination.
ERR_ARCHIVE_DESTINATION_EXISTSThe destination already exists and overwrite is not set.
ERR_ARCHIVE_PATH_ESCAPEAn entry would be written outside the destination directory.
ERR_ARCHIVE_INVALID_ENTRY_NAMEAn entry name is malformed or cannot be created on every platform.
ERR_ARCHIVE_DUPLICATE_ENTRYTwo entries resolve to the same path.
ERR_ARCHIVE_UNSAFE_LINKThe archive contains a symbolic or hard link.
ERR_ARCHIVE_UNSUPPORTED_ENTRYThe archive uses an unsupported entry type or compression method, or the source contains a link or special file.
ERR_ARCHIVE_ENTRY_LIMITThe archive has more entries than maxEntries.
ERR_ARCHIVE_SIZE_LIMITExtraction would write more bytes than maxBytes.
ERR_ARCHIVE_RATIO_LIMITAn entry, or a TAR.GZ archive as a whole, expands more than maxRatio times its compressed size.
ERR_ARCHIVE_ALLOCATION_FAILEDMemory could not be allocated for the result.
ERR_ARCHIVE_NO_SPACEThe disk ran out of space, or a ZIP archive declares more content than the destination has free.
ERR_ARCHIVE_TIMEOUTThe operation took longer than timeoutMs.
ERR_ARCHIVE_ZIP_NOT_STREAMABLEA ZIP archive was given to unpackStream, which cannot extract ZIP from a stream.

Example ​

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

async function backup(): Promise<Result<void, ArchiveError>> {
    const packed: ArchiveSummary = await pack("./documents", "./backup.zip")?;
    print(packed.entries); // 12

    const restored: ArchiveSummary = await unpack("./backup.zip", "./restored")?;
    print(restored.bytes); // 48213
    return Ok();
}

const main = async (): Promise<void> => {
    match (await backup()) {
        Ok() => { print("done"); } // done
        Err(error) => { printError(error.code); } // ERR_ARCHIVE_NOT_FOUND
    }
};