Package Exports

dl-tgz

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dl-tgz) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

dl-tar

A Node.js module to download and extract a tar archive with Observable API

const {readdirSync} = require('fs');
const dlTar = require('dl-tar');

const url = 'https://****.org/my-archive.tar';
/* my-archive
   ├── LICENSE
   ├── README.md
   ├── INSTALL
   └── bin
       └── app.exe
*/

dlTar(url, 'my/dir').subscribe({
  next({header, bytes}) {
    if (bytes !== header.size) {
      return;
    }

    console.log(`✓ ${header.name}`);
  },
  complete() {
    readdirSync('my/dir'); //=> ['INSTALL', LICENSE', 'README.md', 'bin']

    console.log('\nCompleted.')
  }
});

✓ bin/app.exe
✓ README.md
✓ LICENSE
✓ install

Completed.

Installation

Use npm.

npm install dl-tar

API

const dlTar = require('dl-tar');

dlTar(tarArchiveUrl, extractDir [, options])

tarArchiveUrl: String
extractDir: String (a path where the archive will be extracted)
options: Object
Return: Observable (zenparsing's implementation)

When the observable is subscribed, it starts to download the tar archive, extract it and successively send extraction progress as objects to the observer.

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

For example you can get the progress of each entry as a percentage by bytes / header.size * 100.

dlTar('https://****.org/my-archive.tar', 'my/dir').subscribe(progress => {
  console.log(`${(progress.bytes / progress.header.size * 100).toFixed(1)} %`);

  if (progress.bytes === progress.header.size) {
    console.log(`>> OK ${progress.header.name}\n`);
  }
});

0.1 %
0.3 %
0.4 %
[...]
99.6 %
99.8 %
99.9 %
100.0 %
>> OK bin/app.exe
0.1 %
0.2 %
0.3 %
[...]

Options

You can pass options to Request and tar-fs's extract.

Note that strip option defaults to 1, not 0. That means the top level directory is stripped off by default.

Additionally, you can use the following option.

tarTransform

Type: Stream

A transform stream to modify the archive before extraction.

For example, pass gunzip-maybe to this option and you can download both gzipped and non-gzipped tar.

const dlTar = require('dl-tar');
const gunzipMaybe = require('gunzip-maybe');

const observable = dlTar('https://github.com/nodejs/node/archive/master.tar.gz', './', {
  tarTransform: gunzipMaybe()
});

License

Licensed under the MIT License.