tar-stream

tar-stream is a streaming tar parser and generator and nothing else. It is streams2 and operates purely using streams which means you can easily extract/parse tarballs without ever hitting the file system.

npm install tar-stream
418 downloads in the last day
2 114 downloads in the last week
3 120 downloads in the last month

tar-stream

tar-stream is a streaming tar parser and generator and nothing else. It is streams2 and operates purely using streams which means you can easily extract/parse tarballs without ever hitting the file system.

npm install tar-stream

build status

Usage

tar-stream exposes two streams, pack which creates tarballs and extract which extracts tarballs. To modify an existing tarball use both.

Packing

To create a pack stream use tar.pack() and call pack.entry(header, [callback]) to add tar entries.

var tar = require('tar-stream');
var pack = tar.pack(); // p is a streams2 stream

// add a file called my-test.txt with the content "Hello World!"
pack.entry({ name: 'my-test.txt' }, 'Hello World!');

// add a file called my-stream-test.txt from a stream
var entry = pack.entry({ name: 'my-stream-test.txt' }, function(err) {
    // the stream was added
    // no more entries
    pack.finalize();
});
myStream.pipe(entry);

// pipe the pack stream somewhere
pack.pipe(process.stdout);

Extracting

To extract a stream use tar.extract() and listen for extract.on('entry', header, stream, callback)

var extract = tar.extract();

extract.on('entry', function(header, stream, callback) {
    // header is the tar header
    // stream is the content body (might be an empty stream)
    // call next when you are done with this entry

    stream.resume(); // just auto drain the stream
    stream.on('end', function() {
        callback(); // ready for next entry
    });
});

extract.on('finish', function() {
    // all entries read
});

pack.pipe(extract);

Headers

The header object using in entry should contain the following properties. Most of these values can be found by stating a file.

{
    name: 'path/to/this/entry.txt',
    size: 1314,        // entry size. defaults to 0
    mode: 0644,        // entry mode. defaults to to 0755 for dirs and 0644 otherwise
    mtime: new Date(), // last modified date for entry. defaults to now.
    type: 'file',      // type of entry. defaults to file. can be:
                       // file | link | symlink | directory | block-device
                       // character-device | fifo | contigious-file
    linkname: 'path',  // linked file name
    uid: 0,            // uid of entry owner. defaults to 0
    gid: 0,            // gid of entry owner. defaults to 0
    uname: 'maf',      // uname of entry owner. defaults to null
    gname: 'staff',    // gname of entry owner. defaults to null
    devmajor: 0,       // device major version. defaults to 0
    devminor: 0        // device minor version. defaults to 0
}

Modifying existing tarballs

Using tar-stream it is easy to rewrite paths / change modes etc in an existing tarball.

var extract = tar.extract();
var pack = tar.pack();
var path = require('path');

extract.on('entry', function(header, stream, callback) {
    // let's prefix all names with 'tmp'
    header.name = path.join('tmp', header.name);
    // write the new entry to the pack stream
    stream.pipe(pack.entry(header, callback));
});

extract.on('finish', function() {
    // all entries done - lets finalize it
    pack.finalize();
});

// pipe the old tarball to the extractor
oldTarball.pipe(extract);

// pipe the new tarball the another stream
pack.pipe(newTarball);

Performance

See tar-fs for a performance comparison with node-tar

License

MIT

npm loves you