@codler/decompress

Decompress files and archives such as ZIP, TAR, TAR.BZ2, TAR.GZ

Installation

npm install @codler/decompress

Usage

import decompress from "@codler/decompress";

const files = await decompress("archive.zip", "output");

for (const file of files) {
  console.log(file.path);
}

The input can be a file path, a Buffer, or a ReadableStream. The output path is optional; pass options as the second argument when an output path is not needed.

const files = await decompress(buffer, {
  filter: (file) => file.type === "file",
  strip: 1,
});

Using a ReadableStream:

import { createReadStream } from "node:fs";
import { Readable } from "node:stream";
import decompress from "@codler/decompress";

const stream = Readable.toWeb(createReadStream("archive.zip"));
const files = await decompress(stream, "output");

API

decompress(input, output?, options?)

Decompresses input and resolves with the extracted files.

Parameters

input

string | Buffer | ReadableStream<Uint8Array>;

The path to an archive, its contents as a Buffer, or a ReadableStream of the archive contents.

output

string | DecompressOptions;

The directory where files should be extracted. This argument is optional. It can instead be an options object when no output directory is provided.

options

type DecompressOptions = {
  filter?(file: File): boolean;
  map?(file: File): File;
  plugins?: readonly Plugin[];
  strip?: number;
};

Options can be supplied as the third argument when output is a directory.

| Option | Type | Default | Description | | --------- | ------------------------- | ------------------------ | ---------------------------------------------------------- | | filter | (file: File) => boolean | undefined | Filters files before extraction. | | map | (file: File) => File | undefined | Transforms files before extraction. | | plugins | readonly Plugin[] | Built-in archive plugins | Plugins used to process archives. | | strip | number | 0 | Removes leading directory components from extracted paths. |

Returns

Promise<File[]>;

The promise resolves with the files processed by the decompressor.

File

Each file has the following properties:

type File = {
  data: Buffer;
  mode: number;
  mtime: string | Date;
  path: string;
  type: "file" | "directory" | "symlink" | "link";
  linkname?: string;
};

• data: File contents.
• mode: File mode.
• mtime: Last modification time.
• path: File path.
• type: Entry type, such as file, directory, symlink or link.
• linkname: Target path for symlink and hardlink entries.

Plugins

Unless plugins is provided, the API is configured for:

• TAR
• TAR.BZ2
• TAR.GZ
• ZIP

Author

Han Lin Yap (yap.nu)