7zip-native 0.0.6 → 0.0.7

package/README.md

@@ -139,21 +139,39 @@ await archive.extractToStream(entry.path, createWriteStream('./page.jpg'), {
 
 This respects backpressure and ends the destination when extraction succeeds. A destination error, early close, or abort rejects the Promise.
 
+### Creating ZIP, 7z, TAR, and WIM archives
+
+```ts
+await Archive.create('./comic.cbz', [
+	{sourcePath: './pages/cover.jpg', path: 'cover.jpg'},
+	{sourcePath: './pages/01.jpg', path: 'pages/01.jpg'},
+], {
+	compressionLevel: 5,
+	overwrite: false,
+});
+```
+
+`Archive.create()` accepts regular source files and their desired archive-internal paths. It infers ZIP from `.zip` or `.cbz`, 7z from `.7z`, TAR from `.tar`, and WIM from `.wim`; set `format: 'zip'`, `'7z'`, `'tar'`, or `'wim'` to use another output extension. Compression level is an integer from 0 to 9, defaults to 5, and applies only to ZIP and 7z. TAR is uncompressed; WIM uses the upstream handler's default settings. Duplicate, unsafe, or conflicting internal paths are rejected. The output is first written to a temporary file beside the destination, then installed atomically; an existing file is preserved unless `overwrite: true` is specified. Archive creation runs in the bounded native worker pool and does not launch a 7-Zip executable.
+
 ### Extracting to a folder
 
 ```ts
 await archive.extractToFolder('./unpacked', {
 	paths: ['chapter/page1.jpg', 'chapter/page2.jpg'], // alternatively, use ids
+	concurrency: 2,
 	overwrite: true,
 	onProgress: ({filesExtracted, totalFiles, bytesProcessed, totalBytes, percent}) => {
 		console.log(`${filesExtracted}/${totalFiles} files, ${percent}% (${bytesProcessed}/${totalBytes} bytes)`);
 	},
+	onExtract: ({entry, outputPath}) => {
+		console.log(`Extracted ${entry.path} to ${outputPath}`);
+	},
 	maxBytes: 2n * 1024n * 1024n * 1024n,
 	signal: abortController.signal,
 });
 ```
 
-Folder extraction accepts either `ids` or exact `paths`; omit both to extract every entry, and do not provide both together. Paths use archive-internal `/` separators. Extraction is sequential and uses bounded memory. Its default total output limit is 4 GiB; `maxBytes: null` disables that limit. Set `onProgress` to receive the number of regular files selected and fully extracted, the bytes emitted so far, the total uncompressed bytes, and the calculated percentage. It is called before extraction, as data chunks are processed, and after each file completes. By default, existing files are not overwritten; set `overwrite: true` to replace existing regular files. Replacement is committed only after that entry has been fully extracted, using a temporary file alongside the destination so a failure does not truncate the existing file. This can temporarily require extra disk space up to the size of the entry being replaced. Symlink or non-file targets are rejected. Unsafe archive paths, path collisions, and symlinked destination components are also rejected. Archive links are written as regular file data; the API does not create symbolic or hard links. If extraction fails partway through, files already written (or partially written) may remain in the destination.
+Folder extraction accepts either `ids` or exact, original archive `paths`; omit both to extract every entry, and do not provide both together. Paths use archive-internal `/` separators. `concurrency` sets the maximum number of files extracted simultaneously by this call; it must be an integer from 1 to 128, defaults to 1, and is capped at the process-wide native worker-pool concurrency. It does not change `Archive.concurrency()`. Extraction uses bounded memory and a bounded scheduler rather than queueing one promise per entry. Its default total output limit is 4 GiB; `maxBytes: null` disables that limit. Set `onProgress` to receive the number of regular files selected and fully extracted, the bytes emitted so far across active files, the total uncompressed bytes, and the calculated percentage. It is called before extraction, as data chunks are processed, and after each file completes. `onExtract` is called once per regular file after it is fully written; with `overwrite: true`, it runs after the final replacement. Its `entry` retains the original archive metadata and `outputPath` is the final destination path. On Windows only, invalid filename characters (`< > : | ? * "`) and trailing dots/spaces in each output component are replaced with `_`; selectors and entry metadata remain unchanged. By default, existing files are not overwritten; set `overwrite: true` to replace existing regular files. Replacement is committed only after that entry has been fully extracted, using a temporary file alongside the destination so a failure does not truncate the existing file. This can temporarily require extra disk space up to the size of the entry being replaced. Symlink or non-file targets are rejected. Unsafe archive paths, path collisions, and symlinked destination components are also rejected. Archive links are written as regular file data; the API does not create symbolic or hard links. If extraction fails partway through, files already written (or partially written) may remain in the destination.
 
 ### Concurrency
 
@@ -189,6 +207,7 @@ Invalid argument types and values throw standard `TypeError` or `RangeError`. Ar
 | `ERR_ARCHIVE_PASSWORD` | Password is missing or incorrect when requested by the handler |
 | `ERR_ARCHIVE_PATH` | Unsafe or colliding path during folder extraction |
 | `ERR_ARCHIVE_EXTRACT` | Entry extraction failed |
+| `ERR_ARCHIVE_CREATE` | Archive creation failed or the output already exists |
 
 Buffered `extract()` and `read()` do not currently support cancellation. Streams and folder extraction accept an `AbortSignal`.
 
@@ -199,6 +218,7 @@ The package uses the handlers registered in the pinned upstream `Format7zF` bund
 ### Format-specific notes
 
 - **RAR:** extraction uses upstream code subject to its LGPL terms and the unRAR restriction. This package does not create RAR archives or implement the proprietary RAR compression algorithm. Review the upstream notices before redistribution.
+- **Creation:** ZIP, 7z, TAR, and WIM archives can be created from filesystem files. Streams and directory trees are not accepted as sources.
 - **ACE:** not supported by this 7-Zip revision.
 - **Encryption:** password callbacks are connected to archive opening and extraction. AES-256 encrypted ZIP extraction and range reads are tested on Linux x64; encrypted-header behavior and password variants in other formats are not yet verified.
 - **Partial reads:** memory use is limited to the requested range, but the decoder may still process more data internally, especially for solid or sequential formats.
@@ -295,6 +315,17 @@ npm run benchmark:concurrency -- \
 
 The report includes median and p95 latency, throughput, speedup, and the number of entries that can overlap. `--max-files` selects evenly spaced entries, which is useful when sampling solid archives. Benchmarks report measurements only; results depend on the archive, machine, and workload and do not guarantee a speedup.
 
+Compare `extractToFolder()` concurrency (1 through 16) across one or more archives:
+
+```sh
+npm run benchmark:folder-concurrency -- \
+	--archive "./samples/sample.zip" \
+	--archive "./archive.7z" \
+	--iterations 1
+```
+
+Each run extracts one archive into a temporary directory, verifies the completed file and byte counts, and removes the output before continuing. The default is one iteration per concurrency; increase `--iterations` for more stable measurements. The global worker pool is set to 16 for the benchmark and restored afterward.
+
 ## License
 
 This package is MIT-licensed. The integrated 7-Zip code and other bundled dependencies have their own licensing terms; see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) before redistribution.

package/bench/folder-concurrency.mts

@@ -0,0 +1,143 @@
+import {mkdtemp, rm, stat} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
+import {Archive, type ExtractToFolderProgress} from '../dist/index.mjs';
+
+const usage = 'npm run benchmark:folder-concurrency -- --archive <path> [--archive <path> ...] [--iterations <count>]';
+const archivePaths: string[] = [];
+let iterations = 1;
+const args = process.argv.slice(2);
+for(let index = 0; index < args.length; index++)
+{
+	const argument = args[index]!;
+	if(argument === '--archive' || argument.startsWith('--archive='))
+	{
+		const equalsIndex = argument.indexOf('=');
+		const path = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+		if(!path || path.startsWith('--'))
+		{
+			throw new TypeError(`Missing value for --archive\nUsage: ${usage}`);
+		}
+		archivePaths.push(resolve(path));
+		continue;
+	}
+	if(argument === '--iterations' || argument.startsWith('--iterations='))
+	{
+		const equalsIndex = argument.indexOf('=');
+		const value = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+		if(!value || value.startsWith('--'))
+		{
+			throw new TypeError(`Missing value for --iterations\nUsage: ${usage}`);
+		}
+		iterations = Number(value);
+		continue;
+	}
+	throw new TypeError(`Unknown argument ${argument}\nUsage: ${usage}`);
+}
+
+if(archivePaths.length === 0)
+{
+	throw new TypeError(`Specify at least one --archive\nUsage: ${usage}`);
+}
+if(!Number.isSafeInteger(iterations) || iterations < 1)
+{
+	throw new RangeError('--iterations must be a positive integer');
+}
+
+const concurrencies = Array.from({length: 16}, (_, index) => index + 1);
+const originalConcurrency = Archive.concurrency();
+const archiveResults = [];
+try
+{
+	Archive.concurrency(16);
+	for(const archivePath of archivePaths)
+	{
+		const archive = await Archive.open(archivePath);
+		try
+		{
+			const archiveSize = (await stat(archivePath)).size;
+			const files = (await archive.entries()).filter(entry => !entry.isDirectory);
+			if(files.length === 0)
+			{
+				throw new Error(`Archive contains no regular files: ${archivePath}`);
+			}
+			const expectedBytes = files.reduce((total, file) => total + file.size, 0n);
+			const measurements = [];
+			let serialMedian = 0;
+			for(const concurrency of concurrencies)
+			{
+				const durations: number[] = [];
+				for(let iteration = 0; iteration < iterations; iteration++)
+				{
+					const temporaryDirectory = await mkdtemp(join(tmpdir(), '7zip-native-folder-bench-'));
+					let finalProgress: ExtractToFolderProgress | undefined;
+					let completedFiles = 0;
+					try
+					{
+						const start = process.hrtime.bigint();
+						await archive.extractToFolder(join(temporaryDirectory, 'output'), {
+							concurrency,
+							onProgress: progress => {
+								finalProgress = progress;
+							},
+							onExtract: () => {
+								completedFiles++;
+							},
+						});
+						durations.push(Number(process.hrtime.bigint() - start) / 1e6);
+						if(!finalProgress
+							|| finalProgress.filesExtracted !== files.length
+							|| finalProgress.totalFiles !== files.length
+							|| finalProgress.bytesProcessed !== expectedBytes
+							|| finalProgress.totalBytes !== expectedBytes
+							|| completedFiles !== files.length)
+						{
+							throw new Error(`Extraction verification failed for ${archivePath} at concurrency ${concurrency}`);
+						}
+					}
+					finally
+					{
+						await rm(temporaryDirectory, {recursive: true, force: true});
+					}
+				}
+				const sorted = [...durations].sort((a, b) => a - b);
+				const median = sorted[Math.floor(sorted.length / 2)]!;
+				const p95 = sorted[Math.ceil(sorted.length * 0.95) - 1]!;
+				if(concurrency === 1)
+				{
+					serialMedian = median;
+				}
+				measurements.push({
+					concurrency,
+					iterations,
+					median_ms: median,
+					p95_ms: p95,
+					throughput_mib_per_second: Number(expectedBytes) / (median / 1000) / 1024 / 1024,
+					speedup_vs_1: serialMedian / median,
+					runs_ms: durations,
+				});
+			}
+			archiveResults.push({
+				archive: archivePath,
+				archive_bytes: archiveSize,
+				files: files.length,
+				uncompressed_bytes: expectedBytes.toString(),
+				measurements,
+			});
+		}
+		finally
+		{
+			await archive.close();
+		}
+	}
+	console.log(JSON.stringify({
+		global_pool_concurrency: 16,
+		concurrencies,
+		iterations,
+		archives: archiveResults,
+	}, null, 2));
+}
+finally
+{
+	Archive.concurrency(originalConcurrency);
+}

package/dist/index.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
 var node_fs = require('node:fs');
-var promises$1 = require('node:fs/promises');
+var promises = require('node:fs/promises');
 var node_crypto = require('node:crypto');
 var node_module = require('node:module');
 var node_os = require('node:os');
 var node_path = require('node:path');
 var node_stream = require('node:stream');
-var promises = require('node:stream/promises');
+var promises$1 = require('node:stream/promises');
 var node_url = require('node:url');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -76,10 +76,32 @@ function safeEntrySegments(entryPath) {
     }
     return segments;
 }
