@zip.js/zip.js 2.8.31 → 2.8.32

package/index.cjs

@@ -2445,7 +2445,7 @@ function sendMessage(message, { worker, writer, transferStreams }) {
 		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 @@ function getMimeType$1() {
  */
 
 
-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 @@ function createOPFSTempStream(options = {}) {
  */
 
 
+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' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) });
 } catch {
@@ -9871,7 +10134,9 @@ exports.ZipReaderStream = ZipReaderStream;
 exports.ZipWriter = ZipWriter;
 exports.ZipWriterStream = ZipWriterStream;
 exports.configure = configure;
+exports.createBlobTempStream = createBlobTempStream;
 exports.createOPFSTempStream = createOPFSTempStream;
+exports.createSyncAccessHandleTempStream = createSyncAccessHandleTempStream;
 exports.fs = fs;
 exports.getMimeType = getMimeType;
 exports.terminateWorkers = terminateWorkersAndModule;

package/index.d.cts

@@ -381,6 +381,45 @@ export interface OPFSTempStreamOptions {
  */
 export function createOPFSTempStream(options?: OPFSTempStreamOptions): () => Promise<TempStream>;
 
+/**
+ * Options for {@link createBlobTempStream}.
+ */
+export interface BlobTempStreamOptions {
+  /**
+   * Spill a buffered entry to a `Blob` once its buffered data exceeds this size, in bytes. Smaller entries stay in memory.
+   *
+   * @defaultValue 1048576
+   */
+  thresholdBytes?: number;
+}
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries into a `Blob` instead of keeping it in memory.
+ *
+ * An entry stays in memory until it exceeds `thresholdBytes`, then its data is transferred incrementally into a `Blob` built with `new Response(stream).blob()` and streamed back afterwards.
+ * In Chromium-based browsers, `Blob` data is managed outside the page and paged to disk under memory pressure, so peak memory stays bounded on large buffered entries without any storage permission or cleanup obligation.
+ * In Firefox, the `Blob` stays in memory but the helper still reduces peak memory usage moderately (roughly 30% on large entries) by releasing staged chunks earlier.
+ * In Safari, building the `Blob` retains several copies of the staged data (roughly 4 times the entry size at peak); do not use this helper there.
+ * In non-browser runtimes, the helper stays functional but roughly doubles peak memory usage (staged bytes plus their `Blob` copy).
+ * Outside Chromium-based browsers, prefer {@link createOPFSTempStream} or a file-backed implementation.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createBlobTempStream(options?: BlobTempStreamOptions): () => TempStream;
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries to the Origin Private File System (OPFS) via `FileSystemSyncAccessHandle` instead of keeping it in memory.
+ *
+ * This is the fastest disk-backed temporary storage on the web platform: it behaves like {@link createOPFSTempStream} (same options, same bounded-memory profile) but writes roughly 2.5 times faster in Chromium and Firefox and reads back several times faster in Firefox and Safari, making disk-backed staging nearly as fast as the in-memory default.
+ *
+ * `FileSystemSyncAccessHandle` is only exposed in dedicated workers, so this helper requires running the {@link ZipWriter} inside a worker; it throws when created in an unsupported context unless `getDirectory` is provided.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createSyncAccessHandleTempStream(options?: OPFSTempStreamOptions): () => TempStream;
+
 /**
  * Represents an instance used to read or write unknown type of data.
  *
@@ -1823,7 +1862,7 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * The `writable` side receives compressed entry data. The `readable` side is consumed when the entry is replayed into the final zip stream.
    * The optional `dispose` method is called once the entry has been processed (on success, error, or abort) so a resource-backed buffer can release its resource.
    *
-   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation.
+   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation, {@link createSyncAccessHandleTempStream} for a faster worker-only variant, and {@link createBlobTempStream} for a `Blob`-backed one.
    */
   createTempStream?: () => TempStream | Promise<TempStream>;
   /**

package/index.d.ts

@@ -381,6 +381,45 @@ export interface OPFSTempStreamOptions {
  */
 export function createOPFSTempStream(options?: OPFSTempStreamOptions): () => Promise<TempStream>;
 
+/**
+ * Options for {@link createBlobTempStream}.
+ */
+export interface BlobTempStreamOptions {
+  /**
+   * Spill a buffered entry to a `Blob` once its buffered data exceeds this size, in bytes. Smaller entries stay in memory.
+   *
+   * @defaultValue 1048576
+   */
+  thresholdBytes?: number;
+}
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries into a `Blob` instead of keeping it in memory.
+ *
+ * An entry stays in memory until it exceeds `thresholdBytes`, then its data is transferred incrementally into a `Blob` built with `new Response(stream).blob()` and streamed back afterwards.
+ * In Chromium-based browsers, `Blob` data is managed outside the page and paged to disk under memory pressure, so peak memory stays bounded on large buffered entries without any storage permission or cleanup obligation.
+ * In Firefox, the `Blob` stays in memory but the helper still reduces peak memory usage moderately (roughly 30% on large entries) by releasing staged chunks earlier.
+ * In Safari, building the `Blob` retains several copies of the staged data (roughly 4 times the entry size at peak); do not use this helper there.
+ * In non-browser runtimes, the helper stays functional but roughly doubles peak memory usage (staged bytes plus their `Blob` copy).
+ * Outside Chromium-based browsers, prefer {@link createOPFSTempStream} or a file-backed implementation.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createBlobTempStream(options?: BlobTempStreamOptions): () => TempStream;
+
+/**
+ * Builds a {@link ZipWriterConstructorOptions.createTempStream} factory that spills the data of buffered entries to the Origin Private File System (OPFS) via `FileSystemSyncAccessHandle` instead of keeping it in memory.
+ *
+ * This is the fastest disk-backed temporary storage on the web platform: it behaves like {@link createOPFSTempStream} (same options, same bounded-memory profile) but writes roughly 2.5 times faster in Chromium and Firefox and reads back several times faster in Firefox and Safari, making disk-backed staging nearly as fast as the in-memory default.
+ *
+ * `FileSystemSyncAccessHandle` is only exposed in dedicated workers, so this helper requires running the {@link ZipWriter} inside a worker; it throws when created in an unsupported context unless `getDirectory` is provided.
+ *
+ * @param options The options.
+ * @returns A factory suitable for {@link ZipWriterConstructorOptions.createTempStream}.
+ */
+export function createSyncAccessHandleTempStream(options?: OPFSTempStreamOptions): () => TempStream;
+
 /**
  * Represents an instance used to read or write unknown type of data.
  *
@@ -1823,7 +1862,7 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    * The `writable` side receives compressed entry data. The `readable` side is consumed when the entry is replayed into the final zip stream.
    * The optional `dispose` method is called once the entry has been processed (on success, error, or abort) so a resource-backed buffer can release its resource.
    *
-   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation.
+   * See {@link createOPFSTempStream} for a ready-made OPFS-backed implementation, {@link createSyncAccessHandleTempStream} for a faster worker-only variant, and {@link createBlobTempStream} for a `Blob`-backed one.
    */
   createTempStream?: () => TempStream | Promise<TempStream>;
   /**