7zip-native 0.0.7 → 0.0.10

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,14 @@ 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.
+- `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
 
@@ -107,9 +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},
+]);
 ```
 
-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 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. 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
 
@@ -125,7 +147,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,21 +165,34 @@ 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('./comic.cbz', [
-	{sourcePath: './pages/cover.jpg', path: 'cover.jpg'},
-	{sourcePath: './pages/01.jpg', path: 'pages/01.jpg'},
+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. 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.
+`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.
+
+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.
 
 ### Extracting to a folder
 
@@ -160,18 +201,27 @@ 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,
 });
 ```
 
-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.
+`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 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.
+
+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, 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
 
@@ -181,7 +231,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.
 
@@ -256,7 +310,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
 
@@ -290,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 -- \
@@ -301,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:
 
@@ -315,16 +369,34 @@ 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
 npm run benchmark:folder-concurrency -- \
 	--archive "./samples/sample.zip" \
 	--archive "./archive.7z" \
+	--concurrencies 1,2,3,4,5,8,16 \
 	--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.
+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
 

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,11 +1,13 @@
 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>]';
+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++)
 {
@@ -32,6 +34,34 @@ for(let index = 0; index < args.length; index++)
 		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}`);
 }
 
@@ -43,8 +73,27 @@ 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');
+}
 
-const concurrencies = Array.from({length: 16}, (_, index) => index + 1);
+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
@@ -70,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}`);
 						}