zip

The archive/zip module creates and extracts ZIP archives in JSH. It provides in-memory helpers, stream-style APIs, and a file-based Zip class.

Use the API that matches your task:

• Use zipSync() and unzipSync() when the archive is already in memory.
• Use Zip when you want to read files, save .zip files, or extract them to disk.
• Use createZip() and createUnzip() when you want event-driven processing.

Installation

const zip = require('archive/zip');

zipSync()

Creates a ZIP archive synchronously.

Syntax

zipSync(data)

Parameters

• data String | ArrayBuffer | Uint8Array | Number[] | Object[]

If data is a single string or byte buffer, the created entry name defaults to data. If data is an array, each item should be an entry object such as { name, data }.

Return value

Returns an ArrayBuffer that contains ZIP archive bytes.

This form is useful for quick tests or for building an archive before writing it somewhere else.

Usage example

1
2
3
4
5
6

const zip = require('archive/zip');
const archive = zip.zipSync([
	{ name: 'alpha.txt', data: 'Alpha' },
	{ name: 'dir/beta.txt', data: 'Beta' }
]);
console.println(archive.constructor.name);

1
2
3
4

const zip = require('archive/zip');
const archive = zip.zipSync('hello zip');
const entries = zip.unzipSync(archive);
console.println(entries[0].name, new Uint8Array(entries[0].data).length);

unzipSync()

Extracts ZIP archive bytes synchronously and returns entry objects.

Syntax

unzipSync(buffer)

Parameters

• buffer ArrayBuffer | Uint8Array | Number[]

Return value

Returns an array of entry objects.

Each entry can include name, data, comment, method, compressedSize, size, isDir, and modified.

Usage example

1
2
3
4
5
6
7
8
9

const zip = require('archive/zip');
const archive = zip.zipSync([
	{ name: 'one.txt', data: 'One' },
	{ name: 'two.txt', data: 'Two' }
]);
const entries = zip.unzipSync(archive);
console.println(entries[0].name, entries[0].size);
console.println(entries[1].name, entries[1].size);
console.println(entries.length);

zip()

Provides a callback-style asynchronous wrapper for ZIP archive creation.

Syntax

zip(data, callback)

The callback follows the (err, archive) form.

unzip()

Provides a callback-style asynchronous wrapper for ZIP extraction.

Syntax

unzip(buffer, callback)

The callback follows the (err, entries) form.

Use these wrappers when you want callback-based control flow without managing stream events directly.

Usage example

1
2
3
4
5
6
7
8
9

const zip = require('archive/zip');

zip.zip('payload', function(err, archive) {
	if (err) throw err;
	zip.unzip(archive, function(err2, entries) {
		if (err2) throw err2;
		console.println(entries[0].name, new Uint8Array(entries[0].data).length);
	});
});

createZip()

Creates a stream-style ZIP writer.

The returned object accepts entry objects through write() and emits archive bytes through the data event when end() is called.

This API is event-driven, but it still finalizes work on end() rather than emitting extracted files progressively like a Node.js file stream.

Syntax

createZip()

createUnzip()

Creates a stream-style ZIP reader.

Write archive bytes with write(), then call end() to emit one entry event per extracted item.

Syntax

createUnzip()

Usage example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const zip = require('archive/zip');
const writer = zip.createZip();
let archive = null;

writer.on('data', function(chunk) {
	archive = chunk;
});

writer.on('end', function() {
	const reader = zip.createUnzip();
	reader.on('entry', function(entry) {
		const text = String.fromCharCode.apply(null, new Uint8Array(entry.data));
		console.println(entry.name + '=' + text);
	});
	reader.write(archive);
	reader.end();
});

writer.write({ name: 'one.txt', data: 'One' });
writer.write({ name: 'two.txt', data: 'Two' });
writer.end();

Zip

Zip is a file-oriented helper class for building, saving, loading, and extracting ZIP archives.

Constructor

new zip.Zip(filePath?)

If filePath is provided, the archive is loaded from that file.

addFile()

Reads a file from the filesystem and appends it as an archive entry.

addFile(filePath[, entryName])

addBuffer()

Appends a string or byte buffer as an archive entry.

addBuffer(data, entryName[, options])

addEntry()

Appends an archive entry object directly.

addEntry(entry)

Supported ZIP entry fields:

• name String required entry path
• data String | ArrayBuffer | Uint8Array | Number[] file content
• comment String entry comment
• method Number compression method

addFile() is the most direct option when the source data already exists on disk. addBuffer() is useful when the content is generated in memory. addEntry() is helpful when you also want to attach entry metadata such as comment.

getEntries()

Returns a shallow copy of the current archive entries.

getEntries()

writeTo()

Writes the archive to a file.

writeTo(filePath)

extractAllTo()

Extracts entries to a directory.

extractAllTo(outputDir[, overwrite])
extractAllTo(outputDir, options)
extractAllTo(outputDir, overwrite, options)

options supports:

• overwrite Boolean overwrite existing files when true
• filter Function | RegExp | String | String[] selects which entries to extract

Usage example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const zip = require('archive/zip');

const z = new zip.Zip();
z.addBuffer('hello world', 'app.log');
z.addEntry({ name: 'config.json', data: '{"enabled":true}' });
z.writeTo('/tmp/data.zip');

const saved = new zip.Zip('/tmp/data.zip');
saved.extractAllTo('/tmp/out', {
	overwrite: true,
	filter: function(entry) {
		return entry.name === 'app.log';
	}
});

Usage example: create from files and extract again

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

const fs = require('fs');
const zip = require('archive/zip');
const base = '/tmp/zip-files';

fs.mkdir(base + '/input', { recursive: true });
fs.writeFile(base + '/input/one.txt', 'One', 'utf8');
fs.writeFile(base + '/input/two.txt', 'Two', 'utf8');

const archive = new zip.Zip();
archive.addFile(base + '/input/one.txt');
archive.addFile(base + '/input/two.txt', 'renamed-two.txt');
archive.writeTo(base + '/sample.zip');

const loaded = new zip.Zip(base + '/sample.zip');
loaded.extractAllTo(base + '/out', true);
console.println(fs.readFile(base + '/out/renamed-two.txt', 'utf8'));

Usage example: filter extraction

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const zip = require('archive/zip');
const fs = require('fs');
const base = '/tmp/zip-filter';

const archive = zip.zipSync([
	{ name: 'keep/a.txt', data: 'A' },
	{ name: 'keep/b.log', data: 'B' },
	{ name: 'skip/c.txt', data: 'C' }
]);

fs.writeFile(base + '.zip', Array.from(new Uint8Array(archive)), 'buffer');

const loaded = new zip.Zip(base + '.zip');
loaded.extractAllTo(base + '-out', {
	overwrite: true,
	filter: /\.txt$/
});

Notes

• filter may be a callback, RegExp, string match, or array of entry names.
• extractAllTo() throws an error if the destination file already exists and overwrite is false.
• ZIP entry metadata includes comment, method, compressedSize, and size when available.
• ZIP entries do not support TAR link metadata such as symlink or linkname.