7zip-native 0.0.6 → 0.0.7

package/dist/index.d.mts

@@ -19,6 +19,16 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+type ArchiveFormat = '7z' | 'zip' | 'tar' | 'wim';
+interface ArchiveCreateEntry {
+    readonly sourcePath: string;
+    readonly path: string;
+}
+interface CreateArchiveOptions {
+    readonly format?: ArchiveFormat;
+    readonly compressionLevel?: number;
+    readonly overwrite?: boolean;
+}
 interface ExtractToFolderProgress {
     readonly filesExtracted: number;
     readonly totalFiles: number;
@@ -26,6 +36,10 @@ interface ExtractToFolderProgress {
     readonly totalBytes: bigint;
     readonly percent: number;
 }
+interface ExtractedArchiveFile {
+    readonly entry: ArchiveEntry;
+    readonly outputPath: string;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -34,12 +48,14 @@ interface ReadStreamOptions {
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
     readonly paths?: readonly string[];
+    readonly concurrency?: number;
     readonly overwrite?: boolean;
     readonly onProgress?: (progress: ExtractToFolderProgress) => void;
+    readonly onExtract?: (result: ExtractedArchiveFile) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
-type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT';
+type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT' | 'ERR_ARCHIVE_CREATE';
 declare class ArchiveError extends Error {
     readonly code: ArchiveErrorCode;
     constructor(code: ArchiveErrorCode, message: string, options?: ErrorOptions);
@@ -52,6 +68,7 @@ declare class Archive {
     private constructor();
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
+    static create(outputPath: string, entries: readonly ArchiveCreateEntry[], options?: CreateArchiveOptions): Promise<void>;
     entries(): Promise<readonly ArchiveEntry[]>;
     getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
     extract(idOrPath: EntrySelector): Promise<Buffer>;
@@ -69,4 +86,4 @@ declare class Archive {
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveCreateEntry, ArchiveEntry, ArchiveErrorCode, ArchiveFormat, CreateArchiveOptions, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, ExtractedArchiveFile, OpenOptions, ReadOptions, ReadStreamOptions };

package/dist/index.d.ts

@@ -19,6 +19,16 @@ interface ReadOptions {
 interface OpenOptions {
     readonly password?: string;
 }
+type ArchiveFormat = '7z' | 'zip' | 'tar' | 'wim';
+interface ArchiveCreateEntry {
+    readonly sourcePath: string;
+    readonly path: string;
+}
+interface CreateArchiveOptions {
+    readonly format?: ArchiveFormat;
+    readonly compressionLevel?: number;
+    readonly overwrite?: boolean;
+}
 interface ExtractToFolderProgress {
     readonly filesExtracted: number;
     readonly totalFiles: number;
@@ -26,6 +36,10 @@ interface ExtractToFolderProgress {
     readonly totalBytes: bigint;
     readonly percent: number;
 }
+interface ExtractedArchiveFile {
+    readonly entry: ArchiveEntry;
+    readonly outputPath: string;
+}
 interface ReadStreamOptions {
     readonly highWaterMark?: number;
     readonly maxBytes?: number | bigint | null;
@@ -34,12 +48,14 @@ interface ReadStreamOptions {
 interface ExtractToFolderOptions {
     readonly ids?: readonly EntryId[];
     readonly paths?: readonly string[];
+    readonly concurrency?: number;
     readonly overwrite?: boolean;
     readonly onProgress?: (progress: ExtractToFolderProgress) => void;
+    readonly onExtract?: (result: ExtractedArchiveFile) => void;
     readonly maxBytes?: number | bigint | null;
     readonly signal?: AbortSignal;
 }
-type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT';
+type ArchiveErrorCode = 'ERR_ARCHIVE_CLOSED' | 'ERR_INVALID_ENTRY' | 'ERR_INVALID_RANGE' | 'ERR_RESOURCE_LIMIT' | 'ERR_ARCHIVE_OPEN' | 'ERR_ARCHIVE_PASSWORD' | 'ERR_ARCHIVE_PATH' | 'ERR_ARCHIVE_EXTRACT' | 'ERR_ARCHIVE_CREATE';
 declare class ArchiveError extends Error {
     readonly code: ArchiveErrorCode;
     constructor(code: ArchiveErrorCode, message: string, options?: ErrorOptions);
@@ -52,6 +68,7 @@ declare class Archive {
     private constructor();
     static concurrency(value?: number): number;
     static open(path: string, options?: OpenOptions): Promise<Archive>;
+    static create(outputPath: string, entries: readonly ArchiveCreateEntry[], options?: CreateArchiveOptions): Promise<void>;
     entries(): Promise<readonly ArchiveEntry[]>;
     getEntry(idOrPath: EntrySelector): Promise<ArchiveEntry | undefined>;
     extract(idOrPath: EntrySelector): Promise<Buffer>;
@@ -69,4 +86,4 @@ declare class Archive {
 }
 
 export { Archive, ArchiveError };
-export type { ArchiveEntry, ArchiveErrorCode, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, OpenOptions, ReadOptions, ReadStreamOptions };
+export type { ArchiveCreateEntry, ArchiveEntry, ArchiveErrorCode, ArchiveFormat, CreateArchiveOptions, EntryId, EntrySelector, ExtractToFolderOptions, ExtractToFolderProgress, ExtractedArchiveFile, OpenOptions, ReadOptions, ReadStreamOptions };

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { existsSync, createWriteStream } from 'node:fs';
-import { rename, rm, lstat, mkdir } from 'node:fs/promises';
+import { rename, link, rm, lstat, mkdir } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { availableParallelism } from 'node:os';
-import { dirname, resolve, join, relative, sep } from 'node:path';
-import { Transform, Readable } from 'node:stream';
+import { dirname, resolve, join, extname, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { fileURLToPath } from 'node:url';
 
@@ -73,10 +73,32 @@ function safeEntrySegments(entryPath) {
     }
     return segments;
 }
+function sanitizeOutputPath(entryPath) {
+    if (process.platform !== 'win32') {
+        return entryPath;
+    }
+    return entryPath
+        .replace(/([. ]+)([\\/]|$)/g, (_match, unsupported, separator) => '_'.repeat(unsupported.length) + separator)
+        .replace(/[<>:|?*"]/g, '_');
+}
+function assertSafeRelativeArchivePath(entryPath) {
+    const normalized = entryPath.replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(segment => segment !== '' && segment !== '.');
+    if (entryPath.includes('\0')
+        || normalized.startsWith('/')
+        || /^[a-zA-Z]:/.test(normalized)
+        || segments.length === 0
+        || segments.some(segment => segment === '..')) {
+        throw new ArchiveError('ERR_ARCHIVE_PATH', `Unsafe archive entry path: ${entryPath}`);
+    }
+}
 function makeOutputPlans(root, entries) {
     const caseInsensitivePaths = process.platform === 'win32' || process.platform === 'darwin';
     const plans = entries.map((entry) => {
-        const segments = safeEntrySegments(entry.path);
+        if (process.platform === 'win32') {
+            assertSafeRelativeArchivePath(entry.path);
+        }
+        const segments = safeEntrySegments(sanitizeOutputPath(entry.path));
         const targetPath = resolve(root, ...segments);
         const relative$1 = relative(root, targetPath);
         if (relative$1 === ''
@@ -135,6 +157,37 @@ async function assertReplaceableOutput(filePath) {
         }
     }
 }
+async function assertOutputDoesNotExist(filePath) {
+    try {
+        await lstat(filePath);
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Output archive already exists: ${filePath}`);
+    }
+    catch (error) {
+        if (error instanceof ArchiveError || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function normalizeCreateEntry(entry) {
+    if (entry === null || typeof entry !== 'object'
+        || typeof entry.sourcePath !== 'string' || entry.sourcePath.length === 0
+        || typeof entry.path !== 'string' || entry.path.length === 0) {
+        throw new TypeError('Each archive creation entry must have non-empty sourcePath and path strings');
+    }
+    const internalPath = safeEntrySegments(entry.path).join('/');
+    const sourcePath = resolve(entry.sourcePath);
+    let details;
+    try {
+        details = await lstat(sourcePath);
+    }
+    catch (cause) {
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Unable to access archive creation source: ${sourcePath}`, { cause });
+    }
+    if (details.isSymbolicLink() || !details.isFile()) {
+        throw new ArchiveError('ERR_ARCHIVE_CREATE', `Archive creation source is not a regular file: ${sourcePath}`);
+    }
+    return { sourcePath, path: internalPath };
+}
 async function ensureExtractionRoot(root) {
     try {
         const details = await lstat(root);
@@ -296,6 +349,99 @@ class Archive {
             throw new ArchiveError(/password/i.test(message) ? 'ERR_ARCHIVE_PASSWORD' : 'ERR_ARCHIVE_OPEN', message, { cause });
         }
     }
+    static async create(outputPath, entries, options = {}) {
+        if (typeof outputPath !== 'string' || outputPath.length === 0) {
+            throw new TypeError('Output archive path must be a non-empty string');
+        }
+        if (!Array.isArray(entries)) {
+            throw new TypeError('Archive creation entries must be an array');
+        }
+        if (entries.length > 1_000_000) {
+            throw new RangeError('Archive creation exceeds the 1,000,000-entry limit');
+        }
+        if (options === null || typeof options !== 'object') {
+            throw new TypeError('Archive creation options must be an object');
+        }
+        if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
+            throw new TypeError('Archive creation overwrite option must be a boolean');
+        }
+        const compressionLevel = options.compressionLevel ?? 5;
+        if (!Number.isSafeInteger(compressionLevel) || compressionLevel < 0 || compressionLevel > 9) {
+            throw new RangeError('Compression level must be an integer between 0 and 9');
+        }
+        const targetPath = resolve(outputPath);
+        let format;
+        if (options.format !== undefined) {
+            if (options.format !== '7z' && options.format !== 'zip'
+                && options.format !== 'tar' && options.format !== 'wim') {
+                throw new TypeError('Archive format must be "7z", "zip", "tar", or "wim"');
+            }
+            format = options.format;
+        }
+        else {
+            const extension = extname(targetPath).toLowerCase();
+            if (extension === '.7z') {
+                format = '7z';
+            }
+            else if (extension === '.zip' || extension === '.cbz') {
+                format = 'zip';
+            }
+            else if (extension === '.tar') {
+                format = 'tar';
+            }
+            else if (extension === '.wim') {
+                format = 'wim';
+            }
+            else {
+                throw new TypeError('Specify format as "7z", "zip", "tar", or "wim" for an unrecognized output extension');
+            }
+        }
+        if (options.compressionLevel !== undefined && format !== '7z' && format !== 'zip') {
+            throw new TypeError('compressionLevel is only supported for ZIP and 7z archives');
+        }
+        const normalizedEntries = await Promise.all(entries.map(normalizeCreateEntry));
+        const caseInsensitivePaths = process.platform === 'win32' || process.platform === 'darwin';
+        const pathKeys = normalizedEntries.map(entry => caseInsensitivePaths ? entry.path.toLowerCase() : entry.path);
+        const archivePaths = new Set(pathKeys);
+        if (archivePaths.size !== normalizedEntries.length) {
+            throw new ArchiveError('ERR_ARCHIVE_PATH', 'Archive creation paths must be unique');
+        }
+        for (const entry of normalizedEntries) {
+            const segments = entry.path.split('/');
+            for (let index = 1; index < segments.length; index++) {
+                const parent = segments.slice(0, index).join('/');
+                const parentKey = caseInsensitivePaths ? parent.toLowerCase() : parent;
+                if (archivePaths.has(parentKey)) {
+                    throw new ArchiveError('ERR_ARCHIVE_PATH', `Archive creation file path is a parent of another entry: ${parent}`);
+                }
+            }
+        }
+        if (options.overwrite) {
+            await assertReplaceableOutput(targetPath);
+        }
+        else {
+            await assertOutputDoesNotExist(targetPath);
+        }
+        const temporaryPath = join(dirname(targetPath), `.7zip-native-${randomUUID()}.tmp`);
+        try {
+            await native.create(temporaryPath, format, normalizedEntries, compressionLevel, enginePath);
+            if (options.overwrite) {
+                await assertReplaceableOutput(targetPath);
+                await rename(temporaryPath, targetPath);
+            }
+            else {
+                await link(temporaryPath, targetPath);
+                await rm(temporaryPath);
+            }
+        }
+        catch (cause) {
+            await rm(temporaryPath, { force: true });
+            if (cause instanceof ArchiveError) {
+                throw cause;
+            }
+            throw new ArchiveError('ERR_ARCHIVE_CREATE', errorMessage(cause), { cause });
+        }
+    }
     async entries() {
         this.assertOpen();
         this.entriesPromise ??= native.entries(this.handle).catch((cause) => {
@@ -379,9 +525,19 @@ class Archive {
         if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
             throw new TypeError('Folder extraction overwrite option must be a boolean');
         }
+        if (options.concurrency !== undefined
+            && (!Number.isSafeInteger(options.concurrency)
+                || options.concurrency < 1
+                || options.concurrency > 128)) {
+            throw new RangeError('Folder extraction concurrency must be an integer between 1 and 128');
+        }
         if (options.onProgress !== undefined && typeof options.onProgress !== 'function') {
             throw new TypeError('Folder extraction onProgress option must be a function');
         }
+        if (options.onExtract !== undefined && typeof options.onExtract !== 'function') {
+            throw new TypeError('Folder extraction onExtract option must be a function');
+        }
+        const concurrency = Math.min(options.concurrency ?? 1, Archive.concurrency());
         options.signal?.throwIfAborted();
         const maxBytes = normalizeMaxBytes(options.maxBytes, 'maxBytes');
         const entries = await this.entries();
@@ -451,8 +607,28 @@ class Archive {
             options.signal?.throwIfAborted();
             if (plan.isDirectory) {
                 await ensureOutputDirectoryTree(root, plan.targetPath);
-                continue;
             }
+        }
+        const filePlans = plans.filter(plan => !plan.isDirectory);
+        const controller = new AbortController();
+        const extractionSignal = controller.signal;
+        let hasFailure = false;
+        let failure;
+        let nextFileIndex = 0;
+        const stop = (error) => {
+            if (!hasFailure) {
+                hasFailure = true;
+                failure = error;
+            }
+            if (!extractionSignal.aborted) {
+                controller.abort(error);
+            }
+        };
+        const abortFromCaller = () => {
+            stop(options.signal?.reason);
+        };
+        options.signal?.addEventListener('abort', abortFromCaller, { once: true });
+        const extractFile = async (plan) => {
             await ensureOutputParents(root, plan.targetPath);
             const limit = new Transform({
                 transform(chunk, _encoding, callback) {
@@ -477,10 +653,12 @@ class Archive {
                 const temporaryPath = join(dirname(plan.targetPath), `.7zip-native-${randomUUID()}.tmp`);
                 try {
                     await pipeline(this.createReadStream(plan.entry.id, {
-                        signal: options.signal,
+                        signal: extractionSignal,
                         maxBytes: null,
-                    }), limit, createWriteStream(temporaryPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+                    }), limit, createWriteStream(temporaryPath, { flags: 'wx', mode: 0o600 }), { signal: extractionSignal });
+                    extractionSignal.throwIfAborted();
                     await assertReplaceableOutput(plan.targetPath);
+                    extractionSignal.throwIfAborted();
                     await rename(temporaryPath, plan.targetPath);
                 }
                 catch (error) {
@@ -490,12 +668,43 @@ class Archive {
             }
             else {
                 await pipeline(this.createReadStream(plan.entry.id, {
-                    signal: options.signal,
+                    signal: extractionSignal,
                     maxBytes: null,
-                }), limit, createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+                }), limit, createWriteStream(plan.targetPath, { flags: 'wx', mode: 0o600 }), { signal: extractionSignal });
             }
             filesExtracted++;
             reportProgress();
+            options.onExtract?.({ entry: plan.entry, outputPath: plan.targetPath });
+        };
+        const runWorker = async () => {
+            while (!hasFailure) {
+                if (options.signal?.aborted) {
+                    stop(options.signal.reason);
+                    return;
+                }
+                const plan = filePlans[nextFileIndex++];
+                if (!plan) {
+                    return;
+                }
+                try {
+                    await extractFile(plan);
+                }
+                catch (error) {
+                    stop(error);
+                    return;
+                }
+            }
+        };
+        try {
+            options.signal?.throwIfAborted();
+            const workers = Array.from({ length: Math.min(concurrency, filePlans.length) }, () => runWorker());
+            await Promise.all(workers);
+            if (hasFailure) {
+                throw failure;
+            }
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abortFromCaller);
         }
     }
     async read(idOrPath, options) {