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.
unpackStream(archive: ReadableStream<u8[]>, destination: string, options?: UnpackOptions): Promise<Result<ArchiveSummary, ArchiveError>>Minimal example
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
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.
