tessl/npm-unzipper

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

—

Pending

Overview

Eval results

Files

Stream Parsing

Name: tessl/npm-unzipper
Author: tessl

Stream-based ZIP file parser that processes archives entry-by-entry through event emission. This low-level interface provides maximum flexibility for custom processing workflows and selective extraction patterns.

Capabilities

Parse Stream Constructor

Creates a parsing stream that processes ZIP file entries and emits events for each file or directory encountered.

/**
 * Creates a streaming ZIP parser that emits entry events
 * @param options - Optional configuration object
 * @returns Parse stream instance
 */
class Parse extends PullStream {
  constructor(options?: ParseOptions);
}

interface ParseOptions {
  /** Enable verbose logging during parsing */
  verbose?: boolean;
}

Usage Examples:

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

// Basic parsing with entry handling
fs.createReadStream("archive.zip")
  .pipe(new unzipper.Parse())
  .on("entry", (entry) => {
    console.log(`Found: ${entry.path} (${entry.type})`);
    
    if (entry.type === "File") {
      // Process file entry
      entry.pipe(fs.createWriteStream(`extracted/${entry.path}`));
    } else {
      // Skip directory entries
      entry.autodrain();
    }
  })
  .on("finish", () => {
    console.log("Parsing completed");
  });

// Verbose parsing
const parser = new unzipper.Parse({ verbose: true });
fs.createReadStream("archive.zip").pipe(parser);

Promise Interface

Converts the streaming operation to a Promise for async/await compatibility.

/**
 * Returns a Promise that resolves when parsing completes
 * @returns Promise resolving when stream finishes
 */
promise(): Promise<void>;

Usage Examples:

const parser = fs.createReadStream("archive.zip")
  .pipe(new unzipper.Parse())
  .on("entry", (entry) => {
    // Handle entries
    entry.autodrain();
  });

// Wait for completion
await parser.promise();
console.log("All entries processed");

Stream Management

Methods for controlling stream flow and preventing backpressure issues.

/**
 * Drains the stream to prevent blocking
 */
autodrain(): void;

/**
 * Buffers the entire stream contents in memory
 */
buffer(): void;

Events

Entry Event

Emitted for each file or directory found in the ZIP archive.

/**
 * Emitted for each entry (file/directory) in the ZIP archive
 * @param entry - Entry object representing the file or directory
 */
parser.on('entry', (entry: Entry) => {
  // Handle entry
});

interface Entry {
  /** Path of the file/directory within the archive */
  path: string;
  /** Type of entry: 'File' or 'Directory' */
  type: 'File' | 'Directory';
  /** Metadata about the entry */
  vars: {
    uncompressedSize: number;
  };
  /** Additional ZIP properties */
  props: object;
  /** Extra field data */
  extra: object;
  
  /** Pipe entry content to a writable stream */
  pipe(destination: WritableStream): WritableStream;
  /** Skip this entry and continue parsing */
  autodrain(): void;
}

Stream Events

Standard Node.js stream events for monitoring parsing progress.

// Parsing completed successfully
parser.on('finish', () => {
  console.log('Parsing finished');
});

// End of stream reached
parser.on('end', () => {
  console.log('Stream ended');
});

// Stream closed
parser.on('close', () => {
  console.log('Stream closed');
});

// Error occurred during parsing
parser.on('error', (error: Error) => {
  console.error('Parsing error:', error);
});

// Chrome extension header detected (CRX files)
parser.on('crx-header', () => {
  console.log('Chrome extension file detected');
});

Advanced Usage

Selective Extraction

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

fs.createReadStream("archive.zip")
  .pipe(new unzipper.Parse())
  .on("entry", (entry) => {
    const fileName = entry.path;
    const type = entry.type;
    
    // Only extract .txt files
    if (type === "File" && fileName.endsWith(".txt")) {
      entry.pipe(fs.createWriteStream(path.basename(fileName)));
    } else {
      entry.autodrain();
    }
  });

Entry Filtering and Processing

const processedFiles = [];

fs.createReadStream("archive.zip")
  .pipe(new unzipper.Parse())
  .on("entry", (entry) => {
    if (entry.type === "File" && entry.vars.uncompressedSize > 0) {
      // Collect file information
      processedFiles.push({
        path: entry.path,
        size: entry.vars.uncompressedSize
      });
      
      // Process file content
      let content = '';
      entry.on('data', (chunk) => {
        content += chunk.toString();
      });
      
      entry.on('end', () => {
        console.log(`Processed ${entry.path}: ${content.length} chars`);
      });
    } else {
      entry.autodrain();
    }
  })
  .on("finish", () => {
    console.log(`Processed ${processedFiles.length} files`);
  });

Install with Tessl CLI