Zip Dir

Zip Dir is a Node.js library that recursively zips directories into buffers while preserving directory structure. It provides both synchronous and asynchronous operation modes through callbacks and promises, with support for custom file filtering, progress tracking, and flexible output options.

Package Information

• Package Name: zip-dir
• Package Type: npm
• Language: JavaScript
• Installation: npm install zip-dir

Core Imports

const zipdir = require('zip-dir');

ES6 modules:

import zipdir from 'zip-dir';

Basic Usage

const zipdir = require('zip-dir');

// Promise-based usage
const buffer = await zipdir('/path/to/directory');

// Callback-based usage
zipdir('/path/to/directory', function(err, buffer) {
  if (err) throw err;
  console.log('Zip created successfully!');
});

// Save directly to disk
zipdir('/path/to/directory', { saveTo: './output.zip' }, function(err, buffer) {
  if (err) throw err;
  console.log('Zip saved to disk!');
});

Architecture

Zip Dir is built around several key components that work together to provide efficient and reliable directory compression:

• Dual API Design: Supports both Promise-based and callback-based operations (mutually exclusive)
• JSZip Integration: Uses the JSZip library internally for cross-platform zip file creation with DEFLATE compression
• Async Queue Management: Implements concurrency control with a maximum of 500 concurrent file reads to prevent resource exhaustion
• Recursive Directory Traversal: Depth-first traversal that preserves directory structure in the zip archive
• Stream Processing: Files are read and processed individually to handle large directories efficiently
• Error Propagation: Comprehensive error handling that stops processing on first error and properly propagates through callback/promise chains

Capabilities

Directory Compression

Creates a compressed zip archive from a directory, recursively including all files and subdirectories while preserving the directory structure.

/**
 * Zips up a directory recursively preserving directory structure
 * @param {string} rootDir - Path to directory to be zipped (resolved internally)
 * @param {ZipOptions|function} [options] - Configuration options or callback function
 * @param {function} [callback] - Callback function with signature (error, buffer)
 * @returns {Promise<Buffer>|undefined} Promise resolving to zip buffer when no callback provided, undefined when callback used
 */
function zipdir(rootDir, options, callback);

Parameter Handling:

• If second parameter is a function, it's treated as the callback
• Promise and callback APIs are mutually exclusive - providing a callback prevents promise return
• When options.saveTo is provided, the callback/promise waits for both zip creation and file write completion
• All paths are resolved internally to handle trailing slashes and relative paths

Options:

interface ZipOptions {
  /** Path to save the zip file to disk (uses binary encoding) */
  saveTo?: string;
  /** 
   * Function to filter files/directories during traversal
   * @param fullPath - Absolute path to the file or directory
   * @param stats - Node.js fs.Stats object with file metadata
   * @returns true to include item in zip, false to exclude
   * @note Must return true for directories to allow traversal into subdirectories
   */
  filter?(fullPath: string, stats: fs.Stats): boolean;
  /** 
   * Function called for each item added to the zip
   * @param path - For files: path relative to root directory (e.g., "subdir/file.txt")
   *             - For directories: full absolute path of the directory
   */
  each?(path: string): void;
}

Usage Examples:

const zipdir = require('zip-dir');

// Filter out temporary files and keep only JSON files
zipdir('/path/to/directory', {
  filter: (path, stat) => {
    // Allow directories to be traversed
    if (stat.isDirectory()) return true;
    // Only include JSON files
    return path.endsWith('.json');
  }
}, function(err, buffer) {
  console.log('Filtered zip created');
});

// Track progress with each callback
zipdir('/path/to/directory', {
  each: (path) => console.log('Added:', path),
  saveTo: './archive.zip'
}, function(err, buffer) {
  console.log('Archive created with progress tracking');
});

// Promise-based with options
try {
  const buffer = await zipdir('/path/to/directory', {
    filter: (path, stat) => !path.includes('.git'),
    each: (path) => console.log('Processing:', path)
  });
  console.log('Zip buffer size:', buffer.length);
} catch (error) {
  console.error('Error creating zip:', error);
}

Error Handling

The function handles various error conditions and follows Node.js error-first callback conventions. Errors stop processing immediately and are propagated through the callback/promise chain.

Common Error Scenarios:

• ENOENT: Directory does not exist or path is invalid
• ENOTDIR: Path points to a file instead of directory
• EACCES: File system permission errors during directory traversal or file reading
• EMFILE: Too many open files (mitigated by 500 file concurrency limit)
• ENOSPC: Disk space issues when using saveTo option
• JSZip Errors: Zip generation failures (e.g., file too large, memory constraints)

Error Handling Examples:

// Callback error handling
zipdir('/nonexistent/path', function(err, buffer) {
  if (err) {
    console.error('Failed to create zip:', err.message);
    return;
  }
  console.log('Success!');
});

// Promise error handling
try {
  const buffer = await zipdir('/path/to/directory');
} catch (error) {
  console.error('Zip creation failed:', error.message);
}

Types

/**
 * Node.js fs.Stats object containing file/directory metadata
 */
interface fs.Stats {
  isFile(): boolean;
  isDirectory(): boolean;
  size: number;
  mtime: Date;
  // ... other fs.Stats properties
}

Implementation Notes

• Zip Library: Uses JSZip library internally for cross-platform zip file creation
• Compression: Supports DEFLATE compression method with type: 'nodebuffer' output
• Concurrency Control: Implements async queue with maximum 500 concurrent file reads to prevent resource exhaustion and avoid EMFILE errors
• Buffer Output: Returns zip data as Node.js Buffer objects suitable for writing to disk or network transmission
• Directory Structure: Preserves original directory structure in the zip archive with files stored using relative paths from the root directory
• Path Resolution: All input paths are resolved using path.resolve() to handle relative paths and trailing slashes consistently
• File System: Uses fs.readdir(), fs.stat(), and fs.readFile() for directory traversal and file reading
• Error Handling: Stops processing on first error and propagates through callback/promise chains
• Filter Behavior: Filter function must return true for directories to allow traversal into subdirectories
• Progress Tracking:
  • For files: each callback receives path relative to root directory (e.g., "subdir/file.txt")
  • For directories: each callback receives full absolute path of the directory being processed
• File Writing: When saveTo option is used, writes with { encoding: 'binary' } to preserve zip file integrity