tar-to-file

Decompress a single-file tar archive with the Observable API

const {readFileSync} = require('fs');
const tarToFile = require('tar-to-file');

const subscription = tarToFile('archive.tar', 'target.txt').subscribe({
  start() {
    console.log('Extracting `archive.tar` ...');
  },
  complete() {
    console.log('Extracted.');
    readFileSync('target.txt'); //=> <Buffer ...>
  }
});

subscription.unsubscribe();

Installation

Use npm.

npm install tar-to-file

API

const tarToFile = require('tar-to-file');

tarToFile(tarPath, filePath [, options])

tarPath: string (path of the archive file)
filePath: string (file path of the extracted contents)
options: Object
Return: Observable (zenparsing's implementation)

When the Observable is subscribed, it starts to extract a file from a single-file archive and successively send extraction progress to its Observer.

Every progress object have two properties header and bytes. header is a header of the entry, and bytes is the total processed size of the extraction.

For example you can get the progress as a percentage by (progress.bytes / progress.header.size || 0) * 100.

tarToFile('my/archive.tar', 'my/file').subscribe(({bytes, header}) => {
  console.log(`${(bytes / header.size * 100).toFixed(1)} %`);
}, console.error, () => {
  console.log('Completed');
});

0.0 %
0.1 %
0.3 %
0.4 %
︙
99.6 %
99.8 %
99.9 %
100.0 %
Completed

Note that tar-to-file doesn't support any archives that:

• contains multiple entries
• contains a non-file, for example directory and symlink entries

tarToFile('./has-directory.tar').subscribe({
  error(err) {
    err.message; /*=>
      Expected the archive test/fixture-directory.tar to contain only a single file,
      but actually contains a non-file entry '_' (directory).
    */
  }
});

tarToFile('./has-two-files.tar').subscribe({
  error(err) {
    err.message; /*=>
      Expected the archive ./has-two-files.tar to contain only a single file,
      but actually contains multiple entries 'a.txt' and 'b.txt'.
    */
  }
});

Options

You can pass options to tar-fs's extract() method and fs.createWriteStream(). Note that:

• strip, filter and ignore options are not supported.
• fs option defaults to graceful-fs for more stability.

Additionally, you can use the following:

tarTransform

Type: Stream

A transform stream to modify the archive before extraction.

For example, pass zlib.createGunzip() and you can decompress a gzipped tar.

const tarToFile = require('tar-to-file');
const {createGunzip} = require('zlib');

const gunzipStream = createGunzip();

const observable = fileToTar('Untitled.tar.gz', 'Untitled.txt', {
  tarTransform: gunzipStream
});

Related project

• file-to-tar – Inverse of this module. Create a tar archive from a single file

License

ISC License © 2017 - 2018 Shinnosuke Watanabe