tar-stream

tar-stream is a streaming tar parser and generator for Node.js that operates entirely on streams, so you can pack and extract tarballs without ever touching the filesystem. It exposes two complementary duplex-style streams: pack() for building new tar archives and extract() for reading entries out of an existing one, plus an async-iterator interface on the extractor for modern for await consumption.

Because everything is stream-based, tar-stream composes naturally with Node’s pipe chains — piping through a gunzip transform for .tar.gz files, rewriting headers mid-stream to transform an existing archive, or writing a generated pack stream straight to a file, socket, or HTTP response. It implements USTAR with pax extended header support, making it compatible with GNU tar, bsdtar, and other common tar implementations.

What You Get

• A pack() writable stream for constructing tar archives entry-by-entry from buffers or streams
• An extract() stream that emits entry events with parsed headers and readable per-entry content streams
• Async-iterator support on the extractor for for await (const entry of extract) consumption
• Support for rewriting/modifying an existing tarball by piping extract output into a new pack stream
• USTAR format with pax extended header support, compatible with gnutar and bsdtar

Common Use Cases

• Extracting npm-style or Docker-layer tarballs in memory as part of a build or deployment tool
• Generating tarballs on the fly to stream directly to an HTTP response or another process, without writing to disk
• Rewriting paths, modes, or ownership in an existing tarball by piping extract into pack
• Building higher-level filesystem tar tooling (as tar-fs does) on top of a pure-stream tar codec

Under The Hood

Architecture: The package is split into three small files — headers.js parses/encodes the fixed-size USTAR header block plus pax extensions, extract.js implements a duplex stream that reads a byte stream, slices out header blocks and entry bodies, and emits an entry event per file (backpressure-gated until the consumer drains each entry), and pack.js implements the inverse: a readable stream that serializes queued entries (buffer or stream bodies) into header+body blocks. index.js just re-exports both. Tech Stack: Pure JavaScript with no native bindings; runtime dependencies are streamx (the underlying stream primitives), b4a (buffer/Uint8Array interop), fast-fifo (queue for pack entries), and bare-fs for filesystem-optional environments (Bare/browser). Code Quality: Tests live under test/ (pack.js, extract.js, dual.js, plus a slow fixture suite) run via brittle with standard for linting; the library is small (~1,000 lines across the four source files) which keeps the surface easy to audit, though recent commit activity is low (score flags infrequent maintenance) despite very high download volume as a transitive dependency. API Design: The event-based extract.on('entry', (header, stream, next) => ...) pattern requires callers to explicitly drain or resume each entry stream before the next is emitted — a deliberate backpressure design that is easy to get wrong (forgetting next()/resume() stalls the whole archive) but is well documented in the README with explicit warnings.