or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

extraction.mdindex.mdopen.mdparse-one.mdparsing.md
tile.json

tessl/npm-unzipper

Cross-platform streaming API for ZIP file extraction and manipulation in Node.js environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unzipper@0.12.x

To install, run

npx @tessl/cli install tessl/npm-unzipper@0.12.0

index.mddocs/

Unzipper

Unzipper is a cross-platform streaming API for ZIP file extraction and manipulation in Node.js environments. It provides multiple methods for opening ZIP files from various sources including local files, URLs, Amazon S3, and in-memory buffers, with support for streaming individual files without loading entire archives into memory. It also supports Chrome extension (CRX) files.

Package Information

  • Package Name: unzipper
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install unzipper

Core Imports

const { Parse, ParseOne, Extract, Open } = require("unzipper");

For ES modules:

import { Parse, ParseOne, Extract, Open } from "unzipper";

Basic Usage

const unzipper = require("unzipper");
const fs = require("fs");

// Extract entire ZIP archive to directory
fs.createReadStream("archive.zip")
  .pipe(unzipper.Extract({ path: "output" }));

// Parse ZIP file and handle each entry
fs.createReadStream("archive.zip")
  .pipe(unzipper.Parse())
  .on("entry", (entry) => {
    const fileName = entry.path;
    const type = entry.type; // 'Directory' or 'File'
    
    if (type === "File") {
      entry.pipe(fs.createWriteStream(fileName));
    } else {
      entry.autodrain();
    }
  });

// Open ZIP file and access directory structure
const directory = await unzipper.Open.file("archive.zip");
const file = directory.files.find(f => f.path === "readme.txt");
const content = await file.buffer(); // or file.stream()

Architecture

Unzipper is designed around streaming principles with four core components:

  • Parse Stream: Low-level streaming parser that emits events for each ZIP entry
  • ParseOne Stream: Specialized parser for extracting single files from archives
  • Extract Stream: High-level transform stream for complete archive extraction
  • Open Interface: Promise-based API for random access to ZIP contents from multiple sources
  • Entry Objects: Represent individual files/directories with metadata and streaming access

The library maintains a low memory footprint through stream-based processing, allowing handling of large archives without loading them entirely into memory.

Capabilities

Stream Parsing

Low-level streaming ZIP parser that processes archives entry-by-entry, ideal for selective extraction and custom processing workflows.

class Parse extends PullStream {
  constructor(options?: ParseOptions);
  promise(): Promise<void>;
  autodrain(): void;
  buffer(): void;
}

interface ParseOptions {
  verbose?: boolean;
}

Stream Parsing

Single File Extraction

Specialized parser for extracting only the first matching file from a ZIP archive, perfect for scenarios where you need specific files without processing the entire archive.

function ParseOne(match?: RegExp): Parse;

Single File Extraction

Full Archive Extraction

Transform stream for extracting entire ZIP archives to the filesystem with configurable concurrency and destination paths.

class Extract extends Transform {
  constructor(options: ExtractOptions);
}

interface ExtractOptions {
  path: string;
  concurrency?: number;
}

Full Archive Extraction

Random Access Interface

Promise-based API for opening ZIP files from multiple sources (filesystem, URLs, S3, buffers) and accessing their contents with random access patterns.

interface Open {
  file(path: string, options?: OpenOptions): Promise<Directory>;
  url(requestLibrary: any, url: string, options?: OpenOptions): Promise<Directory>;
  s3(awsSdk: any, params: S3Parameters, options?: OpenOptions): Promise<Directory>;
  buffer(buffer: Buffer, options?: OpenOptions): Promise<Directory>;
  custom(source: any, options?: OpenOptions): Promise<Directory>;
}

interface Directory {
  files: File[];
  extract(): Promise<void>;
}

interface File {
  path: string;
  type: string;
  stream(): ReadableStream;
  buffer(): Promise<Buffer>;
}

Random Access Interface

Types

interface Entry {
  path: string;
  type: 'Directory' | 'File';
  vars: {
    uncompressedSize: number;
  };
  props: object;
  extra: object;
  pipe(destination: WritableStream): void;
  autodrain(): void;
}

interface OpenOptions {
  /** Enable verbose logging during operations */
  verbose?: boolean;
  /** Custom encoding for text files */
  encoding?: string;
  /** Additional configuration options */
  [key: string]: any;
}

interface S3Parameters {
  Bucket: string;
  Key: string;
  // Additional S3 parameters
}