+function sanitizeOutputPath(entryPath) {
+    if (process.platform !== 'win32') {
+        return entryPath;
+    }
+    return entryPath
+        .replace(/([. ]+)([\\/]|$)/g, (_match, unsupported, separator) => '_'.repeat(unsupported.length) + separator)
+        .replace(/[<>:|?*"]/g, '_');
+}
+function assertSafeRelativeArchivePath(entryPath) {
+    const normalized = entryPath.replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(segment => segment !== '' && segment !== '.');
+    if (entryPath.includes('\0')
+        || normalized.startsWith('/')
+        || /^[a-zA-Z]:/.test(normalized)
+        || segments.length === 0
+        || segments.some(segment => segment === '..')) {
+        throw new ArchiveError('ERR_ARCHIVE_PATH', `Unsafe archive entry path: ${entryPath}`);
+    }
+}
 function makeOutputPlans(root, entries) {
     const caseInsensitivePaths = process.platform === 'win32' || process.platform === 'darwin';
     const plans = entries.map((entry) => {
-        const segments = safeEntrySegments(entry.path);
+        if (process.platform === 'win32') {
+            assertSafeRelativeArchivePath(entry.path);
+        }
+        const segments = safeEntrySegments(sanitizeOutputPath(entry.path));
         const targetPath = node_path.resolve(root, ...segments);
         const relative = node_path.relative(root, targetPath);
         if (relative === ''
@@ -113,21 +135,21 @@ function makeOutputPlans(root, entries) {
 }
 async function ensureDirectory(directoryPath) {
     try {
-        await promises$1.mkdir(directoryPath, { mode: 0o700 });
+        await promises.mkdir(directoryPath, { mode: 0o700 });
     }
     catch (error) {
         if (error.code !== 'EEXIST') {
             throw error;
         }
     }
-    const details = await promises$1.lstat(directoryPath);
+    const details = await promises.lstat(directoryPath);
     if (details.isSymbolicLink() || !details.isDirectory()) {
         throw new ArchiveError('ERR_ARCHIVE_PATH', `Destination path is not a real directory: ${directoryPath}`);
     }
 }
 async function assertReplaceableOutput(filePath) {
     try {
-        const details = await promises$1.lstat(filePath);
+        const details = await promises.lstat(filePath);
         if (!details.isFile()) {
             throw new ArchiveError('ERR_ARCHIVE_PATH', `Cannot replace a non-file extraction target: ${filePath}`);
         }
@@ -138,9 +160,40 @@ async function assertReplaceableOutput(filePath) {
         }
     }
 }
+async function assertOutputDoesNotExist(filePath) {
+    try {
+        await promises.lstat(filePath);
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Output archive already exists: ${filePath}`);
+    }
+    catch (error) {
+        if (error instanceof ArchiveError || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function normalizeCreateEntry(entry) {
+    if (entry === null || typeof entry !== 'object'
+        || typeof entry.sourcePath !== 'string' || entry.sourcePath.length === 0
+        || typeof entry.path !== 'string' || entry.path.length === 0) {
+        throw new TypeError('Each archive creation entry must have non-empty sourcePath and path strings');
+    }
+    const internalPath = safeEntrySegments(entry.path).join('/');
+    const sourcePath = node_path.resolve(entry.sourcePath);
+    let details;
+    try {
+        details = await promises.lstat(sourcePath);
+    }
+    catch (cause) {
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Unable to access archive creation source: ${sourcePath}`, { cause });
+    }
+    if (details.isSymbolicLink() || !details.isFile()) {
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Archive creation source is not a regular file: ${sourcePath}`);
+    }
+    return { sourcePath, path: internalPath };
+}
 async function ensureExtractionRoot(root) {
     try {
-        const details = await promises$1.lstat(root);
+        const details = await promises.lstat(root);
         if (details.isSymbolicLink() || !details.isDirectory()) {
             throw new ArchiveError('ERR_ARCHIVE_PATH', `Destination is not a real directory: ${root}`);
         }
@@ -151,8 +204,8 @@ async function ensureExtractionRoot(root) {
             throw error;
         }
     }
-    await promises$1.mkdir(root, { recursive: true, mode: 0o700 });
-    const details = await promises$1.lstat(root);
+    await promises.mkdir(root, { recursive: true, mode: 0o700 });
+    const details = await promises.lstat(root);
     if (details.isSymbolicLink() || !details.isDirectory()) {
         throw new ArchiveError('ERR_ARCHIVE_PATH', `Destination is not a real directory: ${root}`);
     }
@@ -299,6 +352,99 @@ class Archive {
             throw new ArchiveError(/password/i.test(message) ? 'ERR_ARCHIVE_PASSWORD' : 'ERR_ARCHIVE_OPEN', message, { cause });
         }
     }
+    static async create(outputPath, entries, options = {}) {
+        if (typeof outputPath !== 'string' || outputPath.length === 0) {
+            throw new TypeError('Output archive path must be a non-empty string');
+        }
+        if (!Array.isArray(entries)) {
+            throw new TypeError('Archive creation entries must be an array');
+        }
+        if (entries.length > 1_000_000) {
+            throw new RangeError('Archive creation exceeds the 1,000,000-entry limit');
+        }
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('Archive creation options must be an object');
+        }
+        if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
+            throw new TypeError('Archive creation overwrite option must be a boolean');
+        }
+        const compressionLevel = options.compressionLevel ?? 5;
+        if (!Number.isSafeInteger(compressionLevel) || compressionLevel < 0 || compressionLevel > 9) {
+            throw new RangeError('Compression level must be an integer between 0 and 9');
+        }
+        const targetPath = node_path.resolve(outputPath);
+        let format;
+        if (options.format !== undefined) {
+            if (options.format !== '7z' && options.format !== 'zip'
+                && options.format !== 'tar' && options.format !== 'wim') {
+                throw new TypeError('Archive format must be "7z", "zip", "tar", or "wim"');
+            }
+            format = options.format;
+        }
+        else {
+            const extension = node_path.extname(targetPath).toLowerCase();
+            if (extension === '.7z') {
+                format = '7z';
+            }
+            else if (extension === '.zip' || extension === '.cbz') {
+                format = 'zip';
+            }
+            else if (extension === '.tar') {
+                format = 'tar';
+            }
+            else if (extension === '.wim') {
+                format = 'wim';
+            }
+            else {
+                throw new TypeError('Specify format as "7z", "zip", "tar", or "wim" for an unrecognized output extension');
+            }
+        }
+        if (options.compressionLevel !== undefined && format !== '7z' && format !== 'zip') {
+            throw new TypeError('compressionLevel is only supported for ZIP and 7z archives');
+        }
+        const normalizedEntries = await Promise.all(entries.map(normalizeCreateEntry));
+        const caseInsensitivePaths = process.platform === 'win32' || process.platform === 'darwin';
+        const pathKeys = normalizedEntries.map(entry => caseInsensitivePaths ? entry.path.toLowerCase() : entry.path);
+        const archivePaths = new Set(pathKeys);
+        if (archivePaths.size !== normalizedEntries.length) {
+            throw new ArchiveError('ERR_ARCHIVE_PATH', 'Archive creation paths must be unique');
+        }
+        for (const entry of normalizedEntries) {
+            const segments = entry.path.split('/');
+            for (let index = 1; index < segments.length; index++) {
+                const parent = segments.slice(0, index).join('/');
+                const parentKey = caseInsensitivePaths ? parent.toLowerCase() : parent;
+                if (archivePaths.has(parentKey)) {
+                    throw new ArchiveError('ERR_ARCHIVE_PATH', `Archive creation file path is a parent of another entry: ${parent}`);
+                }
+            }
+        }
+        if (options.overwrite) {
+            await assertReplaceableOutput(targetPath);
+        }
+        else {
+            await assertOutputDoesNotExist(targetPath);
+        }
+        const temporaryPath = node_path.join(node_path.dirname(targetPath), `.7zip-native-${node_crypto.randomUUID()}.tmp`);
+        try {
+            await native.create(temporaryPath, format, normalizedEntries, compressionLevel, enginePath);
+            if (options.overwrite) {
+                await assertReplaceableOutput(targetPath);
+                await promises.rename(temporaryPath, targetPath);
+            }
+            else {
+                await promises.link(temporaryPath, targetPath);
+                await promises.rm(temporaryPath);
+            }
+        }
+        catch (cause) {
+            await promises.rm(temporaryPath, { force: true });
+            if (cause instanceof ArchiveError) {
+                throw cause;
+            }
+            throw new ArchiveError('ERR_ARCHIVE_CREATE', errorMessage(cause), { cause });
+        }
+    }
     async entries() {
         this.assertOpen();
         this.entriesPromise ??= native.entries(this.handle).catch((cause) => {
@@ -369,7 +515,7 @@ class Archive {
         if (!destination || typeof destination.write !== 'function') {
             throw new TypeError('Destination must be a writable stream');
         }
-        await promises.pipeline(this.createReadStream(idOrPath, options), destination, { signal: options.signal });
+        await promises$1.pipeline(this.createReadStream(idOrPath, options), destination, { signal: options.signal });
     }
     async extractToFolder(destination, options = {}) {
         this.assertOpen();
@@ -382,9 +528,19 @@ class Archive {
         if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
             throw new TypeError('Folder extraction overwrite option must be a boolean');
         }
+        if (options.concurrency !== undefined
+            && (!Number.isSafeInteger(options.concurrency)
+                || options.concurrency < 1
+                || options.concurrency > 128)) {
+            throw new RangeError('Folder extraction concurrency must be an integer between 1 and 128');
+        }
         if (options.onProgress !== undefined && typeof options.onProgress !== 'function') {
             throw new TypeError('Folder extraction onProgress option must be a function');
         }
+        if (options.onExtract !== undefined && typeof options.onExtract !== 'function') {
+            throw new TypeError('Folder extraction onExtract option must be a function');
+        }
+        const concurrency = Math.min(options.concurrency ?? 1, Archive.concurrency());
         options.signal?.throwIfAborted();
         const maxBytes = normalizeMaxBytes(options.maxBytes, 'maxBytes');
         const entries = await this.entries();
@@ -454,8 +610,28 @@ class Archive {
             options.signal?.throwIfAborted();
             if (plan.isDirectory) {
                 await ensureOutputDirectoryTree(root, plan.targetPath);
-                continue;
             }
+        }
+        const filePlans = plans.filter(plan => !plan.isDirectory);
+        const controller = new AbortController();
+        const extractionSignal = controller.signal;
+        let hasFailure = false;
+        let failure;
+        let nextFileIndex = 0;
+        const stop = (error) => {
+            if (!hasFailure) {
+                hasFailure = true;
+                failure = error;
+            }
+            if (!extractionSignal.aborted) {
+                controller.abort(error);
+            }
+        };
+        const abortFromCaller = () => {
+            stop(options.signal?.reason);
+        };
+        options.signal?.addEventListener('abort', abortFromCaller, { once: true });
+        const extractFile = async (plan) => {
             await ensureOutputParents(root, plan.targetPath);
             const limit = new node_stream.Transform({
                 transform(chunk, _encoding, callback) {
@@ -479,26 +655,59 @@ class Archive {
                 await assertReplaceableOutput(plan.targetPath);
                 const temporaryPath = node_path.join(node_path.dirname(plan.targetPath), `.7zip-native-${node_crypto.randomUUID()}.tmp`);
                 try {
-                    await promises.pipeline(this.createReadStream(plan.entry.id, {
-                        signal: options.signal,
+                    await promises$1.pipeline(this.createReadStream(plan.entry.id, {
+                        signal: extractionSignal,
                         maxBytes: null,
-                    }), limit, node_fs.createWriteStream(temporaryPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+                    }), limit, node_fs.createWriteStream(temporaryPath, { flags: 'wx', mode: 0o600 }), { signal: extractionSignal });
+                    extractionSignal.throwIfAborted();
                     await assertReplaceableOutput(plan.targetPath);
-                    await promises$1.rename(temporaryPath, plan.targetPath);
+                    extractionSignal.throwIfAborted();
+                    await promises.rename(temporaryPath, plan.targetPath);
                 }
                 catch (error) {
-                    await promises$1.rm(temporaryPath, { force: true });
+                    await promises.rm(temporaryPath, { force: true });
                     throw error;
                 }
             }
             else {
-                await promises.pipeline(this.createReadStream(plan.entry.id, {
-                    signal: options.signal,
+                await promises$1.pipeline(this.createReadStream(plan.entry.id, {
+                    signal: extractionSignal,
                     maxBytes: null,
-                }), limit, node_fs.createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+                }), limit, node_fs.createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 }), { signal: extractionSignal });
             }
             filesExtracted++;
             reportProgress();
+            options.onExtract?.({ entry: plan.entry, outputPath: plan.targetPath });
+        };
+        const runWorker = async () => {
+            while (!hasFailure) {
+                if (options.signal?.aborted) {
+                    stop(options.signal.reason);
+                    return;
+                }
+                const plan = filePlans[nextFileIndex++];
+                if (!plan) {
+                    return;
+                }
+                try {
+                    await extractFile(plan);
+                }
+                catch (error) {
+                    stop(error);
+                    return;
+                }
+            }
+        };
+        try {
+            options.signal?.throwIfAborted();
+            const workers = Array.from({ length: Math.min(concurrency, filePlans.length) }, () => runWorker());
+            await Promise.all(workers);
+            if (hasFailure) {
+                throw failure;
+            }
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abortFromCaller);
         }
     }
     async read(idOrPath, options) {

package/dist/index.d.cts

@@ -19,6 +19,16 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+type ArchiveFormat = '7z' | 'zip' | 'tar' | 'wim';
+interface ArchiveCreateEntry {
+    readonly sourcePath: string;
+    readonly path: string;
+}
+interface CreateArchiveOptions {
+    readonly format?: ArchiveFormat;
+    readonly compressionLevel?: number;
+    readonly overwrite?: boolean;
+}
 interface ExtractToFolderProgress {
     readonly filesExtracted: number;
     readonly totalFiles: number;
@@ -26,6 +36,10 @@ interface ExtractToFolderProgress {
     readonly totalBytes: bigint;
     readonly percent: number;
 }
+interface ExtractedArchiveFile {
+    readonly entry: ArchiveEntry;
+    readonly outputPath: string;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -34,12 +48,14 @@ interface ReadStreamOptions {
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
     readonly paths?: readonly string[];
+    readonly concurrency?: number;
     readonly overwrite?: boolean;
     readonly onProgress?: (progress: ExtractToFolderProgress) => void;
+    readonly onExtract?: (result: ExtractedArchiveFile) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
-type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT';
+type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT' | 'ERR_ARCHIVE_CREATE';
 declare class ArchiveError extends Error {
     readonly code: ArchiveErrorCode;
     constructor(code: ArchiveErrorCode, message: string, options?: ErrorOptions);
@@ -52,6 +68,7 @@ declare class Archive {
     private constructor();
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
+    static create(outputPath: string, entries: readonly ArchiveCreateEntry[], options?: CreateArchiveOptions): Promise<void>;
     entries(): Promise<readonly ArchiveEntry[]>;
     getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
     extract(idOrPath: EntrySelector): Promise<Buffer>;
@@ -69,4 +86,4 @@ declare class Archive {
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveCreateEntry, ArchiveEntry, ArchiveErrorCode, ArchiveFormat, CreateArchiveOptions, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, ExtractedArchiveFile, OpenOptions, ReadOptions, ReadStreamOptions };