7zip-native 0.0.1 → 0.0.6

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var node_fs = require('node:fs');
 var promises$1 = require('node:fs/promises');
+var node_crypto = require('node:crypto');
 var node_module = require('node:module');
 var node_os = require('node:os');
 var node_path = require('node:path');
@@ -124,6 +125,19 @@ async function ensureDirectory(directoryPath) {
         throw new ArchiveError('ERR_ARCHIVE_PATH', `Destination path is not a real directory: ${directoryPath}`);
     }
 }
+async function assertReplaceableOutput(filePath) {
+    try {
+        const details = await promises$1.lstat(filePath);
+        if (!details.isFile()) {
+            throw new ArchiveError('ERR_ARCHIVE_PATH', `Cannot replace a non-file extraction target: ${filePath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof ArchiveError || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
 async function ensureExtractionRoot(root) {
     try {
         const details = await promises$1.lstat(root);
@@ -167,6 +181,7 @@ class NativeArchiveReadable extends node_stream.Readable {
     maxBytes;
     streamId;
     outputBytes = 0n;
+    starting = false;
     constructor(start, resumeNative, cancel, options, maxBytes) {
         super({ highWaterMark: options.highWaterMark, signal: options.signal });
         this.start = start;
@@ -175,38 +190,63 @@ class NativeArchiveReadable extends node_stream.Readable {
         this.maxBytes = maxBytes;
     }
     _read() {
+        if (this.streamId !== undefined) {
+            try {
+                this.resumeNative(this.streamId);
+            }
+            catch (cause) {
+                this.destroy(extractionError(cause));
+            }
+            return;
+        }
+        if (this.starting) {
+            return;
+        }
+        this.starting = true;
         try {
-            if (this.streamId === undefined) {
-                this.streamId = this.start((chunk, error, done) => {
-                    if (this.destroyed) {
+            Promise.resolve(this.start((chunk, error, done) => {
+                if (this.destroyed) {
+                    return;
+                }
+                if (error) {
+                    this.destroy(extractionError(error));
+                }
+                else if (done) {
+                    this.push(null);
+                }
+                else if (chunk) {
+                    if (this.maxBytes !== null
+                        && this.outputBytes + BigInt(chunk.length) > this.maxBytes) {
+                        this.destroy(new ArchiveError('ERR_RESOURCE_LIMIT', `Stream output exceeds the ${this.maxBytes}-byte limit`));
                         return;
                     }
-                    if (error) {
-                        this.destroy(extractionError(error));
-                    }
-                    else if (done) {
-                        this.push(null);
-                    }
-                    else if (chunk) {
-                        if (this.maxBytes !== null
-                            && this.outputBytes + BigInt(chunk.length) > this.maxBytes) {
-                            this.destroy(new ArchiveError('ERR_RESOURCE_LIMIT', `Stream output exceeds the ${this.maxBytes}-byte limit`));
-                            return;
-                        }
-                        this.outputBytes += BigInt(chunk.length);
-                        this.push(chunk);
+                    this.outputBytes += BigInt(chunk.length);
+                    this.push(chunk);
+                }
+                else {
+                    this.destroy(new ArchiveError('ERR_ARCHIVE_EXTRACT', 'Native stream returned an empty chunk notification'));
+                }
+            })).then((streamId) => {
+                this.streamId = streamId;
+                this.starting = false;
+                try {
+                    if (this.destroyed) {
+                        this.cancel(streamId);
                     }
                     else {
-                        this.destroy(new ArchiveError('ERR_ARCHIVE_EXTRACT', 'Native stream returned an empty chunk notification'));
+                        this.resumeNative(streamId);
                     }
-                });
-                this.resumeNative(this.streamId);
-            }
-            else {
-                this.resumeNative(this.streamId);
-            }
+                }
+                catch (cause) {
+                    this.destroy(extractionError(cause));
+                }
+            }, (cause) => {
+                this.starting = false;
+                this.destroy(extractionError(cause));
+            });
         }
         catch (cause) {
+            this.starting = false;
             this.destroy(extractionError(cause));
         }
     }
@@ -272,21 +312,41 @@ class Archive {
         }
         return (await this.entries()).find(entry => typeof idOrPath === 'number' ? entry.id === idOrPath : entry.path === idOrPath);
     }
-    async extract(idOrIds) {
+    async extract(idOrPathOrPaths) {
         this.assertOpen();
-        const ids = Array.isArray(idOrIds) ? [...idOrIds] : [idOrIds];
-        this.validateIds(ids);
+        const isBatch = Array.isArray(idOrPathOrPaths);
+        let selectors;
+        if (isBatch) {
+            selectors = idOrPathOrPaths;
+        }
+        else {
+            selectors = [idOrPathOrPaths];
+        }
+        const numericIds = selectors.filter((selector) => typeof selector === 'number');
+        let ids;
+        if (numericIds.length === selectors.length) {
+            this.validateIds(numericIds);
+            ids = numericIds;
+        }
+        else {
+            ids = await this.resolveEntryIds(selectors);
+        }
         try {
             const buffers = await native.extract(this.handle, ids);
-            return Array.isArray(idOrIds) ? buffers : buffers[0];
+            return isBatch ? buffers : buffers[0];
         }
         catch (cause) {
             throw extractionError(cause);
         }
     }
-    createReadStream(id, options = {}) {
+    createReadStream(idOrPath, options = {}) {
         this.assertOpen();
-        this.validateIds([id]);
+        if (typeof idOrPath === 'number') {
+            this.validateIds([idOrPath]);
+        }
+        else if (typeof idOrPath !== 'string') {
+            throw new TypeError('Entry selector must be an ID or archive path');
+        }
         if (!options || typeof options !== 'object') {
             throw new TypeError('Stream options must be an object');
         }
@@ -298,13 +358,18 @@ class Archive {
         }
         options.signal?.throwIfAborted();
         const maxBytes = normalizeMaxBytes(options.maxBytes, 'maxBytes');
-        return new NativeArchiveReadable(callback => native.startStream(this.handle, id, callback), streamId => native.resumeStream(streamId), streamId => native.cancelStream(streamId), options, maxBytes);
+        return new NativeArchiveReadable((callback) => {
+            if (typeof idOrPath === 'number') {
+                return native.startStream(this.handle, idOrPath, callback);
+            }
+            return this.resolveEntryId(idOrPath).then(id => native.startStream(this.handle, id, callback));
+        }, streamId => native.resumeStream(streamId), streamId => native.cancelStream(streamId), options, maxBytes);
     }
-    async extractToStream(id, destination, options = {}) {
+    async extractToStream(idOrPath, destination, options = {}) {
         if (!destination || typeof destination.write !== 'function') {
             throw new TypeError('Destination must be a writable stream');
         }
-        await promises.pipeline(this.createReadStream(id, options), destination, { signal: options.signal });
+        await promises.pipeline(this.createReadStream(idOrPath, options), destination, { signal: options.signal });
     }
     async extractToFolder(destination, options = {}) {
         this.assertOpen();
@@ -314,10 +379,19 @@ class Archive {
         if (!options || typeof options !== 'object') {
             throw new TypeError('Folder extraction options must be an object');
         }
+        if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
+            throw new TypeError('Folder extraction overwrite option must be a boolean');
+        }
+        if (options.onProgress !== undefined && typeof options.onProgress !== 'function') {
+            throw new TypeError('Folder extraction onProgress option must be a function');
+        }
         options.signal?.throwIfAborted();
         const maxBytes = normalizeMaxBytes(options.maxBytes, 'maxBytes');
         const entries = await this.entries();
         let selectedEntries = entries;
+        if (options.ids !== undefined && options.paths !== undefined) {
+            throw new TypeError('Specify either folder extraction IDs or paths, not both');
+        }
         if (options.ids !== undefined) {
             if (!Array.isArray(options.ids)) {
                 throw new TypeError('Folder extraction IDs must be an array');
@@ -332,6 +406,21 @@ class Archive {
                 return entry;
             });
         }
+        else if (options.paths !== undefined) {
+            if (!Array.isArray(options.paths)
+                || options.paths.some(entryPath => typeof entryPath !== 'string')) {
+                throw new TypeError('Folder extraction paths must be an array of strings');
+            }
+            const ids = await this.resolveEntryIds(options.paths);
+            const entriesById = new Map(entries.map(entry => [entry.id, entry]));
+            selectedEntries = ids.map((id) => {
+                const entry = entriesById.get(id);
+                if (!entry) {
+                    throw new ArchiveError('ERR_INVALID_ENTRY', `Entry ID ${id} is out of range`);
+                }
+                return entry;
+            });
+        }
         const root = node_path.resolve(destination);
         const plans = makeOutputPlans(root, selectedEntries);
         const expectedBytes = selectedEntries.reduce((total, entry) => total + (entry.isDirectory ? 0n : entry.size), 0n);
@@ -341,6 +430,26 @@ class Archive {
         options.signal?.throwIfAborted();
         await ensureExtractionRoot(root);
         let extractedBytes = 0n;
+        let filesExtracted = 0;
+        const totalFiles = plans.filter(plan => !plan.isDirectory).length;
+        const reportProgress = () => {
+            let percent = 0;
+            if (expectedBytes > 0n) {
+                const scaledPercent = extractedBytes * 10000n / expectedBytes;
+                percent = Number(scaledPercent > 9900n ? 9900n : scaledPercent) / 100;
+            }
+            if (filesExtracted === totalFiles) {
+                percent = 100;
+            }
+            options.onProgress?.({
+                filesExtracted,
+                totalFiles,
+                bytesProcessed: extractedBytes,
+                totalBytes: expectedBytes,
+                percent,
+            });
+        };
+        reportProgress();
         for (const plan of plans) {
             options.signal?.throwIfAborted();
             if (plan.isDirectory) {
@@ -348,7 +457,6 @@ class Archive {
                 continue;
             }
             await ensureOutputParents(root, plan.targetPath);
-            const output = node_fs.createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 });
             const limit = new node_stream.Transform({
                 transform(chunk, _encoding, callback) {
                     const size = BigInt(chunk.length);
@@ -357,18 +465,52 @@ class Archive {
                         return;
                     }
                     extractedBytes += size;
+                    try {
+                        reportProgress();
+                    }
+                    catch (error) {
+                        callback(error instanceof Error ? error : new Error(String(error)));
+                        return;
+                    }
                     callback(null, chunk);
                 },
             });
-            await promises.pipeline(this.createReadStream(plan.entry.id, {
-                signal: options.signal,
-                maxBytes: null,
-            }), limit, output, { signal: options.signal });
+            if (options.overwrite) {
+                await assertReplaceableOutput(plan.targetPath);
+                const temporaryPath = node_path.join(node_path.dirname(plan.targetPath), `.7zip-native-${node_crypto.randomUUID()}.tmp`);
+                try {
+                    await promises.pipeline(this.createReadStream(plan.entry.id, {
+                        signal: options.signal,
+                        maxBytes: null,
+                    }), limit, node_fs.createWriteStream(temporaryPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+                    await assertReplaceableOutput(plan.targetPath);
+                    await promises$1.rename(temporaryPath, plan.targetPath);
+                }
+                catch (error) {
+                    await promises$1.rm(temporaryPath, { force: true });
+                    throw error;
+                }
+            }
+            else {
+                await promises.pipeline(this.createReadStream(plan.entry.id, {
+                    signal: options.signal,
+                    maxBytes: null,
+                }), limit, node_fs.createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+            }
+            filesExtracted++;
+            reportProgress();
         }
     }
-    async read(id, options) {
+    async read(idOrPath, options) {
         this.assertOpen();
-        this.validateIds([id]);
+        let id;
+        if (typeof idOrPath === 'number') {
+            this.validateIds([idOrPath]);
+            id = idOrPath;
+        }
+        else {
+            id = await this.resolveEntryId(idOrPath);
+        }
         const offset = this.toUnsignedBigInt(options.offset ?? 0, 'offset');
         const length = this.toUnsignedBigInt(options.length, 'length');
         const maxUInt64 = (1n << 64n) - 1n;
@@ -399,6 +541,25 @@ class Archive {
             throw new ArchiveError('ERR_INVALID_ENTRY', 'Entry IDs must be unique non-negative safe integers');
         }
     }
+    async resolveEntryId(selector) {
+        if (typeof selector === 'number') {
+            this.validateIds([selector]);
+            return selector;
+        }
+        if (typeof selector !== 'string') {
+            throw new TypeError('Entry selector must be an ID or archive path');
+        }
+        const entry = await this.getEntry(selector);
+        if (!entry) {
+            throw new ArchiveError('ERR_INVALID_ENTRY', `Archive entry "${selector}" was not found`);
+        }
+        return entry.id;
+    }
+    async resolveEntryIds(selectors) {
+        const ids = await Promise.all(selectors.map(selector => this.resolveEntryId(selector)));
+        this.validateIds(ids);
+        return ids;
+    }
     toUnsignedBigInt(value, label) {
         if (typeof value === 'bigint') {
             if (value < 0n) {

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { Readable, Writable } from 'node:stream';
 
 type EntryId = number;
+type EntrySelector = EntryId | string;
 interface ArchiveEntry {
     readonly id: EntryId;
     readonly path: string;
@@ -18,6 +19,13 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+interface ExtractToFolderProgress {
+    readonly filesExtracted: number;
+    readonly totalFiles: number;
+    readonly bytesProcessed: bigint;
+    readonly totalBytes: bigint;
+    readonly percent: number;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -25,6 +33,9 @@ interface ReadStreamOptions {
 }
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
+    readonly paths?: readonly string[];
+    readonly overwrite?: boolean;
+    readonly onProgress?: (progress: ExtractToFolderProgress) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
@@ -42,18 +53,20 @@ declare class Archive {
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
     entries(): Promise<readonly ArchiveEntry[]>;
-    getEntry(idOrPath: EntryId | string): Promise<ArchiveEntry | undefined>;
-    extract(id: EntryId): Promise<Buffer>;
-    extract(ids: readonly EntryId[]): Promise<Buffer[]>;
-    createReadStream(id: EntryId, options?: ReadStreamOptions): Readable;
-    extractToStream(id: EntryId, destination: Writable, options?: ReadStreamOptions): Promise<void>;
+    getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
+    extract(idOrPath: EntrySelector): Promise<Buffer>;
+    extract(idsOrPaths: readonly EntrySelector[]): Promise<Buffer[]>;
+    createReadStream(idOrPath: EntrySelector, options?: ReadStreamOptions): Readable;
+    extractToStream(idOrPath: EntrySelector, destination: Writable, options?: ReadStreamOptions): Promise<void>;
     extractToFolder(destination: string, options?: ExtractToFolderOptions): Promise<void>;
-    read(id: EntryId, options: ReadOptions): Promise<Buffer>;
+    read(idOrPath: EntrySelector, options: ReadOptions): Promise<Buffer>;
     close(): Promise<void>;
     private assertOpen;
     private validateIds;
+    private resolveEntryId;
+    private resolveEntryIds;
     private toUnsignedBigInt;
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, ExtractToFolderOptions, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { Readable, Writable } from 'node:stream';
 
 type EntryId = number;
+type EntrySelector = EntryId | string;
 interface ArchiveEntry {
     readonly id: EntryId;
     readonly path: string;
@@ -18,6 +19,13 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+interface ExtractToFolderProgress {
+    readonly filesExtracted: number;
+    readonly totalFiles: number;
+    readonly bytesProcessed: bigint;
+    readonly totalBytes: bigint;
+    readonly percent: number;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -25,6 +33,9 @@ interface ReadStreamOptions {
 }
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
+    readonly paths?: readonly string[];
+    readonly overwrite?: boolean;
+    readonly onProgress?: (progress: ExtractToFolderProgress) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
@@ -42,18 +53,20 @@ declare class Archive {
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
     entries(): Promise<readonly ArchiveEntry[]>;
-    getEntry(idOrPath: EntryId | string): Promise<ArchiveEntry | undefined>;
-    extract(id: EntryId): Promise<Buffer>;
-    extract(ids: readonly EntryId[]): Promise<Buffer[]>;
-    createReadStream(id: EntryId, options?: ReadStreamOptions): Readable;
-    extractToStream(id: EntryId, destination: Writable, options?: ReadStreamOptions): Promise<void>;
+    getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
+    extract(idOrPath: EntrySelector): Promise<Buffer>;
+    extract(idsOrPaths: readonly EntrySelector[]): Promise<Buffer[]>;
+    createReadStream(idOrPath: EntrySelector, options?: ReadStreamOptions): Readable;
+    extractToStream(idOrPath: EntrySelector, destination: Writable, options?: ReadStreamOptions): Promise<void>;
     extractToFolder(destination: string, options?: ExtractToFolderOptions): Promise<void>;
-    read(id: EntryId, options: ReadOptions): Promise<Buffer>;
+    read(idOrPath: EntrySelector, options: ReadOptions): Promise<Buffer>;
     close(): Promise<void>;
     private assertOpen;
     private validateIds;
+    private resolveEntryId;
+    private resolveEntryIds;
     private toUnsignedBigInt;
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, ExtractToFolderOptions, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Readable, Writable } from 'node:stream';
 
 type EntryId = number;
+type EntrySelector = EntryId | string;
 interface ArchiveEntry {
     readonly id: EntryId;
     readonly path: string;
@@ -18,6 +19,13 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+interface ExtractToFolderProgress {
+    readonly filesExtracted: number;
+    readonly totalFiles: number;
+    readonly bytesProcessed: bigint;
+    readonly totalBytes: bigint;
+    readonly percent: number;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -25,6 +33,9 @@ interface ReadStreamOptions {
 }
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
+    readonly paths?: readonly string[];
+    readonly overwrite?: boolean;
+    readonly onProgress?: (progress: ExtractToFolderProgress) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
@@ -42,18 +53,20 @@ declare class Archive {
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
     entries(): Promise<readonly ArchiveEntry[]>;
-    getEntry(idOrPath: EntryId | string): Promise<ArchiveEntry | undefined>;
-    extract(id: EntryId): Promise<Buffer>;
-    extract(ids: readonly EntryId[]): Promise<Buffer[]>;
-    createReadStream(id: EntryId, options?: ReadStreamOptions): Readable;
-    extractToStream(id: EntryId, destination: Writable, options?: ReadStreamOptions): Promise<void>;
+    getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
+    extract(idOrPath: EntrySelector): Promise<Buffer>;
+    extract(idsOrPaths: readonly EntrySelector[]): Promise<Buffer[]>;
+    createReadStream(idOrPath: EntrySelector, options?: ReadStreamOptions): Readable;
+    extractToStream(idOrPath: EntrySelector, destination: Writable, options?: ReadStreamOptions): Promise<void>;
     extractToFolder(destination: string, options?: ExtractToFolderOptions): Promise<void>;
-    read(id: EntryId, options: ReadOptions): Promise<Buffer>;
+    read(idOrPath: EntrySelector, options: ReadOptions): Promise<Buffer>;
     close(): Promise<void>;
     private assertOpen;
     private validateIds;
+    private resolveEntryId;
+    private resolveEntryIds;
     private toUnsignedBigInt;
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, ExtractToFolderOptions, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };