@zip.js/zip.js 2.8.31 → 2.8.32

package/BENCHMARKS.md

@@ -16,7 +16,9 @@ should not trust anyone's benchmark (including this one) without reproducing it.
 > `CompressionStream` run on the threadpool while you simply issue concurrent `add()`
 > calls. It also streams arbitrarily large files at a flat, low memory ceiling. For
 > deflating thousands of tiny buffers in one shot, **fflate** remains the throughput
-> and footprint champion.
+> and footprint champion. Against native tooling, zip.js on a modern runtime is a bit
+> faster *and* tighter than 7-Zip's fast mode on single-file streaming; 7-Zip keeps a
+> real edge only on thousands of tiny files.
 
 ## Environment
 
@@ -172,6 +174,80 @@ compression pipeline. **jszip buffers the entire file** and needs ~527 MB, at mo
 twice the wall-clock time. If you process files that do not fit comfortably in memory,
 avoid jszip.
 
+## Against native tooling — 7-Zip
+
+How far is zip.js from a native archiver? [`benchmarks/bench-7z.js`](benchmarks/bench-7z.js)
+compares it against the `7zz` CLI (7-Zip 25.01), disk-to-disk on both sides, under Deno
+2.9.3 and Bun 1.3.14 (both runtimes agree within noise; Deno numbers shown). 7-Zip
+timings include process spawn (~ms).
+
+One comparison is impossible to make perfectly fair: **no 7-Zip preset runs zlib's
+algorithm.** `-mx=5+` is a near-optimal parser (much slower, smaller output) and
+`-mx=1..4` a greedy one (faster, larger output) — they bracket zlib level 6. So the
+table carries two anchors: `-mx=6` as the *ratio* anchor and `-mx=1` as the *speed*
+anchor. On this machine the `-mx` ladder on the 256 MB file reads: `-mx=1/3` → 5.9 s,
+`-mx=5/6` → 34 s, `-mx=7` → 85 s — the 6× jump at `-mx=5` is the switch from greedy
+matching to optimal parsing, and it cannot be hidden by threads (one file = one deflate
+stream = one core).
+
+| Workload (compress) | zip.js (workers) | 7-Zip `-mx=6` (mt) | 7-Zip `-mx=1` (mt) |
+|---|--:|--:|--:|
+| Compressible text (20 MB) | **426 ms** / 6.2 MB | 2606 ms / 5.8 MB | 470 ms / 6.8 MB |
+| Incompressible data (20 MB) | **342 ms** | 410 ms | 372 ms |
+| 5,000 files × ~2 KB | 780 ms / 5.5 MB | 199 ms / 4.9 MB | **168 ms** / 5.0 MB |
+| Large file, disk-to-disk (256 MB) | **5.5 s** / 79.5 MB | 33.4 s / 73.6 MB | 5.9 s / 86.7 MB |
+
+| Workload (decompress) | zip.js (workers) | 7-Zip (mt) |
+|---|--:|--:|
+| Compressible text (20 MB) | **69 ms** | 88 ms |
+| 5,000 files × ~2 KB | 976 ms | **471 ms** |
+
+- **On single-file streaming, zip.js strictly dominates 7-Zip's speed tier**: a bit
+  faster *and* ~9 % smaller output, because zlib-6's lazy matching is a better
+  speed/ratio point than 7-Zip's greedy fast mode. What `-mx=6` buys for its 6× time is
+  ~7 % more compression — a trade zip.js cannot make, but also one most workloads don't
+  want.
+- **7-Zip legitimately dominates many small files** (~4× on compress, ~2× on
+  decompress): its per-entry cost is near zero, while zip.js pays per-entry
+  orchestration (worker round trips, header writes, one output stream per extracted
+  file). Same lesson as the fflate rows above — tiny-entry workloads are zip.js's cost
+  center, and the codec backend is irrelevant there.
+
+## The runtime's zlib decides zip.js throughput
+
+On bulk data zip.js is a thin wrapper around the platform's `CompressionStream` — it
+adds ~7 % over the raw encoder on the 256 MB stream. That means throughput is decided
+by **which zlib the runtime vendors**, and they differ a lot. Same 256 MB compressible
+file, one thread, level-6-class output everywhere:
+
+| Encoder | Time | Output |
+|---|--:|--:|
+| zlib-ng — Deno & Bun `CompressionStream` | **4.8–5.1 s** | 79.4 MB |
+| Chromium zlib — Node `CompressionStream` / `node:zlib` | 8.9 s | 78.3 MB |
+| classic zlib — Apple `gzip -6` | 12.5 s | 78.9 MB |
+| classic zlib compiled to WASM — zip.js `useCompressionStream: false` | ~16 s | 78.9 MB |
+| (reference) 7-Zip `-mx=6` | 33.5 s | 73.6 MB |
+
+Verified in the runtimes' sources: Deno builds `flate2` with vendored
+**zlib-ng** (`__vendored_zlib_ng` default feature), Bun vendors **zlib-ng 2.3.3**
+(SIMD CRC/adler/match kernels, NEON on arm64) behind `node:zlib` and
+`CompressionStream`, and Node vendors **Chromium's zlib fork** (SIMD checksums and
+hash sliding, but a match finder much closer to classic zlib).
+
+Consequences worth knowing:
+
+- **The same zip.js code runs ~1.75× faster on Deno/Bun than on Node** for bulk
+  compression. A "zip.js is fast/slow" measurement is often really a statement about
+  the host's zlib — and the Node tables above are the *pessimistic* end.
+- **The WASM backend is the portability floor, not a peer**: classic zlib plus ~30 %
+  WebAssembly overhead ≈ 3× slower than native on compress. Decompression barely
+  suffers (inflate is cheap — within ~10 % of native). It still lands mid-curve
+  against 7-Zip: 16 s / 78.9 MB sits between `-mx=1` (5.9 s / 86.7 MB) and `-mx=6`
+  (33.5 s / 73.6 MB).
+- Output sizes across the zlib family are interchangeable (78–79 MB): it is one
+  algorithm at four levels of implementation tuning. zip.js inherits whichever the
+  host provides — including future upgrades, for free.
+
 ## When to pick which
 
 - **Choose zip.js** for the fastest compression of large or multiple entries
