tar

tar (published to npm as tar, developed as node-tar) is a fast, full-featured implementation of the tar archive format for Node.js. It mirrors the behavior of the Unix tar(1) command, exposing the same five core operations — create, extract, list, replace, and update — through both a low-level streaming API and a high-level convenience API with single-letter aliases familiar to anyone who has used the command line tool.

Because it is the archive library underneath npm’s own package installation pipeline, tar has been hardened over more than a decade against a wide range of filesystem attacks: path-traversal entries, symlink-based writes outside the extraction target, absolute path abuse, and malicious device/FIFO entries are all rejected or neutralized by default. It supports gzip, brotli, and zstd compression natively via minizlib, and every operation can run synchronously, asynchronously with callbacks, as a Promise, or as a raw stream depending on how it’s invoked.

What You Get

• Five core operations — create (c), extract (x), list (t), replace (r), and update (u) — each usable as sync, async/Promise, or stream, mirroring tar(1) CLI semantics
• Security-hardened extraction: rejected .. path traversal, blocked symlink/hardlink escapes outside the extraction root, absolute paths rewritten to relative, and device/FIFO entries never extracted
• Built-in gzip, brotli, and zstd compression/decompression via minizlib, auto-detected on read and configurable on write
• A path-reservation system that safely serializes conflicting filesystem operations during parallel extraction (e.g. a file being swapped for a symlink mid-write)
• Granular warn/error event system with typed error codes (TAR_ENTRY_INVALID, TAR_BAD_ARCHIVE, etc.) so callers can distinguish recoverable per-entry issues from fatal archive corruption
• Full TypeScript types for every option surface, published as dual ESM/CJS builds via tshy

Common Use Cases

• Packaging and unpacking npm-style package tarballs during install/publish workflows
• Backing up or archiving directory trees to a .tgz/.tar file from a Node.js build or deploy script
• Extracting third-party or user-uploaded tarballs safely in a server context where the archive source isn’t trusted
• Streaming tar creation directly into an HTTP response or another pipe without touching disk
• Replacing or appending entries in an existing archive without a full rebuild

Under The Hood

Architecture — tar is organized as a set of composable Minipass transform/writable streams rather than a monolithic library: Pack/PackSync (src/pack.ts) turn a list of paths into a tar byte stream by walking the filesystem and delegating each entry to WriteEntry (src/write-entry.ts); Parser (src/parse.ts) is the inverse, a writable stream that consumes tar bytes and emits ReadEntry objects (src/read-entry.ts) as it decodes 512-byte headers via the Header/Pax classes (src/header.ts, src/pax.ts); Unpack/UnpackSync (src/unpack.ts, ~1,100 lines) subclass the parser and materialize entries onto the filesystem, coordinating a PathReservations queue (src/path-reservations.ts) so concurrent async writes to related paths don’t race. The five public verbs in create.ts, extract.ts, list.ts, replace.ts, and update.ts are thin orchestrators built with a shared makeCommand helper (src/make-command.ts) that normalizes the sync/async/callback/Promise/stream calling conventions into one implementation per verb.

Tech Stack — Written entirely in TypeScript (44.7% of source, compiled JS 55.2%) and built with tshy to publish dual ESM/CommonJS output plus .d.ts types from a single source tree. Runtime dependencies are all from the same maintainer’s ecosystem: minipass (the stream primitive everything is built on), minizlib (gzip/brotli/zstd via Node’s zlib bindings), @isaacs/fs-minipass (filesystem streams), chownr (recursive ownership changes), and yallist (linked-list queue used internally). No external framework dependencies; targets Node.js >=18.

Code Quality — Tested with tap across 30+ dedicated test files (141+ individual test cases found in test/), including targeted regression tests for named security advisories (ghsa-8qq5-rm4j-mr97.ts, ghsa-r6q2-hw4h-h46w.ts), fixture-driven header/parse tests, and a .taprc configured with typecheck: true and a coverage map (map.js). Linting is enforced via oxlint plus oxlint-tsgolint for type-aware rules, formatting via prettier, and the codebase uses symbol-keyed private-ish fields (Symbol('...')) throughout its stream classes for encapsulation instead of relying on TS private alone — a defensive pattern consistent with the project’s security-first posture.

API Design — The library deliberately mirrors tar(1) CLI semantics: every high-level function accepts (options, paths, callback?), single-letter aliases (c/x/t/r/u) map directly to Unix tar flags, and the same option object supports sync: true, a file path, or neither (returning a stream) — one mental model covers all five operations. The cost of that flexibility is a large, densely-typed TarOptions interface (500+ lines in options.ts) with many optional fields and overload variants, which raises the learning curve for anyone who wants more than the common create/extract path shown in the README’s copy-paste examples.