Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shinnn/dl-tar
Download and extract a tar archive with the Observable API
https://github.com/shinnn/dl-tar
archive decompression downloader extraction fetch gzip javascript nodejs observable request tar tgz
Last synced: 27 days ago
JSON representation
Download and extract a tar archive with the Observable API
- Host: GitHub
- URL: https://github.com/shinnn/dl-tar
- Owner: shinnn
- License: isc
- Created: 2017-02-10T11:20:13.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-07-10T21:41:15.000Z (over 5 years ago)
- Last Synced: 2024-10-15T18:40:59.225Z (30 days ago)
- Topics: archive, decompression, downloader, extraction, fetch, gzip, javascript, nodejs, observable, request, tar, tgz
- Language: JavaScript
- Homepage:
- Size: 180 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# dl-tar
[](https://www.npmjs.com/package/dl-tar)
[](https://travis-ci.org/shinnn/dl-tar)
[](https://coveralls.io/github/shinnn/dl-tar?branch=master)
A [Node.js](https://nodejs.org/) module to download and extract a [tar](https://www.gnu.org/software/tar/) archive with the [Observable](https://tc39.github.io/proposal-observable/) API
```javascript
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({entry}) {
if (entry.remain === 0) {
console.log(`✓ ${entry.header.name}`);
}
},
complete() {
readdirSync('my/dir'); //=> ['INSTALL', LICENSE', 'README.md', 'bin']
console.log('\nCompleted.')
}
});
```
```
✓ bin/
✓ bin/app.exe
✓ README.md
✓ LICENSE
✓ install
Completed.
```
## Installation
[Use](https://docs.npmjs.com/cli/install) [npm](https://docs.npmjs.com/getting-started/what-is-npm).
```
npm install dl-tar
```
## API
```javascript
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`](https://tc39.github.io/proposal-observable/#observable) ([zenparsing's implementation](https://github.com/zenparsing/zen-observable))
When the `Observable` is [subscribe](https://tc39.github.io/proposal-observable/#observable-prototype-subscribe)d, it starts to download the tar archive, extract it and successively send extraction progress to its [`Observer`](https://github.com/tc39/proposal-observable#observer).
When the [`Subscription`](https://tc39.github.io/proposal-observable/#subscription-objects) is [unsubscribe](https://tc39.github.io/proposal-observable/#subscription-prototype-unsubscribe)d, it stops downloading and extracting.
It automatically unzips gzipped archives.
#### Progress
Every progress object have two properties `entry` and `response`.
##### entry
Type: [`tar.ReadEntry`](https://github.com/npm/node-tar#class-tarreadentry-extends-minipass)
An instance of [node-tar](https://github.com/npm/node-tar)'s [`ReadEntry`](https://github.com/npm/node-tar/blob/v4.4.2/lib/read-entry.js) object.
For example you can get the progress of each entry as a percentage by `100 - progress.entry.remain / progress.entry.size * 100`.
```javascript
dlTar('https://****.org/my-archive.tar', 'my/dir')
.filter(progress => progress.entry.type === 'File')
.subscribe(progress => {
console.log(`${(100 - progress.entry.remain / progress.entry.size * 100).toFixed(1)} %`);
if (progress.entry.remain === 0) {
console.log(`>> OK ${progress.entry.header.path}`);
}
});
```
```
0.0 %
0.1 %
0.3 %
0.4 %
︙
99.6 %
99.8 %
99.9 %
100.0 %
>> OK bin/app.exe
0.0 %
0.1 %
0.2 %
0.3 %
︙
```
##### response
Type: `Object {bytes: , headers: , url: }`
`response.url` is the final redirected URL of the request, `response.headers` is a [response header object](https://nodejs.org/api/http.html#http_message_headers) derived from [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage), and `response.bytes` is a total content length of the downloaded archive. `content-length` header will be converted to `number` if it's `string`.
#### Options
You can pass options to [Request](https://github.com/request/request#requestoptions-callback) and [node-tar](https://www.npmjs.com/package/tar)'s [`Unpack` constructor](https://github.com/npm/node-tar#class-tarunpack). Note that:
* `onentry` option is not supported.
* `strict` option defaults to `true`, not `false`.
* `strip` option defaults to `1`, not `0`. That means the top level directory is stripped off by default.
## License
[ISC License](./LICENSE) © 2017 - 2018 Shinnosuke Watanabe