7zip-native 0.0.6 → 0.0.8

package/README.md

@@ -23,17 +23,17 @@ The package requires Node.js 18 or newer.
 ```ts
 import {Archive} from '7zip-native';
 
-const archive = await Archive.open('./comics.cbz');
+const archive = await Archive.open('./file.zip');
 
 try
 {
 	const entries = await archive.entries();
-	const cover = await archive.getEntry('chapter/cover.jpg');
+	const file = await archive.getEntry('image.jpg');
 
-	if(cover && !cover.isDirectory)
+	if(file && !file.isDirectory)
 	{
-		const preview = await archive.read(cover.path, {offset: 0, length: 64 * 1024});
-		const image = await archive.extract(cover.path);
+		const preview = await archive.read(file.path, {offset: 0, length: 64 * 1024});
+		const image = await archive.extract(file.path);
 		console.log(entries.length, preview.length, image.length);
 	}
 }
@@ -63,7 +63,9 @@ Opens an archive from a filesystem path and indexes its metadata asynchronously.
 const archive = await Archive.open('./archive.7z', {password: 'secret'});
 ```
 
-`options.password` is passed to the upstream handler when it requests a password. It is held for the lifetime of the archive handle, is not logged, and is limited to 1 MiB of UTF-8 data.
+`Archive.open()` accepts these options:
+
+- `password`: Passed to the upstream handler if it requests a password. It is held for the lifetime of the archive handle, is not logged, and is limited to 1 MiB of UTF-8 data.
 
 ### Listing and looking up entries
 
@@ -109,7 +111,12 @@ const header = await archive.read(entry.path, {
 });
 ```
 
-Offsets and lengths accept safe integers or `bigint`. A range read returns only the requested bytes and is limited to 64 MiB. It uses the handler's normal extraction path, however, so a sequential or solid format may still need to decompress preceding data or the whole entry. It is not guaranteed to be constant-time random access.
+`read()` accepts these options:
+
+- `offset`: Byte position at which to start reading. Defaults to `0`; accepts a non-negative safe integer or `bigint`.
+- `length`: Number of bytes to return. Required; accepts a non-negative safe integer or `bigint`. A range read is limited to 64 MiB.
+
+A range read returns only the requested bytes. It uses the handler's normal extraction path, however, so a sequential or solid format may still need to decompress preceding data or the whole entry. It is not guaranteed to be constant-time random access.
 
 ### Streams and output destinations
 
@@ -125,7 +132,13 @@ for await (const chunk of archive.createReadStream(entry.path, {
 }
 ```
 
-The native engine emits bounded 64 KiB chunks and waits for stream demand, preserving backpressure. Destroying the stream or aborting its signal cancels extraction at the next output boundary. Streams default to a 4 GiB output limit; set `maxBytes` to another non-negative `number` or `bigint`, or to `null` to disable the limit.
+`createReadStream()` accepts these options:
+
+- `highWaterMark`: Readable buffer threshold in bytes. Must be an integer from 1 byte to 16 MiB; defaults to Node.js's Readable default.
+- `maxBytes`: Maximum number of output bytes. Defaults to 4 GiB; accepts a non-negative `number` or `bigint`, or `null` to disable the limit.
+- `signal`: Optional `AbortSignal` that cancels extraction.
+
+The native engine emits bounded 64 KiB chunks and waits for stream demand, preserving backpressure. Destroying the stream or aborting its signal cancels extraction at the next output boundary.
 
 To pipe directly to a Node.js `Writable`:
 
@@ -137,23 +150,63 @@ 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.
+`extractToStream()` accepts the same `highWaterMark`, `maxBytes`, and `signal` options as `createReadStream()`. It 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('./archive.zip', [
+	{sourcePath: './image.jpg', path: 'image.jpg'},
+	{sourcePath: './file.txt', path: 'file.txt'},
+], {
+	compressionLevel: 5,
+	overwrite: false,
+});
+```
+
+`Archive.create()` accepts regular source files and their desired archive-internal paths:
+
+- `sourcePath`: Filesystem path of the regular file to add.
+- `path`: Desired path inside the archive, using `/` separators.
+
+It also accepts these options:
+
+- `format`: Archive format. If omitted, inferred as ZIP from `.zip`, 7z from `.7z`, TAR from `.tar`, or WIM from `.wim`. Set to `'zip'`, `'7z'`, `'tar'`, or `'wim'` to use another output extension.
+- `compressionLevel`: 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.
+- `overwrite`: Defaults to `false`. When `true`, an existing output file is replaced after the new archive has been written.
+
+Duplicate, unsafe, or conflicting internal paths are rejected. The output is first written to a temporary file beside the destination, then installed atomically, so an existing file is preserved if archive creation fails. 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.
+`extractToFolder()` accepts these options:
+
+- `ids`: Entry IDs to extract. Omit both `ids` and `paths` to extract every entry.
+- `paths`: Exact, original archive paths to extract, using `/` separators. This cannot be combined with `ids`.
+- `concurrency`: Maximum number of files this call extracts simultaneously. Must be an integer from 1 to 128; defaults to 1 and is capped at the process-wide native worker-pool concurrency. This does not change `Archive.concurrency()`.
+- `overwrite`: Defaults to `false`, so existing files are not overwritten. When `true`, each existing regular file is replaced only after its entry has been fully extracted to a temporary file alongside the destination. A failure does not truncate the existing file, but replacement may temporarily require extra disk space up to the size of the entry.
+- `onProgress`: Called before extraction, as chunks are processed, and after each file completes. Receives `filesExtracted`, `totalFiles`, aggregated `bytesProcessed`, `totalBytes`, and the calculated `percent`.
+- `onExtract`: Called once for each regular file after it is fully written and, when overwriting, after the final replacement. Receives `{entry, outputPath}`; `entry` retains the original archive metadata and `outputPath` is the final destination path.
+- `maxBytes`: Maximum total uncompressed output size. Defaults to 4 GiB; set to `null` to disable the limit.
+- `signal`: Optional `AbortSignal`. Cancellation stops new files from starting, cancels or waits for active extractions, cleans temporary replacement files, and rejects the call.
+
+On Windows only, invalid filename characters (`< > : | ? * "`) and trailing dots/spaces in each destination component are replaced with `_`; selectors and entry metadata remain unchanged. Unsafe archive paths, path collisions, symlinked destination components, and symlink or non-file targets are 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
 
