zipstream

A lightweight, zero-dependency ZIP parser for modern browsers.

zipstream uses the native DecompressionStream API and optional Web Worker execution for responsive UI and extraction progress reporting.

Features

• No third-party runtime dependencies
• Browser-native decompression with DecompressionStream
• Web Worker parsing with progress callbacks
• Metadata-first APIs for quick ZIP inspection
• Friendly API for text, JSON, and binary entry reads
• Designed for diagnostics and log archive workflows

Install

npm install zipstream

Quick Start

import { parseZip } from 'zipstream';

const buffer = await file.arrayBuffer();
const archive = await parseZip(buffer, {
	validateCrc: false,
	onProgress(progress) {
		console.log(progress.percentComplete, progress.currentFile);
	},
});

const entry = archive.getEntry('browser_rundown_report.json');
if (entry) {
	const json = await entry.json();
	console.log(json);
}

Worker Mode

import { parseZipWorker } from 'zipstream';

const archive = await parseZipWorker(await file.arrayBuffer(), {
	onProgress(p) {
		updateProgressBar(p.percentComplete);
		updateStatus(`${p.filesProcessed}/${p.totalFiles} ${p.currentFile}`);
	},
	fallbackToMainThread: true,
});

API

parseZip(buffer, options)

Parses a ZIP buffer and returns a ZipArchive.

Options:

• validateCrc: boolean, default false
• preload: boolean, default true
• onProgress: function(progress)

parseZipWorker(buffer, options)

Parses ZIP in a module worker and returns a ZipArchive.

Options:

• validateCrc: boolean, default false
• onProgress: function(progress)
• workerUrl: URL or string (optional custom worker location)
• fallbackToMainThread: boolean, default true

listEntriesSync(buffer)

Returns file metadata without extracting payloads.

Progress Payload

{
	filesProcessed: number;
	totalFiles: number;
	currentFile: string;
	percentComplete: number;
}

Entry Interface

Each archive entry exposes:

• name
• size
• compressedSize
• method
• isDirectory
• arrayBuffer()
• text()
• json()

Supported ZIP Features

• ZIP local file headers + central directory
• Compression methods:
  • Stored (0)
  • Deflate (8 via deflate-raw)

Not supported:

• ZIP64
• Encryption/password-protected archives
• Split/multi-volume archives
• Exotic compression methods

Browser Support

Requires a browser runtime with:

• DecompressionStream
• ES modules
• Web Workers (optional, but recommended)

Demo

Open demo/index.html from a local static server and load a ZIP file.

Example:

npx serve .

Then open /demo/index.html.

License

MIT