# `@particle/unpack-file`

unpack .tar.gz and .zip files, optionally reporting progress


## Installation

```shell
npm install @particle/unpack-file --save
```
<!-- private-module-note-start -->

<!-- private-module-note-end -->

## API
<!-- api-docs-start -->
<a name="module_@particle/unpack-file"></a>

### @particle/unpack-file

* [@particle/unpack-file](#module_@particle/unpack-file)
    * _static_
        * [.unpackTarGz(source, destination, [options])](#module_@particle/unpack-file.unpackTarGz) ⇒ <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code>
        * [.unpackZip(source, destination, [options])](#module_@particle/unpack-file.unpackZip) ⇒ <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code>
    * _inner_
        * [~UnpackedFile](#module_@particle/unpack-file..UnpackedFile) : <code>Object</code>


* * *

<a name="module_@particle/unpack-file.unpackTarGz"></a>

#### unpackFile.unpackTarGz(source, destination, [options]) ⇒ <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code>
Unpack a tarball (`.tar.gz`, `.tgz`, etc) file and optionally report progress.

**Kind**: static method of [<code>@particle/unpack-file</code>](#module_@particle/unpack-file)  
**Returns**: <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code> - A promise for the downloaded file or
an error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| source | <code>string</code> |  | Absolute path to the tarball you want to unpack |
| destination | <code>string</code> |  | Absolute path to the directory where unpacked bits will be saved |
| [options] | <code>object</code> |  |  |
| [options.onProgress] | <code>function</code> |  | Function to call with progess info (optional) |
| [options.interval] | <code>number</code> | <code>100</code> | How often to report progress in milliseconds (optional) |

**Example**  
```js
const source = '/path/to/my.tar.gz';
const destination = '/path/to/folder';

// unpack a tarball
const { dirname } = await unpackTarGz(source, destination);

// unpack a tarball and report progress
const onProgress = (progress) => console.log(progress);
const options = { onProgress, interval: 250 };
const { dirname } = await unpackTarGz(source, destination, options);
```

* * *

<a name="module_@particle/unpack-file.unpackZip"></a>

#### unpackFile.unpackZip(source, destination, [options]) ⇒ <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code>
Unpack a zip (`.zip`, etc) file and optionally report progress.

**Kind**: static method of [<code>@particle/unpack-file</code>](#module_@particle/unpack-file)  
**Returns**: <code>Promise.&lt;(UnpackedFile\|Error)&gt;</code> - A promise for the downloaded file or
an error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| source | <code>string</code> |  | Absolute path to the zip file you want to unpack |
| destination | <code>string</code> |  | Absolute path to the directory where unpacked bits will be saved |
| [options] | <code>object</code> |  |  |
| [options.onProgress] | <code>function</code> |  | Function to call with progess info (optional) |
| [options.interval] | <code>number</code> | <code>100</code> | How often to report progress in milliseconds (optional) |

**Example**  
```js
const source = '/path/to/my.zip';
const destination = '/path/to/folder';

// unpack a tarball
const { dirname } = await unpackZip(source, destination);

// unpack a tarball and report progress
const onProgress = (progress) => console.log(progress);
const options = { onProgress, interval: 250 };
const { dirname } = await unpackZip(source, destination, options);
```

* * *

<a name="module_@particle/unpack-file..UnpackedFile"></a>

#### @particle/unpack-file~UnpackedFile : <code>Object</code>
Object returned after successfully unpacking a file

**Kind**: inner typedef of [<code>@particle/unpack-file</code>](#module_@particle/unpack-file)  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| dirname | <code>string</code> | Absolute path to the directory containing your unpacked files |


* * *


<!-- api-docs-end -->

_NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in [tests](./src/index.test.js)_