@@ -163,7 +216,11 @@ Archive.concurrency(8);
 Archive.concurrency(0); // reset to the default
 ```
 
-The setting controls the process-wide native worker pool used by extraction, streams, and range reads. The default is the lesser of 4 and the parallelism available to Node.js; the allowed range is 1–128 workers, with `0` restoring the default.
+`Archive.concurrency(value?)` controls the process-wide native worker pool used by extraction, streams, and range reads:
+
+- `value`: Omit to read the current setting. Set to an integer from 1 to 128 to configure the worker count, or `0` to restore the default.
+
+The default is the lesser of 4 and the parallelism available to Node.js.
 
 Concurrent operations on one archive use independent decoder contexts rather than calling one 7-Zip archive object simultaneously. This is safe for handlers that support independent contexts, but it does not guarantee a speedup. Solid archives may decompress shared data more than once; batching related entries may be faster.
 
@@ -189,6 +246,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 +257,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.
@@ -236,7 +295,7 @@ When packaging with ASAR, ensure both `7zip_native.node` and the matching engine
 }
 ```
 
-Test the packaged application on each target; ASAR unpacking does not replace checking that the addon and engine can both be loaded from the packaged runtime.
+If an application bundler relocates this package's JavaScript (for example, into a `www` directory), keep `7zip-native` resolvable as an installed dependency so the loader can locate the package's prebuilt binaries. Test the packaged application on each target; ASAR unpacking does not replace checking that the addon and engine can both be loaded from the packaged runtime.
 
 ## Build from source
 
@@ -295,6 +354,18 @@ 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" \
+	--concurrencies 1,2,3,4,5,8,16 \
+	--iterations 1
+```
+
+By default, the benchmark tests all concurrencies from 1 to 16. Use `--concurrencies` to select a comma-separated subset, or `--concurrency` for one value; concurrency 1 is always included as the speedup baseline. 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,192 @@
+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>] [--concurrency <workers> | --concurrencies <workers,...>]';
+const archivePaths: string[] = [];
+let iterations = 1;
+let concurrencyOption: string | undefined;
+let concurrenciesOption: string | undefined;
+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;
+	}
+	if(argument === '--concurrency' || argument.startsWith('--concurrency='))
+	{
+		if(concurrencyOption !== undefined)
+		{
+			throw new TypeError('Option --concurrency may only be specified once');
+		}
+		const equalsIndex = argument.indexOf('=');
+		concurrencyOption = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+		if(!concurrencyOption || concurrencyOption.startsWith('--'))
+		{
+			throw new TypeError(`Missing value for --concurrency\nUsage: ${usage}`);
+		}
+		continue;
+	}
+	if(argument === '--concurrencies' || argument.startsWith('--concurrencies='))
+	{
+		if(concurrenciesOption !== undefined)
+		{
+			throw new TypeError('Option --concurrencies may only be specified once');
+		}
+		const equalsIndex = argument.indexOf('=');
+		concurrenciesOption = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+		if(!concurrenciesOption || concurrenciesOption.startsWith('--'))
+		{
+			throw new TypeError(`Missing value for --concurrencies\nUsage: ${usage}`);
+		}
+		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');
+}
+if(concurrencyOption !== undefined && concurrenciesOption !== undefined)
+{
+	throw new TypeError('Use either --concurrency or --concurrencies, not both');
+}
+
+function parseConcurrency(value: string): number
+{
+	const concurrency = Number(value);
+	if(!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 16)
+	{
+		throw new RangeError('Concurrency values must be integers between 1 and 16');
+	}
+	return concurrency;
+}
+
+const selectedConcurrencies = concurrencyOption === undefined
+	? concurrenciesOption === undefined
+		? Array.from({length: 16}, (_, index) => index + 1)
+		: concurrenciesOption.split(',').map(value => parseConcurrency(value.trim()))
+	: [parseConcurrency(concurrencyOption)];
+const concurrencies = [...new Set([1, ...selectedConcurrencies])];
+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);
+}