@jeffy-g/unzip

Streaming ZIP extraction helper and CLI powered by fflate.

Default extraction uses a streaming path, so large ZIP files do not need to be expanded in memory first. The package also ships with a small CLI progress renderer via progress-light.js.

Features

• Stream-first extraction for lower memory usage
• Legacy memory mode for compatibility
• CLI with verbose logging or single-line progress output
• Callback-based API for entry-level progress reporting
• CommonJS package with bundled type definitions

Install

npm i @jeffy-g/unzip

If you want to use the CLI globally:

npm i -g @jeffy-g/unzip

CLI

The command name is ffunzip.

ffunzip [-v] [-p|-progress] [-d <dir>] [-m|-mode <stream|memory>] <zip-file> [more.zip ...]

Options

Option	Description
-d <dir>	Extraction target directory. Default: ./output
-v	Print verbose entry logs
-p, -progress	Show the bundled single-line progress renderer. Implies verbose logging
-m, -mode <stream|memory>	Extraction mode. Default: stream
-h, -help	Print help

Notes

• Long options use a single dash because the CLI is parsed by tin-args
• stream is the default and recommended mode
• memory uses the previous all-at-once extraction path

Examples

ffunzip archive.zip
ffunzip -d ./output bundle.zip
ffunzip -p -mode memory huge.zip
ffunzip -v first.zip second.zip third.zip

API

const unzipWithCallback = require("@jeffy-g/unzip");

/** @type {TUnzipCallback} */
const withCallback = (entry) => {
  if (typeof entry === "string") {
    console.log(`done: ${entry}`);
    return;
  }

  if (entry.state === "info") {
    console.log(`scan [${entry.type === "File" ? "f" : "d"}]: ${entry.path}`.gray(14));
    return;
  }

  if (entry.state === "ignore" || entry.type === "Folder") {
    return;
  }

  const color = entry.state === "pending" ? "cyan" : "green";
  console.log(`${entry.state} - ${
    entry.path[color]
  }${entry.state !== "write" ? `, size: ${entry.size?.toLocaleString().blue}` : ""}`);
};

unzipWithCallback("archive.zip", "./output", withCallback);
// same as unzipWithCallback.stream(...)

unzipWithCallback.memory("archive.zip", "./output", withCallback);
unzipWithCallback.legacy("archive.zip", "./output", withCallback);

Callback states

State	Meaning
info	Entry discovered while scanning the ZIP
pending	File extraction is about to start
write	File extraction finished
ignore	Directory entry was handled without file output

Exported members

• unzipWithCallback(...)
• unzipWithCallback.stream(...)
• unzipWithCallback.memory(...)
• unzipWithCallback.legacy(...)
• unzipWithCallback.version

Runtime dependencies

• fflate
• colors.ts
• tin-args

License

MIT