bun.archive

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Bun.Archive constructor with file contents object

Create an archive from an object where keys are file paths and values are file contents. File contents can be strings, Blobs, ArrayBufferViews (such as Uint8Array), or ArrayBuffers. By default, archives are uncompressed tar format. Example: new Bun.Archive({ "hello.txt": "Hello, World!", "nested/file.txt": "content" })

Bun.Archive constructor with existing archive data

Create an Archive from existing tar or tar.gz data by passing bytes or a Blob. The constructor accepts Uint8Array, ArrayBuffer, or Blob containing archive data. Gzip compression is automatically detected.

Bun.Archive constructor options

ArchiveOptions accepts: compress (string, optional) - compression algorithm, currently only "gzip" is supported; level (number, optional) - compression level 1-12, default 6 when gzip is enabled. Pass undefined or no options for uncompressed tar (default).

Bun.Archive.extract() method

Extract archive to a directory. Signature: extract(path: string, options?: ArchiveExtractOptions): Promise<number>. Returns the number of entries extracted (files, directories, and symlinks). Creates the target directory if it doesn't exist and overwrites existing files. ArchiveExtractOptions accepts glob (string or readonly string[]) - glob pattern(s) to filter extraction, supports negative patterns with "!" prefix.

Bun.Archive.blob() method

Get archive as a Blob. Returns Promise<Blob>. Uses the compression setting specified in the constructor.

Bun.Archive.bytes() method

Get archive as a Uint8Array. Returns Promise<Uint8Array<ArrayBuffer>>. Uses the compression setting specified in the constructor.

Bun.Archive.files() method

Get archive contents as File objects without extracting to disk. Signature: files(glob?: string | readonly string[]): Promise<Map<string, File>>. Returns only regular files (no directories). Each File object includes name (file path with forward slash separators), size (in bytes), lastModified (modification timestamp), and standard Blob methods like text(), arrayBuffer(), and stream(). Loads file contents into memory; use extract() for large archives to write directly to disk.

Bun.Archive extraction security validation

Bun.Archive validates paths during extraction. It rejects absolute paths (POSIX / and Windows drive letters like C:\ or C:/, and UNC paths like \\server\share). Path traversal components (..) are normalized away to prevent directory escape attacks. On Windows, symbolic links are always skipped during extraction regardless of privilege level. On Linux and macOS, symlinks are extracted normally. Invalid symlink targets are rejected.

Bun.Archive glob patterns support

Glob patterns for archive operations support: * (match any characters except /), ** (match any characters including /), ? (match single character), [abc] (match character set), {a,b} (match alternatives), !pattern (exclude files matching pattern, negation). When only negative patterns are provided, all files not matching them are included. Patterns are matched against archive entry paths normalized to use forward slashes.

Bun.Archive compression levels

Gzip compression level ranges from 1 to 12, where 1 = fastest and 12 = smallest. Default level is 6 when gzip compression is enabled.

Bun.Archive extract with glob patterns example

Extract TypeScript files: archive.extract("./extracted", { glob: "**/*.ts" }). Extract from multiple directories: archive.extract("./extracted", { glob: ["src/**", "lib/**"] }). Extract everything except node_modules: archive.extract("./extracted", { glob: ["**", "!node_modules/**"] }). Extract source files but exclude tests: archive.extract("./extracted", { glob: ["src/**", "!**/*.test.ts", "!**/__tests__/**"] }).

Bun.Archive files() with glob filtering example

Get only TypeScript files: archive.files("**/*.ts"). Get files in src directory: archive.files("src/*"). Get all JSON files (recursive): archive.files("**/*.json"). Get multiple file types: archive.files(["**/*.ts", "**/*.js"]). Returns an empty Map if no files match.

Bun.Archive error handling

Archive operations can fail due to corrupted data, I/O errors, or invalid paths. Common error scenarios: Corrupted/truncated archives - new Archive() loads archive data but errors may be deferred until read/extract operations; Permission denied - extract() throws if target directory is not writable, error code "EACCES"; Disk full - extract() throws if insufficient space, error code "ENOSPC"; Invalid paths - operations throw for malformed file paths. Use try/catch to handle errors.

Bun.Archive complete type reference

type ArchiveInput = Record<string, string | Blob | Bun.ArrayBufferView | ArrayBufferLike> | Blob | Bun.ArrayBufferView | ArrayBufferLike; type ArchiveOptions = { compress?: "gzip"; level?: number }; interface ArchiveExtractOptions { glob?: string | readonly string[] }; class Archive { constructor(data: ArchiveInput, options?: ArchiveOptions); extract(path: string, options?: ArchiveExtractOptions): Promise<number>; blob(): Promise<Blob>; bytes(): Promise<Uint8Array<ArrayBuffer>>; files(glob?: string | readonly string[]): Promise<Map<string, File>> }

Bun.write with Archive

Use Bun.write() to write an archive to disk. Write uncompressed tar: const archive = new Bun.Archive({...}); await Bun.write("output.tar", archive). Write gzipped tar: const compressed = new Bun.Archive({...}, { compress: "gzip" }); await Bun.write("output.tar.gz", compressed).

Bun.Archive create from directory example

Recursively walk a directory and create an archive with normalized forward slash paths. Use Bun.file(fullPath) for file content. Handle directories vs files with entry.isDirectory(). Construct archivePath by joining prefix and entry.name with forward slashes.

Give your agent this brain