runtime:archive

Read and write tar, tar.gz and zip (DECISIONS D174). Bun.Archive's shape: new Archive(input) builds from a plain object of entries or opens bytes, a Blob or a runtime:fs file(); bytes()/blob() return the archive, entries() exposes metadata with lazy entry reads, files() returns Map<string, File>, and extract() writes it out.

Import

import { Archive, ArchiveEntry } from "runtime:archive";
import { file } from "runtime:fs";

new Archive(input, options?)

input is one of:

• a plain object whose keys are entry paths and whose values are a string (UTF-8), a Uint8Array/ArrayBuffer/view, a Blob or File, null for a directory (the key must end with /), or { data, lastModified } where data is any of the former and lastModified is epoch milliseconds or a Date;

• a Uint8Array, ArrayBuffer, view or Blob holding an archive;

• a runtime:fs file().

A path string is a TypeError: pass file(path). A SharedArrayBuffer is refused. Bytes — a source, or an entry's data — are copied when the Archive is constructed, so changing the buffer afterwards does not change the archive. Opening detects the format from the leading bytes — gzip, zip or tar — and never from a name or extension.

For build entries, Blob and File mean the web APIs. A runtime:fs file() handle is not a build entry value; use await file(path).bytes() to add its contents. This reads the whole input file into memory.

Builds are deterministic: entries are sorted by path, ownership is 0:0, modes are 0644 for files and 0755 for directories, and the timestamp is 0 unless an entry supplied lastModified (zip clamps to 1980–2107). The same input produces the same bytes.

import { Archive } from "runtime:archive";
import { file } from "runtime:fs";

const entries = {
  "hello.txt": "Hello, world!",
  "assets/logo.png": await file("assets/logo.png").bytes(),
  "empty/": null,
};

await new Archive(entries).bytes();                          // tar
await new Archive(entries, { format: "zip" }).bytes();
await new Archive(entries, { compress: "gzip" }).bytes();   // tar.gz

Methods

for await (const entry of archive) streams metadata instead of collecting an array, so the guest holds only the current entry. Per-entry validation and the entry limits still apply, but the cross-entry checks run as entries arrive: a duplicate or file/directory collision later in the archive rejects the loop after earlier entries were yielded. A zip parser still holds its central directory, bounded by maxEntries.

An ArchiveEntry has path, size, directory and lastModified (epoch milliseconds, or null), plus lazy bytes(), text(), blob() and stream(). Reading an entry does not materialize the other entries: stream() yields bounded chunks, files(filter) reads only the entries the filter selected, and a file() source is scanned through the filesystem rather than loaded whole. (A tar.gz entry still has to decompress through its predecessors to reach its data; those bytes are discarded as they are skipped.)

import { Archive } from "runtime:archive";
import { file } from "runtime:fs";

const opened = new Archive(file("bundle.tar.gz"));
for (const entry of await opened.entries()) {
  if (!entry.directory) console.log(entry.path, entry.size);
}
const text = await (await opened.entries())[0].text();

const images = await opened.files(/^assets\/.*\.png$/);
await opened.extract("public");                  // creates public/ as needed
await Archive.write(file("bundle.zip"), { "hello.txt": "Hello" }, { format: "zip" });

Filters

files() and extract({ filter }) take the same filter:

• A glob ("src/**") or a list of globs (["**/*.ts", "!**/*.test.ts"]), matched against the entry path with the rules of runtime:fs's Glob: * does not cross /, ** does. In a list, a pattern starting with ! excludes: an entry is taken when it matches a pattern without ! and none with it, and a list of only ! patterns takes everything else.

• A RegExp, tested against the path.

• A function (path) => boolean.

An invalid glob, or a list with a non-string in it, is a TypeError.

Safety

Every entry path is validated before that entry is returned or a file is written, and the eager listings finish the layout check before returning. A path must be relative, slash-separated, valid UTF-8, with no empty, . or .. component, no backslash and no drive letter. Tar symlinks and hard links, zip symlinks, special tar types (character/block/FIFO/sparse/global PAX) and encrypted zip entries are refused, as is zip compression other than Stored and Deflated. Duplicate entries, file/directory collisions, and names that would collide on a case-insensitive filesystem (Windows, macOS) are refused. On Windows, device names (NUL, COM1.txt), names with : or another character Windows forbids, and names ending in a dot or space are refused too. An archive is never sanitized into a different one. extract() checks the destination, parents and output paths for existing symlinks, then decodes and validates the whole archive into a temporary directory beneath the destination before moving staged files into place. Nothing beneath the destination is followed if it is a link, including one that appears during extraction. A corrupt or unsafe archive therefore does not partially change destination files. Staging uses temporary disk space up to the uncompressed output size. An I/O error while moving staged files into place can leave partial output.

Errors

See also

• Archives guide — bundling downloads and unpacking uploads.

• Internals: archives — what is validated, what is held in memory, and why extraction stages before writing.