@@ -195,8 +271,13 @@ npm install            # jszip, fflate, archiver (zip.js is used from the repo)
 npm run corpus         # generate the deterministic datasets under .corpus/
 node bench.js          # the head-to-head tables (compress / decompress / disk streaming)
 node bench-backends.js # the parallelism & codec-backend matrix
+deno run -A bench-7z.js # zip.js vs the 7zz CLI (also: bun bench-7z.js)
 ```
 
+`bench-7z.js` needs the 7-Zip CLI (`brew install sevenzip`) and runs under Deno or Bun;
+set `ZIPJS_BACKEND=wasm` to measure the WebAssembly codec instead of the native
+`CompressionStream`, and `SKIP_HUGE=1` to skip the 256 MB combo.
+
 Both scripts write JSON and a human-readable log to `benchmarks/results/`. Set
 `RUNS=<n>` to change the number of repetitions (default 3). The datasets are generated
 from a seeded PRNG (`benchmarks/lib/corpus.js`), so every run — and every library —

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zip-js/zip-js",
-	"version": "2.8.31",
+	"version": "2.8.32",
 	"exports": {
 		".": "./index.js"
 	},

package/dist/zip-core.js

@@ -2445,7 +2445,7 @@
 			const { value, readable, writable } = message;
 			const transferables = [];
 			if (value) {
-				message.value = value;
+				message.value = value.byteOffset || value.byteLength != value.buffer.byteLength ? new Uint8Array(value) : value;
 				transferables.push(message.value.buffer);
 			}
 			if (transferStreams && transferStreamsSupported) {
@@ -6646,13 +6646,13 @@
 	 */
 
 
-	const DEFAULT_THRESHOLD = 1024 * 1024;
-	const DEFAULT_DIRECTORY_NAME = ".zip.js-temp";
+	const DEFAULT_THRESHOLD$2 = 1024 * 1024;
+	const DEFAULT_DIRECTORY_NAME$1 = ".zip.js-temp";
 
 	function createOPFSTempStream(options = {}) {
 		const {
-			thresholdBytes = DEFAULT_THRESHOLD,
-			directoryName = DEFAULT_DIRECTORY_NAME,
+			thresholdBytes = DEFAULT_THRESHOLD$2,
+			directoryName = DEFAULT_DIRECTORY_NAME$1,
 			getDirectory = () => navigator.storage.getDirectory()
 		} = options;
 		let directoryHandlePromise;
@@ -6781,6 +6781,269 @@
 	 */
 
 
+	const DEFAULT_THRESHOLD$1 = 1024 * 1024;
+
+	function createBlobTempStream(options = {}) {
+		const {
+			thresholdBytes = DEFAULT_THRESHOLD$1
+		} = options;
+		return function () {
+			const memoryChunks = [];
+			let bufferedSize = 0;
+			let spilled = false;
+			let blobWriter, blobPromise, blobReader;
+
+			async function spillToBlob() {
+				const transformStream = new TransformStream();
+				blobPromise = new Response(transformStream.readable).blob();
+				blobWriter = transformStream.writable.getWriter();
+				spilled = true;
+				for (const chunk of memoryChunks) {
+					await blobWriter.write(chunk);
+				}
+				memoryChunks.length = 0;
+			}
+
+			const writable = new WritableStream({
+				async write(chunk) {
+					if (spilled) {
+						await blobWriter.write(chunk);
+					} else {
+						memoryChunks.push(chunk);
+						bufferedSize += chunk.length;
+						if (bufferedSize > thresholdBytes) {
+							await spillToBlob();
+						}
+					}
+				},
+				async close() {
+					if (blobWriter) {
+						await blobWriter.close();
+						blobWriter = null;
+					}
+				}
+			});
+
+			let memoryIndex = 0;
+			const readable = new ReadableStream({
+				async pull(controller) {
+					if (spilled) {
+						if (!blobReader) {
+							const blob = await blobPromise;
+							blobReader = blob.stream().getReader();
+						}
+						const { value, done } = await blobReader.read();
+						if (done) {
+							controller.close();
+						} else {
+							controller.enqueue(value);
+						}
+					} else if (memoryIndex < memoryChunks.length) {
+						controller.enqueue(memoryChunks[memoryIndex++]);
+					} else {
+						controller.close();
+					}
+				},
+				async cancel(reason) {
+					if (blobReader) {
+						await blobReader.cancel(reason);
+					}
+				}
+			}, { highWaterMark: 0 });
+			async function dispose() {
+				if (blobWriter) {
+					try {
+						await blobWriter.abort();
+					} catch {
+						// ignored
+					}
+					blobWriter = null;
+				}
+				if (blobPromise) {
+					blobPromise.catch(() => {
+						// ignored
+					});
+					blobPromise = null;
+				}
+				memoryChunks.length = 0;
+			}
+
+			return { writable, readable, dispose };
+		};
+	}
+
+	/*
+	 Copyright (c) 2025 Gildas Lormeau. All rights reserved.
+
+	 Redistribution and use in source and binary forms, with or without
+	 modification, are permitted provided that the following conditions are met:
+
+	 1. Redistributions of source code must retain the above copyright notice,
+	 this list of conditions and the following disclaimer.
+
+	 2. Redistributions in binary form must reproduce the above copyright
+	 notice, this list of conditions and the following disclaimer in
+	 the documentation and/or other materials provided with the distribution.
+
+	 3. The names of the authors may not be used to endorse or promote products
+	 derived from this software without specific prior written permission.
+
+	 THIS SOFTWARE IS PROVIDED ''AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+	 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+	 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT,
+	 INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
+	 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+	 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+	 OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+	 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+	 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+	 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+	 */
+
+
+	const DEFAULT_THRESHOLD = 1024 * 1024;
+	const DEFAULT_DIRECTORY_NAME = ".zip.js-temp";
+	const READ_CHUNK_SIZE = 512 * 1024;
+	const ERR_UNSUPPORTED_CONTEXT = "createSyncAccessHandle is only available in dedicated workers";
+
+	function createSyncAccessHandleTempStream(options = {}) {
+		const {
+			thresholdBytes = DEFAULT_THRESHOLD,
+			directoryName = DEFAULT_DIRECTORY_NAME,
+			getDirectory
+		} = options;
+		if (!getDirectory &&
+			(typeof FileSystemFileHandle == "undefined" || !FileSystemFileHandle.prototype.createSyncAccessHandle)) {
+			throw new Error(ERR_UNSUPPORTED_CONTEXT);
+		}
+		const getRootDirectory = getDirectory || (() => navigator.storage.getDirectory());
+		let directoryHandlePromise;
+		function getTempDirectory() {
+			if (!directoryHandlePromise) {
+				directoryHandlePromise = Promise.resolve(getRootDirectory())
+					.then(root => root.getDirectoryHandle(directoryName, { create: true }));
+			}
+			return directoryHandlePromise;
+		}
+		return function () {
+			const memoryChunks = [];
+			let bufferedSize = 0;
+			let spilled = false;
+			let fileName, accessHandle;
+			let writeOffset = 0;
+			let readOffset = 0;
+
+			async function spillToFile() {
+				const directoryHandle = await getTempDirectory();
+				fileName = crypto.randomUUID();
+				const fileHandle = await directoryHandle.getFileHandle(fileName, { create: true });
+				accessHandle = await fileHandle.createSyncAccessHandle();
+				spilled = true;
+				for (const chunk of memoryChunks) {
+					accessHandle.write(chunk, { at: writeOffset });
+					writeOffset += chunk.length;
+				}
+				memoryChunks.length = 0;
+			}
+
+			const writable = new WritableStream({
+				async write(chunk) {
+					if (spilled) {
+						accessHandle.write(chunk, { at: writeOffset });
+						writeOffset += chunk.length;
+					} else {
+						memoryChunks.push(chunk);
+						bufferedSize += chunk.length;
+						if (bufferedSize > thresholdBytes) {
+							await spillToFile();
+						}
+					}
+				},
+				close() {
+					if (accessHandle) {
+						accessHandle.flush();
+					}
+				}
+			});
+
+			let memoryIndex = 0;
+			const readable = new ReadableStream({
+				pull(controller) {
+					if (spilled) {
+						const remaining = writeOffset - readOffset;
+						if (remaining <= 0) {
+							controller.close();
+							return;
+						}
+						const buffer = new Uint8Array(Math.min(READ_CHUNK_SIZE, remaining));
+						const read = accessHandle.read(buffer, { at: readOffset });
+						if (read) {
+							readOffset += read;
+							controller.enqueue(buffer.subarray(0, read));
+						} else {
+							controller.close();
+						}
+					} else if (memoryIndex < memoryChunks.length) {
+						controller.enqueue(memoryChunks[memoryIndex++]);
+					} else {
+						controller.close();
+					}
+				}
+			}, { highWaterMark: 0 });
+			async function dispose() {
+				if (accessHandle) {
+					try {
+						accessHandle.close();
+					} catch {
+						// ignored
+					}
+					accessHandle = null;
+				}
+				if (fileName) {
+					try {
+						const directoryHandle = await getTempDirectory();
+						await directoryHandle.removeEntry(fileName);
+					} catch {
+						// ignored
+					}
+					fileName = null;
+				}
+				memoryChunks.length = 0;
+			}
+
+			return { writable, readable, dispose };
+		};
+	}
+
+	/*
+	 Copyright (c) 2025 Gildas Lormeau. All rights reserved.
+
+	 Redistribution and use in source and binary forms, with or without
+	 modification, are permitted provided that the following conditions are met:
+
+	 1. Redistributions of source code must retain the above copyright notice,
+	 this list of conditions and the following disclaimer.
+
+	 2. Redistributions in binary form must reproduce the above copyright
+	 notice, this list of conditions and the following disclaimer in
+	 the documentation and/or other materials provided with the distribution.
+
+	 3. The names of the authors may not be used to endorse or promote products
+	 derived from this software without specific prior written permission.
+
+	 THIS SOFTWARE IS PROVIDED ''AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+	 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+	 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT,
+	 INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
+	 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+	 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+	 OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+	 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+	 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+	 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+	 */
+
+
 	try {
 		configure({ baseURI: (typeof document === 'undefined' && typeof location === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : typeof document === 'undefined' ? location.href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('zip-core.js', document.baseURI).href)) });
 	} catch {
@@ -6837,7 +7100,9 @@
 	exports.ZipWriter = ZipWriter;
 	exports.ZipWriterStream = ZipWriterStream;
 	exports.configure = configure;
+	exports.createBlobTempStream = createBlobTempStream;
 	exports.createOPFSTempStream = createOPFSTempStream;
+	exports.createSyncAccessHandleTempStream = createSyncAccessHandleTempStream;
 	exports.getMimeType = getMimeType;
 	exports.terminateWorkers = terminateWorkers;