# @xingrz/decompress

> Extracting archives made easy

Latest version **5.2.0-alpha.1** (published 2021-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @xingrz/decompress
pnpm add @xingrz/decompress
yarn add @xingrz/decompress
bun add @xingrz/decompress
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.2.0-alpha.1 |
| Published | 2021-11-13 |
| First published | 2021-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 9 |
| Unpacked size | 13.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Kevin Mårtensson |
| Maintainers | xingrz |
| Keywords | bz2, bzip2, decompress, extract, tar, tar.bz, tar.gz, tar.zst, zip, unzip |

## Links

- npm: https://www.npmjs.com/package/@xingrz/decompress
- Repository: https://github.com/xingrz/decompress
- Homepage: https://github.com/xingrz/decompress#readme
- Issues: https://github.com/xingrz/decompress/issues
- npm.io page: https://npm.io/package/@xingrz/decompress

## Dependencies (9)

- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [make-dir](https://npm.io/package/make-dir.md) ^3.1.0
- [strip-dirs](https://npm.io/package/strip-dirs.md) ^2.0.0
- [@xingrz/decompress-tar](https://npm.io/package/@xingrz/decompress-tar.md) ^5.2.0-alpha.0
- [@xingrz/decompress-targz](https://npm.io/package/@xingrz/decompress-targz.md) ^5.2.0-alpha.0
- [@xingrz/decompress-types](https://npm.io/package/@xingrz/decompress-types.md) ^5.2.0-alpha.0
- [@xingrz/decompress-unzip](https://npm.io/package/@xingrz/decompress-unzip.md) ^5.2.0-alpha.0
- [@xingrz/decompress-tarbz2](https://npm.io/package/@xingrz/decompress-tarbz2.md) ^5.2.0-alpha.0
- [@xingrz/decompress-tarzst](https://npm.io/package/@xingrz/decompress-tarzst.md) ^5.2.0-alpha.0

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 5.2.0-alpha.1 (latest) — 2021-11-13
- 5.2.0-alpha.0 — 2021-11-13
- 5.1.0-alpha.1 — 2021-11-12
- 5.1.0-alpha.0 — 2021-11-12
- 5.0.0-alpha.10 — 2021-11-11
- 5.0.0-alpha.8 — 2021-11-11
- 5.0.0-alpha.7 — 2021-11-03
- 5.0.0-alpha.6 — 2021-11-03
- 5.0.0-alpha.5 — 2021-11-03
- 5.0.0-alpha.4 — 2021-11-03
- 5.0.0-alpha.3 — 2021-11-02
- 5.0.0-alpha.2 — 2021-11-02
- 5.0.0-alpha.1 — 2021-11-02
- 5.0.0-alpha.0 — 2021-11-01

## README

@xingrz/decompress [![test](https://github.com/xingrz/decompress/actions/workflows/test.yml/badge.svg)](https://github.com/xingrz/decompress/actions/workflows/test.yml)
==========

[![][npm-version]][npm-url] [![][npm-downloads]][npm-url] [![license][license-img]][license-url] [![issues][issues-img]][issues-url] [![stars][stars-img]][stars-url] [![commits][commits-img]][commits-url]

Extracting archives made easy.

## Plugins

| package                                 | version         | format      |
| --------------------------------------- | --------------- | ----------- |
| [@xingrz/decompress-tar][tar-url]       | ![][tar-img]    | `*.tar`     |
| [@xingrz/decompress-tarbz2][tarbz2-url] | ![][tarbz2-img] | `*.tar.bz2` |
| [@xingrz/decompress-targz][targz-url]   | ![][targz-img]  | `*.tar.gz`  |
| [@xingrz/decompress-tarzst][tarzst-url] | ![][tarzst-img] | `*.tar.zst` |
| [@xingrz/decompress-unzip][unzip-url]   | ![][unzip-img]  | `*.zip`     |

[tar-url]: https://github.com/xingrz/decompress-tar
[tar-img]: https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-tar?label=npm&style=flat-square

[tarbz2-url]: https://github.com/xingrz/decompress-tarbz2
[tarbz2-img]: https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-tarbz2?label=npm&style=flat-square

[targz-url]: https://github.com/xingrz/decompress-targz
[targz-img]: https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-targz?label=npm&style=flat-square

[tarzst-url]: https://github.com/xingrz/decompress-tarzst
[tarzst-img]: https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-tarzst?label=npm&style=flat-square

[unzip-url]: https://github.com/xingrz/decompress-unzip
[unzip-img]: https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-unzip?label=npm&style=flat-square

#### Plugin API

[![](https://img.shields.io/npm/dependency-version/@xingrz/decompress/@xingrz/decompress-types?style=flat-square)](https://github.com/xingrz/decompress-types)

## Install

```sh
npm install --save @xingrz/decompress
```

## Usage

```ts
import decompress from 'decompress';

const files = await decompress('unicorn.zip', 'dist');
console.log('done!');
```

## API

### `decompress(input[, output][, options])`

Returns a Promise for an array of [`File`](https://github.com/xingrz/decompress-types/blob/master/index.d.ts#L3)s in the following format:

```ts
interface File {
	path: string;
	type: 'file' | 'link' | 'symlink' | 'directory';
	mode: number;
	mtime: Date | string;
	data?: Buffer;
}
```

If `output` is not presented, `data` will be populated with the content of the file. Otherwise the file will be written to disk and the `data` will be undefined.

#### `input`

Type: `string` | `Buffer`

Path of file or `Buffer` to decompress.

#### `output`

Type: `string` (optional)

Path to output directory.

#### `options`

##### `filter`

Type: `(file: File) => boolean`

Filter out files before extracting. E.g:

```ts
const files = await decompress('unicorn.zip', 'dist', {
	filter: file => path.extname(file.path) !== '.exe'
});
console.log('done!');
```

*Note that in the current implementation, **`filter` is only applied after fully reading all files from the archive in memory**. Do not rely on this option to limit the amount of memory used by `decompress` to the size of the files included by `filter`. `decompress` will read the entire compressed file into memory regardless.*

##### `map`

Type: `(file: File) => File`

Map files before extracting: E.g:

```ts
const files = await decompress('unicorn.zip', 'dist', {
	map: file => {
		file.path = `unicorn-${file.path}`;
		return file;
	}
});
console.log('done!');
```

##### `plugins`

Type: `DecompressPlugin[]`

Array of [plugins](#plugins) to use. See [@xingrz/decompress-types](https://github.com/xingrz/decompress-types/blob/master/index.d.ts) for full definitions.

##### `strip`

Type: `number` (default: `0`)

Remove leading directory components from extracted files.

## License

MIT © [Kevin Mårtensson](https://github.com/kevva), [XiNGRZ](https://github.com/xingrz)

[npm-version]: https://img.shields.io/npm/v/@xingrz/decompress.svg?style=flat-square
[npm-downloads]: https://img.shields.io/npm/dm/@xingrz/decompress.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/@xingrz/decompress
[license-img]: https://img.shields.io/github/license/xingrz/decompress?style=flat-square
[license-url]: LICENSE
[issues-img]: https://img.shields.io/github/issues/xingrz/decompress?style=flat-square
[issues-url]: https://github.com/xingrz/decompress/issues
[stars-img]: https://img.shields.io/github/stars/xingrz/decompress?style=flat-square
[stars-url]: https://github.com/xingrz/decompress/stargazers
[commits-img]: https://img.shields.io/github/last-commit/xingrz/decompress?style=flat-square
[commits-url]: https://github.com/xingrz/decompress/commits/master

---
_Source: https://npm.io/package/@xingrz/decompress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._