0
# tar-stream
1

2
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.).
3

4
## Package Information
5

6
- **Package Name**: tar-stream
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install tar-stream`
10

11
## Core Imports
12

13
```javascript
14
const tar = require('tar-stream');
15
```
16

17
ES Modules (via bundlers or dynamic import):
18

19
```javascript
20
import tar from 'tar-stream';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const tar = require('tar-stream');
27

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

33
// Extract a tar archive
34
const extract = tar.extract();
35
extract.on('entry', function(header, stream, next) {
36
  console.log('Extracting:', header.name);
37
  stream.on('end', function() {
38
    next(); // ready for next entry
39
  });
40
  stream.resume(); // auto-drain the stream
41
});
42

43
// Connect pack to extract
44
pack.pipe(extract);
45
```
46

47
## Architecture
48

49
tar-stream is built around two core streaming components:
50

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

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

58
## Capabilities
59

60
### Tar Extraction
61

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

64
```javascript { .api }
65
function extract(opts?: ExtractOptions): Extract;
66

67
interface ExtractOptions {
68
  filenameEncoding?: string; // default: 'utf-8'
69
  allowUnknownFormat?: boolean; // default: false
70
}
71
```
72

73
[Extraction](./extraction.md)
74

75
### Tar Creation
76

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

79
```javascript { .api }
80
function pack(opts?: PackOptions): Pack;
81

82
interface PackOptions {
83
  // No specific options currently defined
84
}
85
```
86

87
[Packing](./packing.md)
88

89
## Types
90

91
### Header Object
92

93
Complete tar header information for entries.
94

95
```javascript { .api }
96
interface Header {
97
  name: string;           // Path to the entry
98
  size: number;          // Entry size in bytes, defaults to 0
99
  mode: number;          // Entry permissions, defaults to 0o755 for dirs, 0o644 for files
100
  mtime: Date;           // Last modified date, defaults to current time
101
  type: string;          // Entry type (see EntryType)
102
  linkname?: string;     // Name of linked file (for symlinks and hard links)
103
  uid: number;           // User ID of entry owner, defaults to 0
104
  gid: number;           // Group ID of entry owner, defaults to 0
105
  uname?: string;        // Username of entry owner
106
  gname?: string;        // Group name of entry owner
107
  devmajor: number;      // Device major version, defaults to 0
108
  devminor: number;      // Device minor version, defaults to 0
109
  pax?: object;          // Pax extended header attributes
110
}
111

112
type EntryType =
113
  | 'file'
114
  | 'link'
115
  | 'symlink'
116
  | 'directory'
117
  | 'block-device'
118
  | 'character-device'
119
  | 'fifo'
120
  | 'contiguous-file'
121
  | 'pax-header'           // Internal: PAX extended header
122
  | 'pax-global-header'    // Internal: PAX global header
123
  | 'gnu-long-link-path'   // Internal: GNU long link path header
124
  | 'gnu-long-path';       // Internal: GNU long path header
125
```