7zip-native 0.0.8 → 0.0.12

package/README.md

@@ -66,6 +66,11 @@ const archive = await Archive.open('./archive.7z', {password: 'secret'});
 `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.
+- `deflateBufferSize`: Input buffer size in bytes for Deflate extraction. Defaults to `32768`; accepts integers from `4096` through `2097152`. It is stored per archive and applied to each extraction, so different open archives can use different values.
+
+```ts
+const archive = await Archive.open('./archive.zip', {deflateBufferSize: 32768});
+```
 
 ### Listing and looking up entries
 
@@ -109,14 +114,24 @@ const header = await archive.read(entry.path, {
 	offset: 0,
 	length: 64 * 1024,
 });
+const headers = await archive.read([first.path, second.id], {
+	offset: 0,
+	length: 64 * 1024,
+});
+const prefixes = await archive.read([
+	{entry: first.path, offset: 0, length: 8192},
+	{entry: second.id, offset: 0, length: 64},
+]);
 ```
 
+`read()` accepts one entry selector or a batch. For a selector array, the same range is used for every entry; use `ReadRequest[]` to specify a different range per entry. Both batch forms return buffers in request order and run as one native extraction operation. The selector-array form preserves repeated selectors; `ReadRequest[]` must contain unique entries.
+
 `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.
+A range read returns only the requested bytes. A batch is limited to 64 MiB per entry and 256 MiB total output. 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
 
@@ -169,13 +184,15 @@ await Archive.create('./archive.zip', [
 - `sourcePath`: Filesystem path of the regular file to add.
 - `path`: Desired path inside the archive, using `/` separators.
 
+The source file's modification time is stored in the archive.
+
 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.
+Duplicate, absolute, or traversal paths are rejected, but platform-supported filename characters such as trailing spaces are preserved in the archive-internal path. 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
 
@@ -184,11 +201,8 @@ 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}`);
+	onExtract: ({entry, outputPath, percent}) => {
+		console.log(`Extracted ${entry.path} to ${outputPath} (${percent}%)`);
 	},
 	maxBytes: 2n * 1024n * 1024n * 1024n,
 	signal: abortController.signal,
