node-stream-zip

What is node-stream-zip?

The node-stream-zip npm package is a library designed for node.js that allows for efficient, stream-based operations on ZIP archives. It enables reading entries, extracting files, and navigating through the structure of ZIP files without needing to decompress the entire archive upfront. This makes it particularly useful for applications that need to work with large ZIP files or require selective access to archive contents.

What are node-stream-zip's main functionalities?

Opening and reading ZIP archive

This code demonstrates how to open a ZIP file and read the number of entries (files and directories) it contains using the node-stream-zip package. It utilizes the async API for non-blocking operations.

const StreamZip = require('node-stream-zip');
const zip = new StreamZip.async({ file: './path/to/zipfile.zip' });
async function readZip() {
  const entriesCount = await zip.entriesCount;
  console.log(`Entries read: ${entriesCount}`);
  await zip.close();
}
readZip();

Extracting a file from ZIP archive

This example shows how to extract a specific file from a ZIP archive to a desired location on the filesystem. It highlights the package's capability to handle individual file extraction efficiently.

const StreamZip = require('node-stream-zip');
const zip = new StreamZip.async({ file: './path/to/zipfile.zip' });
async function extractFile() {
  await zip.extract('path/inside/zip.txt', './output/path/extracted.txt');
  console.log('File extracted');
  await zip.close();
}
extractFile();

Listing all entries in ZIP archive

This snippet is an example of how to list all entries (files and directories) in a ZIP archive. It demonstrates the package's ability to navigate and read the archive's structure.

const StreamZip = require('node-stream-zip');
const zip = new StreamZip.async({ file: './path/to/zipfile.zip' });
async function listEntries() {
  const entries = await zip.entries();
  for (const entry of Object.values(entries)) {
    console.log(entry.name);
  }
  await zip.close();
}
listEntries();

Other packages similar to node-stream-zip

adm-zip

adm-zip is a JavaScript implementation for zip data compression for NodeJS. It provides functionalities similar to node-stream-zip, such as reading and extracting zip files. However, adm-zip does not focus as much on stream-based operations, which can make it less efficient for large files or selective extraction scenarios.

jszip

jszip is another popular library for creating, reading, and editing .zip files with JavaScript, both in node environments and in the browser. Unlike node-stream-zip, jszip offers broader compatibility with web applications but might not offer the same level of efficiency for node.js specific stream-based operations.

yauzl

yauzl is a minimalistic zip archive reader for Node.js, focusing on low memory usage. It is similar to node-stream-zip in its emphasis on non-blocking, stream-based operations for reading zip files. However, yauzl has a more minimalistic API and might require more manual handling for certain tasks compared to node-stream-zip.

README

node-stream-zip

node.js library for reading and extraction of ZIP archives.
Features:

• it never loads entire archive into memory, everything is read by chunks
• large archives support
• all operations are non-blocking, no sync i/o
• fast initialization
• no dependencies, no binary addons
• decompression with built-in zlib module
• deflate, sfx, macosx/windows built-in archives
• ZIP64 support

Installation

npm i node-stream-zip

Usage

There are two APIs provided:

1. promise-based / async
2. callbacks

It's recommended to use the new, promise API, however the legacy callback API may be more flexible for certain operations.

Async API

Open a zip file

const StreamZip = require('node-stream-zip');
const zip = new StreamZip.async({ file: 'archive.zip' });

Stream one entry to stdout

const stm = await zip.stream('path/inside/zip.txt');
stm.pipe(process.stdout);
stm.on('end', () => zip.close());

Read a file as buffer

const data = await zip.entryData('path/inside/zip.txt');
await zip.close();

Extract one file to disk

await zip.extract('path/inside/zip.txt', './extracted.txt');
await zip.close();

List entries

const entriesCount = await zip.entriesCount;
console.log(`Entries read: ${entriesCount}`);

const entries = await zip.entries();
for (const entry of Object.values(entries)) {
    const desc = entry.isDirectory ? 'directory' : `${entry.size} bytes`;
    console.log(`Entry ${entry.name}: ${desc}`);
}

// Do not forget to close the file once you're done
await zip.close();

Extract a folder from archive to disk

fs.mkdirSync('extracted');
await zip.extract('path/inside/zip/', './extracted');
await zip.close();

Extract everything

fs.mkdirSync('extracted');
const count = await zip.extract(null, './extracted');
console.log(`Extracted ${count} entries`);
await zip.close();

When extracting a folder, you can listen to extract event

zip.on('extract', (entry, file) => {
    console.log(`Extracted ${entry.name} to ${file}`);
});

entry event is generated for every entry during loading

zip.on('entry', entry => {
    // you can already stream this entry,
    // without waiting until all entry descriptions are read (suitable for very large archives)
    console.log(`Read entry ${entry.name}`);
});

Callback API

Open a zip file

const StreamZip = require('node-stream-zip');
const zip = new StreamZip({ file: 'archive.zip' });

// Handle errors
zip.on('error', err => { /*...*/ });

List entries

zip.on('ready', () => {
    console.log('Entries read: ' + zip.entriesCount);
    for (const entry of Object.values(zip.entries())) {
        const desc = entry.isDirectory ? 'directory' : `${entry.size} bytes`;
        console.log(`Entry ${entry.name}: ${desc}`);
    }
    // Do not forget to close the file once you're done
    zip.close();
});

Stream one entry to stdout

zip.on('ready', () => {
    zip.stream('path/inside/zip.txt', (err, stm) => {
        stm.pipe(process.stdout);
        stm.on('end', () => zip.close());
    });
});

Extract one file to disk

zip.on('ready', () => {
    zip.extract('path/inside/zip.txt', './extracted.txt', err => {
        console.log(err ? 'Extract error' : 'Extracted');
        zip.close();
    });
});

Extract a folder from archive to disk

zip.on('ready', () => {
    fs.mkdirSync('extracted');
    zip.extract('path/inside/zip/', './extracted', err => {
        console.log(err ? 'Extract error' : 'Extracted');
        zip.close();
    });
});

Extract everything

zip.on('ready', () => {
    fs.mkdirSync('extracted');
    zip.extract(null, './extracted', (err, count) => {
        console.log(err ? 'Extract error' : `Extracted ${count} entries`);
        zip.close();
    });
});

Read a file as buffer in sync way

zip.on('ready', () => {
    const data = zip.entryDataSync('path/inside/zip.txt');
    zip.close();
});

When extracting a folder, you can listen to extract event

zip.on('extract', (entry, file) => {
    console.log(`Extracted ${entry.name} to ${file}`);
});

entry event is generated for every entry during loading

zip.on('entry', entry => {
    // you can already stream this entry,
    // without waiting until all entry descriptions are read (suitable for very large archives)
    console.log(`Read entry ${entry.name}`);
});

Options

You can pass these options to the constructor

• storeEntries: true - you will be able to work with entries inside zip archive, otherwise the only way to access them is entry event
• skipEntryNameValidation: true - by default, entry name is checked for malicious characters, like ../ or c:\123, pass this flag to disable validation errors

Methods

• zip.entries() - get all entries description
• zip.entry(name) - get entry description by name
• zip.stream(entry, function(err, stm) { }) - get entry data reader stream
• zip.entryDataSync(entry) - get entry data in sync way
• zip.close() - cleanup after all entries have been read, streamed, extracted, and you don't need the archive

Building

The project doesn't require building. To run unit tests with nodeunit:

npm test

Known issues

• utf8 file names

Out of scope

• AES encrypted files: the library will throw an error if you try to open it

Contributors

ZIP parsing code has been partially forked from cthackers/adm-zip (MIT license).