tar-parser

tar-parser is a fast, efficient parser for tar archives.

Tar archives are ubiquitous in software development, used for distributing packages, backing up files, and transferring data. Most existing JavaScript tar parsers are either Node.js-specific or don't handle streaming efficiently, forcing you to buffer entire archives in memory. This makes them unsuitable for serverless environments or processing large archives.

tar-parser can be used in any JavaScript environment (not just Node.js) and processes archives as streams, making it ideal for modern web development across all runtimes.

Features

• Universal Runtime - Runs anywhere JavaScript runs
• Web Streams - Built on the standard web Streams API, so it's composable with fetch() streams
• Format Support - Supports POSIX, GNU, and PAX tar formats
• Memory Efficient - Does not buffer anything in normal usage
• Zero Dependencies - No external dependencies

Installation

Install from npm:

npm install @remix-run/tar-parser

Usage

The main parser interface is the parseTar(archive, handler) function:

import { parseTar } from '@remix-run/tar-parser'

let response = await fetch('https://github.com/remix-run/remix/archive/refs/heads/main.tar.gz')

await parseTar(response.body.pipeThrough(new DecompressionStream('gzip')), (entry) => {
  console.log(entry.name, entry.size)
})

If you're parsing an archive with filename encodings other than UTF-8, use the filenameEncoding option:

let response = await fetch(/* ... */)

await parseTar(response.body, { filenameEncoding: 'latin1' }, (entry) => {
  console.log(entry.name, entry.size)
})

Benchmark

tar-parser performs on par with other popular tar parsing libraries on Node.js.

> @remix-run/[email protected] bench /Users/michael/Projects/remix-the-web/packages/tar-parser
> node --disable-warning=ExperimentalWarning ./bench/runner.ts

Platform: Darwin (24.0.0)
CPU: Apple M1 Pro
Date: 12/6/2024, 11:00:55 AM
Node.js v22.8.0
┌────────────┬────────────────────┐
│ (index)    │ lodash npm package │
├────────────┼────────────────────┤
│ tar-parser │ '6.23 ms ± 0.58'   │
│ tar-stream │ '6.72 ms ± 2.24'   │
│ node-tar   │ '6.49 ms ± 0.44'   │
└────────────┴────────────────────┘

Related Packages

• multipart-parser - Fast, streaming multipart parser for JavaScript

Credits

tar-parser is based on the excellent tar-stream package (MIT license) and adopts the same core parsing algorithm, utility functions, and many test cases.

License

See LICENSE