7zip-native 0.0.0-stage → 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleguer Llopart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,294 @@
-# Temporary Holding Version
+> [!CAUTION]
+> This project was generated primarily by an LLM and may contain errors. Review and validate it before use, especially in production.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 7zip-native
+
+Native Node-API bindings for the 7-Zip archive engine. Use a typed, Promise-based Node.js API to inspect archives, read entry data, stream large files, or extract entries without launching `7z`, `7zz`, or another archive executable.
+
+The package includes the native addon and the matching 7-Zip engine for each supported target. Compression and decompression are provided by the upstream 7-Zip implementation.
+
+## Installation
+
+```sh
+npm install 7zip-native
+```
+
+The package requires Node.js 18 or newer. The release workflow builds and tests with Node.js 22.
+
+## Quick start
+
+```ts
+import {Archive} from '7zip-native';
+
+const archive = await Archive.open('./comics.cbz');
+
+try
+{
+	const entries = await archive.entries();
+	const cover = await archive.getEntry('chapter/cover.jpg');
+
+	if(cover && !cover.isDirectory)
+	{
+		const preview = await archive.read(cover.path, {offset: 0, length: 64 * 1024});
+		const image = await archive.extract(cover.path);
+		console.log(entries.length, preview.length, image.length);
+	}
+}
+finally
+{
+	await archive.close();
+}
+```
+
+The package supports both ES modules and CommonJS:
+
+```js
+// ES module
+import {Archive} from '7zip-native';
+
+// CommonJS
+const {Archive} = require('7zip-native');
+```
+
+## API
+
+### `Archive.open(path, options?)`
+
+Opens an archive from a filesystem path and indexes its metadata asynchronously.
+
+```ts
+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.
+
+### Listing and looking up entries
+
+```ts
+const entries = await archive.entries();
+const byPath = await archive.getEntry('folder/page.jpg');
+const byId = await archive.getEntry(0);
+```
+
+`entries()` returns cached metadata. Entry IDs are zero-based and stable for the lifetime of the opened archive. `getEntry()` returns `undefined` if the ID or full path does not match.
+
+All entry-targeted methods accept either the entry's numeric `id` or its exact archive-internal `path`: `extract()`, `read()`, `createReadStream()`, and `extractToStream()`. Batch `extract()` calls can mix IDs and paths. For folder extraction, use either the `ids` or `paths` option; omit both to extract every entry.
+
+Each entry includes:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `number` | Stable ID within this opened archive |
+| `path` | `string` | Entry path, using `/` separators |
+| `size` | `bigint` | Uncompressed size |
+| `compressedSize` | `bigint` | Compressed size |
+| `isDirectory` | `boolean` | Whether the entry is a directory |
+| `encrypted` | `boolean` | Whether the entry is encrypted |
+| `attributes` | `number` | Format-specific attributes |
+| `crc` | `number \| undefined` | CRC when supplied by the format |
+
+### Extracting to memory
+
+```ts
+const image = await archive.extract(entry.id); // Buffer
+const sameImage = await archive.extract(entry.path); // Buffer
+const pages = await archive.extract([page1.id, page2.path]); // Buffer[]
+```
+
+Paths use `/` separators. Batch results are returned in the same order as the requested selectors; duplicate entries are rejected. A missing path rejects with `ERR_INVALID_ENTRY`. A buffered extraction is limited to 256 MiB per entry, with a 512 MiB cap on native results pending transfer to JavaScript. For large entries, use a stream or extract to a folder instead.
+
+### Reading a byte range
+
+```ts
+const header = await archive.read(entry.path, {
+	offset: 0,
+	length: 64 * 1024,
+});
+```
+
+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.
+
+### Streams and output destinations
+
+Create a standard Node.js `Readable` for a large entry:
+
+```ts
+for await (const chunk of archive.createReadStream(entry.path, {
+	highWaterMark: 256 * 1024,
+	signal: abortController.signal,
+}))
+{
+	// Consume each Buffer chunk before requesting more data.
+}
+```
+
+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.
+
+To pipe directly to a Node.js `Writable`:
+
+```ts
+import {createWriteStream} from 'node:fs';
+
+await archive.extractToStream(entry.path, createWriteStream('./page.jpg'), {
+	signal: abortController.signal,
+});
+```
+
+This respects backpressure and ends the destination when extraction succeeds. A destination error, early close, or abort rejects the Promise.
+
+### Extracting to a folder
+
+```ts
+await archive.extractToFolder('./unpacked', {
+	paths: ['chapter/page1.jpg', 'chapter/page2.jpg'], // alternatively, use ids
+	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. Existing files are never overwritten. Unsafe paths, path collisions, and symlinked destination components 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
+
+```ts
+const current = Archive.concurrency();
+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.
+
+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.
+
+### Closing an archive
+
+Call `close()` when finished. It rejects future API calls; operations already submitted keep the native state alive until they finish.
+
+```ts
+await archive.close();
+```
+
+## Errors and limits
+
+Invalid argument types and values throw standard `TypeError` or `RangeError`. Archive and extraction failures use `ArchiveError`, which has a stable `code` property:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_ARCHIVE_CLOSED` | Operation attempted after `close()` |
+| `ERR_INVALID_ENTRY` | Entry ID is invalid or out of range |
+| `ERR_INVALID_RANGE` | Byte range is invalid or exceeds the native offset limit |
+| `ERR_RESOURCE_LIMIT` | Configured or default output limit was exceeded |
+| `ERR_ARCHIVE_OPEN` | Archive could not be opened or indexed |
+| `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 |
+
+Buffered `extract()` and `read()` do not currently support cancellation. Streams and folder extraction accept an `AbortSignal`.
+
+## Supported formats
+
+The package uses the handlers registered in the pinned upstream `Format7zF` bundle, including 7z, ZIP, RAR, TAR, GZIP, BZIP2, XZ, WIM, ISO/UDF, CAB, ARJ, LZH, CPIO, Zstandard, and additional formats enabled by that upstream revision. Whether a particular archive can be extracted depends on its handler and compression method; unsupported methods, corrupt data, and integrity failures reject the operation. Standalone compression codecs are not necessarily archive formats.
+
+### 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.
+- **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.
+
+See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for third-party redistribution terms.
+
+## Platform support
+
+The release workflow builds eight targets:
+
+| Platform | Architecture | CI verification |
+| --- | --- | --- |
+| Linux | x64, ARM64 | Build and runtime tests |
+| Linux | x86 (ia32), ARM32 | Cross-compile and verify binary architecture; not runtime-tested in CI |
+| macOS | x64, ARM64 | Build and runtime tests |
+| Windows | x64, ARM64 | Build and runtime tests |
+
+The published binaries must match the target operating system and architecture. Windows x86 (ia32) prebuilds are not published. The package declares Node.js `>=18`; the workflow currently builds and tests with Node.js 26. This checkout has been verified locally on Linux x64. Do not treat cross-compiled Linux 32-bit artifacts as runtime-tested.
+
+## Electron
+
+The addon uses Node-API, but the addon and 7-Zip engine still need to match the Electron application's operating system and architecture. Use a matching package prebuild when available, or rebuild for the Electron version and target architecture using your Electron build tooling.
+
+When packaging with ASAR, ensure both `7zip_native.node` and the matching engine library (`7z.dll`, `7z.so`, or `lib7z.dylib`) are physically unpacked and that the runtime paths resolve to those unpacked files. For `electron-builder`, an `asarUnpack` configuration can include:
+
+```json
+{
+	"build": {
+		"asarUnpack": [
+			"node_modules/7zip-native/prebuilds/**/*.node",
+			"node_modules/7zip-native/prebuilds/**/*.dll",
+			"node_modules/7zip-native/prebuilds/**/*.so",
+			"node_modules/7zip-native/prebuilds/**/*.dylib"
+		]
+	}
+}
+```
+
+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
+
+```sh
+git clone --recurse-submodules https://github.com/ollm/7zip-native.git
+cd 7zip-native
+npm ci --ignore-scripts
+npm run build
+npm test
+```
+
+Source builds require a C++17 toolchain, Python 3, Node.js headers (downloaded by `node-gyp`), and the upstream submodule. Linux and macOS use GNU make; Windows requires Visual C++ build tools and `nmake`. `npm run build:native` compiles the upstream `Format7zF` bundle and Node-API addon, then stages them under `prebuilds/<platform>-<arch>/`.
+
+To update the upstream submodule deliberately:
+
+```sh
+git submodule update --remote vendor/7zip
+git -C vendor/7zip rev-parse HEAD
+git add .gitmodules vendor/7zip
+```
+
+Review the upstream changes and commit the new submodule revision. The current submodule is pinned to 7-Zip 26.05 (`b88c6bc09339de32f7d18bbab900686b244f42ba`).
+
+## Benchmarks
+
+Run the native benchmark against a representative archive:
+
+```sh
+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:
+
+```sh
+npm run benchmark:compare -- \
+	--archive "./archive.zip" \
+	--entry "chapter/page.jpg" \
+	--iterations 20 \
+	--read-bytes 65536 \
+	--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.
+
+Compare extraction concurrency:
+
+```sh
+npm run benchmark:concurrency -- \
+	--archive "./archive.7z" \
+	--iterations 20 \
+	--concurrencies 1,2,3,4,5,8,16 \
+	--max-files 20
+```
+
+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.
+
+## 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/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+## 7-Zip
+
+This package bundles a shared-library build of 7-Zip 26.05 from the official
+`ip7z/7zip` repository, preserved as a git submodule at `vendor/7zip`.
+Copyright (C) 1999-2026 Igor Pavlov.
+
+Most bundled files are licensed under GNU LGPL 2.1 or later. Some files have
+separate BSD or public-domain notices, as identified by upstream. The complete
+license texts are preserved in `vendor/7zip/DOC/License.txt`; distribution
+must retain those notices and comply with the applicable license for each
+component.
+
+RAR decompression uses source subject to the additional unRAR license
+restriction. RAR source may handle RAR archives, but may not be used to
+recreate the proprietary RAR compression algorithm. This package offers no
+RAR creation functionality. The full restriction is preserved in
+`vendor/7zip/DOC/unRarLicense.txt`.
+
+The addon adapter and TypeScript API are MIT-licensed. The addon dynamically
+links the upstream engine shared library rather than statically linking its
+code into the Node-API module.

package/bench/args.mts

@@ -0,0 +1,69 @@
+export interface BenchmarkArguments {
+	readonly archivePath: string;
+	readonly options: ReadonlyMap<string, string>;
+}
+
+export function parseBenchmarkArguments(
+	args: readonly string[],
+	availableOptions: readonly string[],
+	usage: string,
+): BenchmarkArguments
+{
+	const options = new Map<string, string>();
+	const supportedOptions = new Set(availableOptions);
+	let archivePath: string | undefined;
+
+	for(let index = 0; index < args.length; index++)
+	{
+		const argument = args[index]!;
+		if(argument === '--archive' || argument.startsWith('--archive='))
+		{
+			if(archivePath !== undefined)
+			{
+				throw new TypeError('The archive path may only be specified once');
+			}
+			const equalsIndex = argument.indexOf('=');
+			const value = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+			if(!value || value.startsWith('--'))
+			{
+				throw new TypeError('Missing value for --archive');
+			}
+			archivePath = value;
+			continue;
+		}
+
+		if(argument.startsWith('--'))
+		{
+			const equalsIndex = argument.indexOf('=');
+			const name = argument.slice(2, equalsIndex === -1 ? undefined : equalsIndex);
+			if(!supportedOptions.has(name))
+			{
+				throw new TypeError(`Unknown option --${name}\nUsage: ${usage}`);
+			}
+			if(options.has(name))
+			{
+				throw new TypeError(`Option --${name} may only be specified once`);
+			}
+			const value = equalsIndex === -1 ? args[++index] : argument.slice(equalsIndex + 1);
+			if(!value || value.startsWith('--'))
+			{
+				throw new TypeError(`Missing value for --${name}`);
+			}
+			options.set(name, value);
+			continue;
+		}
+
+		if(archivePath !== undefined)
+		{
+			throw new TypeError(`Unexpected argument ${argument}\nUsage: ${usage}`);
+		}
+		archivePath = argument;
+	}
+
+	if(!archivePath)
+	{
+		throw new TypeError(`Usage: ${usage}`);
+	}
+
+	return {archivePath, options};
+}

package/bench/benchmark.mts

@@ -0,0 +1,102 @@
+import {Archive} from '../dist/index.mjs';
+
+const archivePath = process.argv[2];
+if(!archivePath)
+{
+	throw new TypeError('Usage: npm run benchmark -- <archive-path>');
+}
+
+const iterations = Number(process.env.BENCH_ITERATIONS ?? 15);
+if(!Number.isSafeInteger(iterations) || iterations < 3)
+{
+	throw new RangeError('BENCH_ITERATIONS must be an integer of at least 3');
+}
+
+function summarize(label: string, values: readonly number[])
+{
+	const sorted = [...values].sort((a, b) => a - b);
+	const percentile = (fraction: number) => sorted[Math.min(
+		sorted.length - 1,
+		Math.ceil(sorted.length * fraction) - 1,
+	)]!;
+	return {
+		label,
+		iterations: sorted.length,
+		median_ms: percentile(0.5),
+		p95_ms: percentile(0.95),
+	};
+}
+
+async function sample(label: string, run: () => Promise<unknown>)
+{
+	const durations: number[] = [];
+	for(let i = 0; i < iterations; i++)
+	{
+		const start = process.hrtime.bigint();
+		await run();
+		durations.push(Number(process.hrtime.bigint() - start) / 1e6);
+	}
+	return summarize(label, durations);
+}
+
+const archive = await Archive.open(archivePath);
+const entries = await archive.entries();
+const file = entries.find(entry => !entry.isDirectory);
+if(!file)
+{
+	await archive.close();
+	throw new Error('The benchmark archive contains no files');
+}
+
+const before = process.memoryUsage().rss;
+const results = [];
+try
+{
+	results.push(await sample('open_and_list', async () => {
+		const opened = await Archive.open(archivePath);
+		await opened.entries();
+		await opened.close();
+	}));
+	results.push(await sample('first_64KiB', async () => {
+		await archive.read(file.id, {offset: 0, length: 64 * 1024});
+	}));
+	results.push(await sample('full_extract', async () => {
+		await archive.extract(file.id);
+	}));
+
+	for(const workers of [1, 2, 4, 8])
+	{
+		const handles = await Promise.all(
+			Array.from({length: workers}, () => Archive.open(archivePath)),
+		);
+		try
+		{
+			results.push(await sample(`parallel_reads_${workers}`, async () => {
+				await Promise.all(handles.map(async handle => {
+					const [entry] = await handle.entries();
+					if(entry)
+					{
+						await handle.read(entry.id, {offset: 0, length: 64 * 1024});
+					}
+				}));
+			}));
+		}
+		finally
+		{
+			await Promise.all(handles.map(handle => handle.close()));
+		}
+	}
+}
+finally
+{
+	await archive.close();
+}
+
+console.log(JSON.stringify({
+	archive: archivePath,
+	entry: file.path,
+	entry_size_bytes: file.size.toString(),
+	rss_before_bytes: before,
+	rss_after_bytes: process.memoryUsage().rss,
+	results,
+}, null, 2));