Skip to content

unpackStream ​

unpackStream extracts a TAR or TAR.GZ archive from a ReadableStream<u8[]> into a directory while the bytes arrive, with the same safety as unpack: entries stay inside the destination, links and special files are refused, the limits apply, and on failure everything the call created is removed. The format is identified from the first bytes.

A ZIP archive cannot be extracted from a stream: its entry table is at the end, and the entries before it cannot be trusted until it is read. Such a stream fails with ERR_ARCHIVE_ZIP_NOT_STREAMABLE; write it to a file and use unpack.

SignatureunpackStream(archive: ReadableStream<u8[]>, destination: string, options?: UnpackOptions): Promise<Result<ArchiveSummary, ArchiveError>>

Minimal example ​

tyrus
import { ArchiveError, ArchiveSummary, unpackStream } from "tyrus:archive";
import { FsError, readFileStream } from "tyrus:fs";
import { ReadableStream } from "tyrus:stream";

async function restore(): Promise<void> {
    try {
        const input: ReadableStream<u8[]> = readFileStream("./site.tgz");
        const summary = await unpackStream(input, "./restored") onfail {
            printError(summary.code);
            return;
        };
        print(summary.entries); // 3
    } catch (error: FsError) {
        printError(error.code);
    }
}

Every option ​

tyrus
import { ArchiveError, ArchiveSummary, UnpackOptions, unpackStream } from "tyrus:archive";
import { ReadableStream } from "tyrus:stream";

async function extract(upload: ReadableStream<u8[]>): Promise<Result<void, ArchiveError>> {
    const summary: ArchiveSummary = await unpackStream(upload, "./workspace", {
        overwrite: true, // replace files that already exist; default false
        stripComponents: 1, // drop this many leading path components; default 0
        maxEntries: 1_000, // refuse archives with more entries; default 100000
        maxBytes: 50_000_000, // refuse more extracted bytes; default 4 GiB
        maxRatio: 100, // refuse a TAR.GZ expanding past this ratio; default 200
        timeoutMs: 30_000, // give up after this many milliseconds; default 600000 (10 minutes)
    })?;
    print(summary.entries); // 3
    return Ok();
}

The stream is borrowed: the call reads it to the end of the archive, and the program keeps its handle. A stream that fails while being read resolves with ERR_ARCHIVE_IO, and one nobody writes to fails at timeoutMs.