@@ -199,14 +213,15 @@ await archive.extractToFolder('./unpacked', {
 
 - `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.
+- `concurrency`: Maximum number of native extraction batches this call runs 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`, an existing regular file is removed before the new file is written directly to its final path. A failed extraction can leave the destination missing.
+- `onExtract`: Called after each regular file has been completely written and closed; it does not wait for the rest of the batch. Concurrent extraction can make event order differ from selection order. Receives `{entry, outputPath, percent}`, where `percent` is the completed-file count divided by the total selected regular files. `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.
+Each native extraction call receives a batch of entry IDs and output paths. The addon queues disk writes asynchronously while 7-Zip continues extracting later entries; `onExtract` runs after that file's queued writes have completed and the file is closed. File contents are not streamed through Node.js or Electron. The `extractToFolder()` promise resolves after all `onExtract` callbacks have run.
+
+On Windows only, unsupported filename characters (including control characters), trailing dots/spaces in each destination component, and reserved device names are normalized for the output path; selectors and entry metadata remain unchanged. On Linux and macOS, platform-supported filename characters are preserved. 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
 
@@ -329,7 +344,7 @@ BENCH_ITERATIONS=20 npm run benchmark -- "./archive.zip"
 
 It measures native open/list, prefix reads, full extraction, and reads across independent archive handles. `BENCH_ITERATIONS` defaults to 15 and must be at least 3.
 
-Compare the native API with the `7zip-bin-full` command-line baseline:
+Compare the native API with the `7zzc` command-line baseline from `7zip-bin-full`:
 
 ```sh
 npm run benchmark:compare -- \
@@ -340,7 +355,7 @@ npm run benchmark:compare -- \
 	--concurrency 4
 ```
 
-The comparison validates entry listings and output data before reporting median and p95 latency. CLI timings include process startup. Since the CLI has no ranged-read API, its range baseline extracts the entry to stdout and slices the requested bytes; this is not equivalent to native range reading. Captured output is capped at 256 MiB, and full-archive comparison is skipped if an entry exceeds that limit.
+The comparison validates entry listings and output data before reporting median and p95 latency. CLI timings include process startup. Prefix reads use `-slb`; non-solid archives abort decoding per item once the byte limit is reached. For a range, the CLI emits through `offset + length` and slices stdout because it has no ranged-read API; this still needs to decode the preceding bytes. Captured output is capped at 256 MiB, and full-archive comparison is skipped if an entry exceeds that limit.
 
 Compare extraction concurrency:
 
@@ -354,6 +369,23 @@ 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 parallel extraction of every file in the archive, divided among promises:
+
+```sh
+npm run benchmark:multiprocess -- \
+	--archive "./archive.zip" \
+	--parallel-counts 1,2,4 \
+	--iterations 3
+
+ELECTRON_RUN_AS_NODE=1 electron bench/multiprocess-extract.cjs \
+	--archive "./archive.zip" \
+	--parallel-counts 1,2,4 \
+	--iterations 3 \
+	--deflate-buffer-size 262144
+```
+
+For each parallel count, the benchmark uses `Promise.all()`: every `7zip-native` promise opens its own handle to the same archive, and every `7zip-bin-full` promise spawns one `7zzc` command. All non-directory files in the archive are divided as evenly as possible among the concurrent operations. The native extraction pool is sized to the maximum requested parallel count so native promises can run concurrently. Outputs go to separate temporary directories and are verified by file size before cleanup. The report includes `Archive.open()` and CLI startup time. Native operations stay in the benchmark's Node/Electron process; only the CLI baseline spawns child processes.
+
 Compare `extractToFolder()` concurrency (1 through 16) across one or more archives:
 
 ```sh

package/bench/compare.mts

@@ -35,12 +35,12 @@ if(!Number.isSafeInteger(parallelConcurrency) || parallelConcurrency < 1 || para
 }
 
 const require = createRequire(import.meta.url);
-const binaryPackage = require('7zip-bin-full') as {path7z?: unknown};
-if(typeof binaryPackage.path7z !== 'string')
+const binaryPackage = require('7zip-bin-full') as {path7zc?: unknown};
+if(typeof binaryPackage.path7zc !== 'string')
 {
-	throw new TypeError('7zip-bin-full does not provide a path7z binary for this platform');
+	throw new TypeError('7zip-bin-full does not provide a path7zc binary for this platform');
 }
-const binaryPath = binaryPackage.path7z;
+const binaryPath = binaryPackage.path7zc;
 
 function runCli(args: readonly string[], outputLimit = maxCapturedBytes): Promise<Buffer>
 {
@@ -142,10 +142,18 @@ function cliList(): Promise<CliEntry[]>
 	return runCli(['l', '-slt', '-sccUTF-8', archivePath]).then(parseCliEntries);
 }
 
-function cliExtract(paths: readonly string[], outputLimit = maxCapturedBytes): Promise<Buffer>
+function cliExtract(
+	paths: readonly string[],
+	outputLimit = maxCapturedBytes,
+	byteLimit?: number,
+): Promise<Buffer>
 {
-	return runCli([
-		'x',
+	const args = ['x'];
+	if(byteLimit !== undefined)
+	{
+		args.push(`-slb${byteLimit}`);
+	}
+	args.push(
 		archivePath,
 		...paths,
 		'-so',
@@ -154,7 +162,8 @@ function cliExtract(paths: readonly string[], outputLimit = maxCapturedBytes): P
 		'-bb0',
 		'-spd',
 		'-sccUTF-8',
-	], outputLimit);
+	);
+	return runCli(args, outputLimit);
 }
 
 function isGroupedExtractionResult(value: BenchmarkResult): value is GroupedExtractionResult
@@ -502,7 +511,7 @@ try
 		));
 	}
 
-	const rangeNote = '7zip-bin-full decompresses the whole entry and slices stdout; it has no ranged-read API';
+	const rangeNote = '7zzc uses -slb; non-solid archives abort per item, while ranges emit through offset + length and slice stdout';
 	for(const [name, offset, length] of [
 		['read_prefix', 0n, prefixLength],
 		['read_range_at_one_third', rangeOffset, rangeLength],
@@ -515,8 +524,13 @@ try
 		}
 		const nativeRead = () => archive.read(file.id, {offset, length});
 		const cliRead = async () => {
-			const full = await cliExtract([file.path], Number(file.size));
-			return full.subarray(Number(offset), Number(offset + length));
+			if(length === 0n)
+			{
+				return Buffer.alloc(0);
+			}
+			const limit = Number(offset + length);
+			const output = await cliExtract([file.path], limit, limit);
+			return output.subarray(Number(offset), limit);
 		};
 		results.push(await measurePair(name, nativeRead, cliRead));
 	}

