or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

extraction.mdindex.mdpacking.md
tile.json

tessl/npm-tar-stream

Streaming tar parser and generator that operates purely using streams without hitting the file system.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tar-stream@3.1.x

To install, run

npx @tessl/cli install tessl/npm-tar-stream@3.1.0

index.mddocs/

tar-stream

tar-stream is a streaming tar parser and generator that operates purely using streams without ever hitting the file system. It implements USTAR format with additional support for pax extended headers, making it compatible with all popular tar distributions (gnutar, bsdtar, etc.).

Package Information

  • Package Name: tar-stream
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install tar-stream

Core Imports

const tar = require('tar-stream');

ES Modules (via bundlers or dynamic import):

import tar from 'tar-stream';

Basic Usage

const tar = require('tar-stream');

// Create a tar archive
const pack = tar.pack();
pack.entry({ name: 'my-file.txt' }, 'Hello World!');
pack.finalize();

// Extract a tar archive
const extract = tar.extract();
extract.on('entry', function(header, stream, next) {
  console.log('Extracting:', header.name);
  stream.on('end', function() {
    next(); // ready for next entry
  });
  stream.resume(); // auto-drain the stream
});

// Connect pack to extract
pack.pipe(extract);

Architecture

tar-stream is built around two core streaming components:

  • Extract Stream: A Writable stream that parses tar data and emits entry events for each file/directory
  • Pack Stream: A Readable stream that generates tar data from entries added via the entry() method
  • Header System: Comprehensive tar header encoding/decoding supporting USTAR and pax formats
  • Stream Integration: Full integration with Node.js streams for memory-efficient processing

The library supports both traditional callback-style and modern async iterator patterns for maximum flexibility.

Capabilities

Tar Extraction

Streaming tar archive parser that extracts entries without hitting the file system. Supports both callback-style and async iterator patterns.

function extract(opts?: ExtractOptions): Extract;

interface ExtractOptions {
  filenameEncoding?: string; // default: 'utf-8'
  allowUnknownFormat?: boolean; // default: false
}

Extraction

Tar Creation

Streaming tar archive generator that creates tar data from entries. Supports all tar entry types including files, directories, symlinks, and device files.

function pack(opts?: PackOptions): Pack;

interface PackOptions {
  // No specific options currently defined
}

Packing

Types

Header Object

Complete tar header information for entries.

interface Header {
  name: string;           // Path to the entry
  size: number;          // Entry size in bytes, defaults to 0
  mode: number;          // Entry permissions, defaults to 0o755 for dirs, 0o644 for files
  mtime: Date;           // Last modified date, defaults to current time
  type: string;          // Entry type (see EntryType)
  linkname?: string;     // Name of linked file (for symlinks and hard links)
  uid: number;           // User ID of entry owner, defaults to 0
  gid: number;           // Group ID of entry owner, defaults to 0
  uname?: string;        // Username of entry owner
  gname?: string;        // Group name of entry owner
  devmajor: number;      // Device major version, defaults to 0
  devminor: number;      // Device minor version, defaults to 0
  pax?: object;          // Pax extended header attributes
}

type EntryType =
  | 'file'
  | 'link'
  | 'symlink'
  | 'directory'
  | 'block-device'
  | 'character-device'
  | 'fifo'
  | 'contiguous-file'
  | 'pax-header'           // Internal: PAX extended header
  | 'pax-global-header'    // Internal: PAX global header
  | 'gnu-long-link-path'   // Internal: GNU long link path header
  | 'gnu-long-path';       // Internal: GNU long path header