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

1npm 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

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

Stream one entry to stdout

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

Read a file as buffer

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

Extract one file to disk

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

List entries

1const entriesCount = await zip.entriesCount;
2console.log(`Entries read: ${entriesCount}`);
3
4const entries = await zip.entries();
5for (const entry of Object.values(entries)) {
6    const desc = entry.isDirectory ? 'directory' : `${entry.size} bytes`;
7    console.log(`Entry ${entry.name}: ${desc}`);
8}
9
10// Do not forget to close the file once you're done
11await zip.close();

Extract a folder from archive to disk

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

Extract everything

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

When extracting a folder, you can listen to extract event

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

entry event is generated for every entry during loading

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

Callback API

Open a zip file

1const StreamZip = require('node-stream-zip');
2const zip = new StreamZip({ file: 'archive.zip' });
3
4// Handle errors
5zip.on('error', err => { /*...*/ });

List entries

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

Stream one entry to stdout

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

Extract one file to disk

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

Extract a folder from archive to disk

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

Extract everything

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

Read a file as buffer in sync way

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

When extracting a folder, you can listen to extract event

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

entry event is generated for every entry during loading

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

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
• nameEncoding: 'utf8' - encoding used to decode file names, UTF8 by default

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:

1npm 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).