dir-archiver

Create, inspect, audit, normalize, and extract archives through a small ESM API.

dir-archiver adds deterministic filesystem traversal, safe extraction, and task-level results to Bytefold. It supports Node.js 24 or newer, Deno, and Bun.

Install

npm install dir-archiver
bun add dir-archiver

For Deno:

deno add jsr:@ismail-elkorchi/dir-archiver

Example

import { audit, extract, list, write } from "dir-archiver";

await write("./project", "./artifacts/project.zip", {
  includeBaseDirectory: true,
  exclude: ["node_modules", ".git"],
});

const inventory = await list("./artifacts/project.zip");
console.log(inventory.entries);

const report = await audit("./artifacts/project.zip", {
  safetyProfile: "untrusted",
});
if (!report.isSafe) {
  throw new Error(`Archive rejected: ${JSON.stringify(report.issues)}`);
}

await extract("./artifacts/project.zip", "./artifacts/unpacked", {
  safetyProfile: "strict",
  maxExtractedFileBytes: 64 * 1024 * 1024,
  maxTotalExtractedBytes: 512 * 1024 * 1024,
});

API

| Operation | Purpose | | --- | --- | | write(source, destination, options?) | Create an archive from a local file or directory. | | detect(input, options?) | Detect the archive and compression layers. | | list(input, options?) | Return JSON-safe entry summaries. | | audit(input, options?) | Return Bytefold's safety report. | | extract(input, destination, options?) | Audit and extract with path and byte-limit enforcement. | | normalize(input, destination, options?) | Write deterministic normalized output when supported. |

The package does not expose Bytefold's live reader. Import Bytefold directly when you need entry streams or lower-level reader methods.

write() accepts archive writer formats: zip, tar, tgz, tar.gz, tar.zst, and tar.br. Read operations also accept Bytefold's read-only and raw-compression formats.

CLI

npx dir-archiver --help

npx dir-archiver write \
  --source ./project \
  --output ./artifacts/project.zip \
  --exclude node_modules \
  --exclude .git \
  --json

npx dir-archiver extract \
  --input ./artifacts/project.zip \
  --output ./artifacts/unpacked \
  --safety-profile strict \
  --json

Every value-taking option occurrence has one value. Repeat --exclude for repeated exclusions. Unknown flags, duplicate scalar options, irrelevant options, and arguments after -- are usage errors.

The command comes before its command-specific options. --json controls successful operation results; invalid invocations always write concise diagnostics to stderr and exit with status 2. Use -h or --help for root or command help, and --version for the installed version.

Operational limits

• Writing and extraction are not transactional; use temporary destinations when partial output is unacceptable.
• Extraction rejects unsafe archive paths and audits before creating the destination. Use a new directory below a trusted parent.
• Symlink entries are skipped unless allowSymlinks is true. Hard links are rejected.
• followSymlinks can archive targets outside the source directory; enable it only for a trusted filesystem layout.
• Source files and extracted entries are currently buffered in memory.
• maxExtractedFileBytes and maxTotalExtractedBytes limit extracted data; Bytefold's limits control parsing and decompression.
• Filesystem, network, cancellation, and Bytefold errors can surface directly. Package policy failures use DirArchiverError.code.

Documentation

• API reference
• CLI reference
• Safety
• Formats
• Troubleshooting
• Breaking changes
• Security policy
• Changelog