package/bench/folder-concurrency.mts

@@ -1,7 +1,7 @@
 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';
+import {Archive} from '../dist/index.mjs';
 
 const usage = 'npm run benchmark:folder-concurrency -- --archive <path> [--archive <path> ...] [--iterations <count>] [--concurrency <workers> | --concurrencies <workers,...>]';
 const archivePaths: string[] = [];
@@ -119,27 +119,20 @@ try
 				for(let iteration = 0; iteration < iterations; iteration++)
 				{
 					const temporaryDirectory = await mkdtemp(join(tmpdir(), '7zip-native-folder-bench-'));
-					let finalProgress: ExtractToFolderProgress | undefined;
+					let finalPercent = 0;
 					let completedFiles = 0;
 					try
 					{
 						const start = process.hrtime.bigint();
 						await archive.extractToFolder(join(temporaryDirectory, 'output'), {
 							concurrency,
-							onProgress: progress => {
-								finalProgress = progress;
-							},
-							onExtract: () => {
+							onExtract: ({percent}) => {
 								completedFiles++;
+								finalPercent = percent;
 							},
 						});
 						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)
+						if(completedFiles !== files.length || finalPercent !== 100)
 						{
 							throw new Error(`Extraction verification failed for ${archivePath} at concurrency ${concurrency}`);
 						}

package/bench/multiprocess-extract.cjs

@@ -0,0 +1,334 @@
+'use strict';
+
+const {spawn} = require('node:child_process');
+const {mkdtemp, rm, stat} = require('node:fs/promises');
+const {tmpdir} = require('node:os');
+const path = require('node:path');
+
+function elapsedMs(start)
+{
+	return Number(process.hrtime.bigint() - start) / 1e6;
+}
+
+function errorText(chunks)
+{
+	return Buffer.concat(chunks).toString('utf8').trim();
+}
+
+async function extractNative(Archive, archivePath, outputPath, files, deflateBufferSize)
+{
+	const started = process.hrtime.bigint();
+	let archive;
+	try
+	{
+		archive = await Archive.open(archivePath, {deflateBufferSize});
+		await archive.extractToFolder(outputPath, {
+			paths: files.map(file => file.path),
+			concurrency: 1,
+		});
+	}
+	finally
+	{
+		await archive?.close();
+	}
+	return elapsedMs(started);
+}
+
+function extractWithCli(binaryPath, archivePath, outputPath, files)
+{
+	return new Promise((resolve, reject) => {
+		const started = process.hrtime.bigint();
+		const args = [
+			'x',
+			archivePath,
+			...files.map(file => file.path),
+			`-o${outputPath}`,
+			'-y',
+			'-bd',
+			'-bb0',
+			'-mmt=1',
+			'-sccUTF-8',
+			'-spd',
+		];
+		const child = spawn(binaryPath, args, {stdio: ['ignore', 'ignore', 'pipe']});
+		const stderr = [];
+		let stderrLength = 0;
+		child.stderr.on('data', chunk => {
+			if(stderrLength < 64 * 1024)
+			{
+				const kept = chunk.subarray(0, 64 * 1024 - stderrLength);
+				stderr.push(kept);
+				stderrLength += kept.length;
+			}
+		});
+		child.once('error', reject);
+		child.once('close', (code, signal) => {
+			if(code !== 0)
+			{
+				const detail = errorText(stderr);
+				reject(new Error(
+					`7zip-bin-full exited with ${signal ?? code}${detail ? `: ${detail}` : ''}`,
+				));
+				return;
+			}
+			resolve(elapsedMs(started));
+		});
+	});
+}
+
+function safeOutputPath(root, entryPath)
+{
+	const normalized = entryPath.replace(/\\/g, '/');
+	const parts = normalized.split('/').filter(part => part !== '' && part !== '.');
+	if(normalized.startsWith('/') || parts.length === 0 || parts.some(part => part === '..'))
+	{
+		throw new Error(`Unsafe archive path in benchmark input: ${entryPath}`);
+	}
+	return path.resolve(root, ...parts);
+}
+
+async function verifyOutput(outputPath, files)
+{
+	let totalBytes = 0n;
+	for(const file of files)
+	{
+		const outputFile = safeOutputPath(outputPath, file.path);
+		const outputStat = await stat(outputFile);
+		if(!outputStat.isFile() || BigInt(outputStat.size) !== file.size)
+		{
+			throw new Error(
+				`Extraction mismatch for ${file.path}: expected ${file.size} bytes, got ${outputStat.size}`,
+			);
+		}
+		totalBytes += file.size;
+	}
+	return totalBytes;
+}
+
+async function runWave(
+	backend,
+	Archive,
+	binaryPath,
+	archivePath,
+	groups,
+	expectedFileCount,
+	parallelOperations,
+	deflateBufferSize,
+)
+{
+	if(groups.length !== parallelOperations
+		|| groups.some(files => files.length === 0)
+		|| groups.reduce((sum, files) => sum + files.length, 0) !== expectedFileCount)
+	{
+		throw new Error(`The concurrent operations must partition exactly ${expectedFileCount} files`);
+	}
+
+	const temporaryRoot = await mkdtemp(path.join(tmpdir(), '7zip-native-parallel-extract-'));
+	const started = process.hrtime.bigint();
+	try
+	{
+		const operations = groups.map((files, index) => {
+			const outputPath = path.join(temporaryRoot, `operation-${index + 1}`);
+			return backend === 'native'
+				? extractNative(Archive, archivePath, outputPath, files, deflateBufferSize)
+				: extractWithCli(binaryPath, archivePath, outputPath, files);
+		});
+		let operationTimes;
+		try
+		{
+			operationTimes = await Promise.all(operations);
+		}
+		catch(error)
+		{
+			await Promise.allSettled(operations);
+			throw error;
+		}
+		const wallMs = elapsedMs(started);
+		let totalBytes = 0n;
+		for(let index = 0; index < parallelOperations; index++)
+		{
+			const files = groups[index];
+			totalBytes += await verifyOutput(
+				path.join(temporaryRoot, `operation-${index + 1}`),
+				files,
+			);
+		}
+		return {wallMs, operationTimes, totalBytes};
+	}
+	finally
+	{
+		await rm(temporaryRoot, {recursive: true, force: true});
+	}
+}
+
+function summarize(values)
+{
+	const sorted = [...values].sort((left, right) => left - right);
+	const median = sorted.length % 2 === 0
+		? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+		: sorted[Math.floor(sorted.length / 2)];
+	const p95 = sorted[Math.ceil(sorted.length * 0.95) - 1];
+	return {median_ms: median, p95_ms: p95, samples_ms: values};
+}
+
+function partitionFiles(files, partitionCount)
+{
+	const groups = [];
+	const baseSize = Math.floor(files.length / partitionCount);
+	const remainder = files.length % partitionCount;
+	let offset = 0;
+	for(let index = 0; index < partitionCount; index++)
+	{
+		const groupSize = baseSize + (index < remainder ? 1 : 0);
+		groups.push(files.slice(offset, offset + groupSize));
+		offset += groupSize;
+	}
+	return groups;
+}
+
+function parseArguments(args)
+{
+	const values = new Map();
+	for(let index = 0; index < args.length; index++)
+	{
+		const argument = args[index];
+		if(!argument.startsWith('--'))
+		{
+			throw new TypeError(`Unexpected argument ${argument}`);
+		}
+		const equals = argument.indexOf('=');
+		const key = argument.slice(2, equals === -1 ? undefined : equals);
+		const value = equals === -1 ? args[++index] : argument.slice(equals + 1);
+		if(!value || value.startsWith('--') || values.has(key))
+		{
+			throw new TypeError(`Invalid or repeated option --${key}`);
+		}
+		if(!['archive', 'parallel-counts', 'iterations', 'deflate-buffer-size'].includes(key))
+		{
+			throw new TypeError(`Unknown option --${key}`);
+		}
+		values.set(key, value);
+	}
+	const archivePath = values.get('archive');
+	if(!archivePath)
+	{
+		throw new TypeError(
+			'Usage: node bench/multiprocess-extract.cjs --archive <zip> [--parallel-counts 1,2,4] [--iterations 3] [--deflate-buffer-size 262144]',
+		);
+	}
+	const parallelCounts = [...new Set((values.get('parallel-counts') ?? '1,2,4')
+		.split(',')
+		.map(value => Number(value)))];
+	if(parallelCounts.length === 0
+		|| parallelCounts.some(value => !Number.isSafeInteger(value) || value < 1 || value > 32))
+	{
+		throw new RangeError('--parallel-counts must contain integers between 1 and 32');
+	}
+	const iterations = Number(values.get('iterations') ?? 3);
+	if(!Number.isSafeInteger(iterations) || iterations < 1 || iterations > 20)
+	{
+		throw new RangeError('--iterations must be an integer between 1 and 20');
+	}
+	const deflateBufferSize = Number(values.get('deflate-buffer-size') ?? 256 * 1024);
+	if(!Number.isSafeInteger(deflateBufferSize)
+		|| deflateBufferSize < 4 * 1024
+		|| deflateBufferSize > 2 * 1024 * 1024)
+	{
+		throw new RangeError('--deflate-buffer-size must be between 4096 and 2097152 bytes');
+	}
+	return {archivePath: path.resolve(archivePath), parallelCounts, iterations, deflateBufferSize};
+}
+
+async function main()
+{
+	const {Archive} = require('7zip-native');
+	const {path7zc} = require('7zip-bin-full');
+	const options = parseArguments(process.argv.slice(2));
+	Archive.concurrency(Math.max(...options.parallelCounts));
+	const listingArchive = await Archive.open(options.archivePath);
+	let files;
+	try
+	{
+		files = (await listingArchive.entries())
+			.filter(entry => !entry.isDirectory)
+			.map(entry => ({path: entry.path, size: entry.size}));
+	}
+	finally
+	{
+		await listingArchive.close();
+	}
+	if(files.length === 0)
+	{
+		throw new RangeError('The archive contains no files to extract');
+	}
+	if(options.parallelCounts.some(count => count > files.length))
+	{
+		throw new RangeError('The parallel count cannot exceed the number of files in the archive');
+	}
+	const runtime = process.versions.electron ? 'electron-as-node' : 'node';
+	const totalBytes = files.reduce((sum, file) => sum + file.size, 0n);
+	const results = [];
+	for(const parallelOperations of options.parallelCounts)
+	{
+		const groups = partitionFiles(files, parallelOperations);
+		const samples = {native: [], cli: []};
+		await runWave(
+			'native', Archive, path7zc, options.archivePath, groups, files.length,
+			parallelOperations, options.deflateBufferSize,
+		);
+		await runWave(
+			'cli', Archive, path7zc, options.archivePath, groups, files.length,
+			parallelOperations, options.deflateBufferSize,
+		);
+		for(let iteration = 0; iteration < options.iterations; iteration++)
+		{
+			const backends = iteration % 2 === 0 ? ['native', 'cli'] : ['cli', 'native'];
+			for(const backend of backends)
+			{
+				samples[backend].push(await runWave(
+					backend, Archive, path7zc, options.archivePath, groups, files.length,
+					parallelOperations, options.deflateBufferSize,
+				));
+			}
+		}
+		for(const backend of ['native', 'cli'])
+		{
+			const waves = samples[backend];
+			const wall = summarize(waves.map(wave => wave.wallMs));
+			const operationTimes = summarize(waves.flatMap(wave => wave.operationTimes));
+			const medianWall = wall.median_ms;
+			results.push({
+				backend: backend === 'native' ? '7zip-native' : '7zip-bin-full (7zzc)',
+				parallel_promises: parallelOperations,
+				files_per_promise: groups.map(group => group.length),
+				total_file_extractions: files.length,
+				unique_files: files.length,
+				total_output_bytes: totalBytes.toString(),
+				median_wall_ms: medianWall,
+				p95_wall_ms: wall.p95_ms,
+				median_operation_ms: operationTimes.median_ms,
+				throughput_mib_per_second: Number(totalBytes) / (medianWall / 1000) / 1024 / 1024,
+				samples_ms: wall.samples_ms,
+			});
+		}
+	}
+	console.log(JSON.stringify({
+		runtime,
+		archive: options.archivePath,
+		archive_file_count: files.length,
+		iterations: options.iterations,
+		deflate_buffer_size: options.deflateBufferSize,
+		total_files_per_run: files.length,
+		files_partitioned_across_promises: true,
+		includes_archive_open: true,
+		includes_cli_process_startup: true,
+		native_extraction_runs_in_benchmark_process: true,
+		cli_binary: path7zc,
+		results,
+	}, null, 2));
+}
+
+main().catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});