zip-lib 1.2.2 → 1.3.0

package/lib/fs.js

@@ -1,16 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOutside = isOutside;
 exports.realpath = realpath;
 exports.readdirp = readdirp;
 exports.getFileEntry = getFileEntry;
 exports.ensureFolder = ensureFolder;
 exports.pathExists = pathExists;
+exports.statFolder = statFolder;
 exports.rimraf = rimraf;
 exports.isRootPath = isRootPath;
 const fsSync = require("node:fs");
 const fs = require("node:fs/promises");
 const path = require("node:path");
 const util = require("node:util");
+function isOutside(baseDir, targetPath) {
+    const absoluteBase = path.resolve(baseDir);
+    const absoluteTarget = path.resolve(targetPath);
+    const relative = path.relative(absoluteBase, absoluteTarget);
+    return relative.startsWith("..") || path.isAbsolute(relative);
+}
 async function realpath(target) {
     // fs.promises.realpath has a bug with long path on Windows.
     // https://github.com/nodejs/node/issues/51031
@@ -18,16 +26,14 @@ async function realpath(target) {
 }
 async function readdirp(folder) {
     const result = [];
-    const files = await fs.readdir(folder);
-    for (const item of files) {
-        const file = path.join(folder, item);
-        const entry = await getFileEntry(file);
+    const filePaths = (await fs.readdir(folder)).map((item) => path.join(folder, item));
+    const entries = await Promise.all(filePaths.map((filePath) => getFileEntry(filePath)));
+    for (const entry of entries) {
         if (!entry.isSymbolicLink && entry.type === "dir") {
-            const subFiles = await readdirp(file);
+            const subFiles = await readdirp(entry.path);
             if (subFiles.length > 0) {
                 result.push(...subFiles);
                 // If the folder is not empty, don't need to add the folder itself.
-                // continue and skip the code below
                 continue;
             }
         }
@@ -37,27 +43,32 @@ async function readdirp(folder) {
 }
 async function getFileEntry(target) {
     const stat = await fs.lstat(target);
-    let isSymbolicLink = false;
-    let fileType = "file";
     if (stat.isDirectory()) {
-        fileType = "dir";
-    }
-    else {
-        if (stat.isSymbolicLink()) {
-            isSymbolicLink = true;
-            // If the path is a link, we must instead use fs.stat() to find out if the
-            // link is a directory or not because lstat will always return the stat of
-            // the link which is always a file.
-            const actualStat = await fs.stat(target);
-            if (actualStat.isDirectory()) {
-                fileType = "dir";
-            }
-        }
+        return {
+            path: target,
+            isSymbolicLink: false,
+            type: "dir",
+            mtime: stat.mtime,
+            mode: stat.mode,
+        };
     }
+    if (!stat.isSymbolicLink()) {
+        return {
+            path: target,
+            isSymbolicLink: false,
+            type: "file",
+            mtime: stat.mtime,
+            mode: stat.mode,
+        };
+    }
+    // If the path is a link, we must instead use fs.stat() to find out if the
+    // link is a directory or not because lstat will always return the stat of
+    // the link which is always a file.
+    const actualStat = await fs.stat(target);
     return {
         path: target,
-        isSymbolicLink,
-        type: fileType,
+        isSymbolicLink: true,
+        type: actualStat.isDirectory() ? "dir" : "file",
         mtime: stat.mtime,
         mode: stat.mode,
     };
@@ -65,24 +76,23 @@ async function getFileEntry(target) {
 async function ensureFolder(folder) {
     // stop at root
     if (folder === path.dirname(folder)) {
-        return Promise.resolve({
+        return {
             isDirectory: true,
             isSymbolicLink: false,
-        });
+        };
     }
     try {
-        const result = await mkdir(folder);
-        return result;
+        return await mkdir(folder);
     }
     catch (error) {
         // ENOENT: a parent folder does not exist yet, continue
         // to create the parent folder and then try again.
         if (error.code === "ENOENT") {
             await ensureFolder(path.dirname(folder));
-            return mkdir(folder);
+            return await mkdir(folder);
         }
         // Any other error
-        return Promise.reject(error);
+        throw error;
     }
 }
 async function pathExists(target) {
@@ -94,10 +104,21 @@ async function pathExists(target) {
         return false;
     }
 }
+async function statFolder(folder) {
+    try {
+        return await statExistingFolder(folder);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
 async function rimraf(target) {
     if (isRootPath(target)) {
         // refuse to recursively delete root
-        return Promise.reject(new Error(`Refuse to recursively delete root, path: "${target}"`));
+        throw new Error(`Refuse to recursively delete root, path: "${target}"`);
     }
     try {
         const stat = await fs.lstat(target);
@@ -108,17 +129,15 @@ async function rimraf(target) {
             await Promise.all(children.map((child) => rimraf(path.join(target, child))));
             // Folder
             await fs.rmdir(target);
+            return;
         }
         // Single file delete
-        else {
-            // chmod as needed to allow for unlink
-            const mode = stat.mode;
-            if (!(mode & 128)) {
-                // 128 === 0200
-                await fs.chmod(target, mode | 128);
-            }
-            return fs.unlink(target);
+        const mode = stat.mode;
+        if (!(mode & 128)) {
+            // 128 === 0200
+            await fs.chmod(target, mode | 128);
         }
+        await fs.unlink(target);
     }
     catch (error) {
         if (error.code !== "ENOENT") {
@@ -137,39 +156,40 @@ async function mkdir(folder) {
     catch (error) {
         // ENOENT: a parent folder does not exist yet or folder name is invalid.
         if (error.code === "ENOENT") {
-            return Promise.reject(error);
+            throw error;
         }
         // Any other error: check if folder exists and
         // return normally in that case if its a folder
         try {
-            const fileStat = await fs.lstat(folder);
-            if (fileStat.isSymbolicLink()) {
-                const realFilePath = await realpath(folder);
-                const realFileStat = await fs.lstat(realFilePath);
-                if (!realFileStat.isDirectory()) {
-                    return Promise.reject(new Error(`"${folder}" exists and is not a directory.`));
-                }
-                return {
-                    isDirectory: false,
-                    isSymbolicLink: true,
-                    realpath: realFilePath,
-                };
-            }
-            else {
-                if (!fileStat.isDirectory()) {
-                    return Promise.reject(new Error(`"${folder}" exists and is not a directory.`));
-                }
-                return {
-                    isDirectory: true,
-                    isSymbolicLink: false,
-                };
-            }
+            return await statExistingFolder(folder);
         }
         catch (_statError) {
             throw error; // rethrow original error
         }
     }
 }
+async function statExistingFolder(folder) {
+    const fileStat = await fs.lstat(folder);
+    if (!fileStat.isSymbolicLink()) {
+        if (!fileStat.isDirectory()) {
+            throw new Error(`"${folder}" exists and is not a directory.`);
+        }
+        return {
+            isDirectory: true,
+            isSymbolicLink: false,
+        };
+    }
+    const realFilePath = await realpath(folder);
+    const realFileStat = await fs.lstat(realFilePath);
+    if (!realFileStat.isDirectory()) {
+        throw new Error(`"${folder}" exists and is not a directory.`);
+    }
+    return {
+        isDirectory: false,
+        isSymbolicLink: true,
+        realpath: realFilePath,
+    };
+}
 // "A"
 const charA = 65;
 // "Z"

package/lib/index.d.ts

@@ -3,19 +3,38 @@ import { type IZipOptions } from "./zip";
 export * from "./unzip";
 export * from "./zip";
 /**
- * Compress a single file to zip.
+ * Compress a single file to a buffer.
+ * @param file
+ * @param options
+ */
+export declare function archiveFile(file: string, options?: IZipOptions): Promise<Buffer>;
+/**
+ * Compress a single file to the specified zip file path.
  * @param file
  * @param zipFile the zip file path.
  * @param options
  */
 export declare function archiveFile(file: string, zipFile: string, options?: IZipOptions): Promise<void>;
 /**
- * Compress all the contents of the specified folder to zip.
+ * Compress all the contents of the specified folder to a buffer.
+ * @param folder
+ * @param options
+ */
+export declare function archiveFolder(folder: string, options?: IZipOptions): Promise<Buffer>;
+/**
+ * Compress all the contents of the specified folder to the specified zip file path.
  * @param folder
  * @param zipFile the zip file path.
  * @param options
  */
 export declare function archiveFolder(folder: string, zipFile: string, options?: IZipOptions): Promise<void>;
+/**
+ * Extract the zip buffer to the specified location.
+ * @param zipBuffer
+ * @param targetFolder
+ * @param options
+ */
+export declare function extract(zipBuffer: Buffer, targetFolder: string, options?: IExtractOptions): Promise<void>;
 /**
  * Extract the zip file to the specified location.
  * @param zipFile

package/lib/index.js

@@ -21,35 +21,38 @@ const unzip_1 = require("./unzip");
 const zip_1 = require("./zip");
 __exportStar(require("./unzip"), exports);
 __exportStar(require("./zip"), exports);
-/**
- * Compress a single file to zip.
- * @param file
- * @param zipFile the zip file path.
- * @param options
- */
 function archiveFile(file, zipFile, options) {
-    const zip = new zip_1.Zip(options);
+    let optionsParameter;
+    if (typeof zipFile === "string") {
+        optionsParameter = options;
+    }
+    else if (typeof zipFile === "object") {
+        optionsParameter = zipFile;
+    }
+    const zip = new zip_1.Zip(optionsParameter);
     zip.addFile(file);
-    return zip.archive(zipFile);
+    if (typeof zipFile === "string") {
+        return zip.archive(zipFile);
+    }
+    return zip.archive();
 }
-/**
- * Compress all the contents of the specified folder to zip.
- * @param folder
- * @param zipFile the zip file path.
- * @param options
- */
 function archiveFolder(folder, zipFile, options) {
-    const zip = new zip_1.Zip(options);
+    let optionsParameter;
+    if (typeof zipFile === "string") {
+        optionsParameter = options;
+    }
+    else if (typeof zipFile === "object") {
+        optionsParameter = zipFile;
+    }
+    const zip = new zip_1.Zip(optionsParameter);
     zip.addFolder(folder);
-    return zip.archive(zipFile);
+    if (typeof zipFile === "string") {
+        return zip.archive(zipFile);
+    }
+    return zip.archive();
 }
-/**
- * Extract the zip file to the specified location.
- * @param zipFile
- * @param targetFolder
- * @param options
- */
-function extract(zipFile, targetFolder, options) {
+function extract(zipFileOrBuffer, targetFolder, options) {
     const unzip = new unzip_1.Unzip(options);
-    return unzip.extract(zipFile, targetFolder);
+    // biome-ignore lint/suspicious/noExplicitAny: <>
+    return unzip.extract(zipFileOrBuffer, targetFolder);
 }

package/lib/unzip.d.ts

@@ -1,23 +1,35 @@
 import { Cancelable } from "./cancelable";
 export interface IExtractOptions {
     /**
-     * If it is `true`, the target directory will be deleted before extract.
+     * If it is `true`, the target directory will be deleted before extraction.
      * The default value is `false`.
      */
     overwrite?: boolean;
     /**
-     * Extract symbolic links as files on Windows. This value is only available on Windows and ignored on other platforms.
+     * Extracts symbolic links as files on Windows. This value is only available on Windows and is ignored on other platforms.
      * The default value is `true`.
      *
      * If `true`, the symlink in the zip will be extracted as a normal file on Windows.
      *
-     * If `false`, the symlink in the zip will be extracted as a symlink correctly on Windows, but an `EPERM` error will be thrown under non-administrators.
+     * If `false`, the library will try to extract symlinks as real symlinks on Windows.
+     * This may fail with an `EPERM` error when the current process is not allowed to create symlinks.
      *
-     * > ⚠**WARNING:** On Windows, the default security policy allows only administrators to create symbolic links.
-     * If you set `symlinkAsFileOnWindows` to `false` and the zip contains symlink,
-     * be sure to run the code under the administrator, otherwise an `EPERM` error will be thrown.
+     * > ⚠**WARNING:** On Windows, creating symbolic links may require administrator privileges,
+     * depending on system policy. If Windows Developer Mode is enabled, non-administrator
+     * processes can usually create symlinks as well.
      */
     symlinkAsFileOnWindows?: boolean;
+    /**
+     * Controls the creation phase of symlinks.
+     *
+     * `true`: Refuses to create any symlink whose target is outside the extraction root.
+     *
+     * `false`: Allows creating external symlinks. **Note:** Subsequent write operations to these
+     * links will still be intercepted by the separate AFWRITE security layer.
+     *
+     * The default value is `false`.
+     */
+    safeSymlinksOnly?: boolean;
     /**
      * Called before an item is extracted.
      * @param event
@@ -25,7 +37,7 @@ export interface IExtractOptions {
     onEntry?: (event: IEntryEvent) => void;
 }
 /**
- * The IEntryEvent interface represents an event that an entry is about to be extracted.
+ * Represents an event fired before an entry is extracted.
  */
 export interface IEntryEvent {
     /**
@@ -37,7 +49,7 @@ export interface IEntryEvent {
      */
     readonly entryCount: number;
     /**
-     * Prevent extracting current entry.
+     * Prevents the current entry from being extracted.
      */
     preventDefault(): void;
 }
@@ -52,15 +64,25 @@ export declare class Unzip extends Cancelable {
     constructor(options?: IExtractOptions | undefined);
     private zipFile;
     private token;
+    /**
+     * Extract the zip buffer to the specified location.
+     * @param zipBuffer
+     * @param targetFolder
+     */
+    extract(zipBuffer: Buffer, targetFolder: string): Promise<void>;
     /**
      * Extract the zip file to the specified location.
      * @param zipFile
      * @param targetFolder
-     * @param options
      */
     extract(zipFile: string, targetFolder: string): Promise<void>;
+    private prepareExtraction;
+    private processEntries;
+    private readNextEntry;
+    private createPromiseSettler;
+    private handleZipEntry;
     /**
-     * Cancel decompression.
+     * Cancel extraction.
      * If the cancel method is called after the extract is complete, nothing will happen.
      */
     cancel(): void;
@@ -70,6 +92,7 @@ export declare class Unzip extends Cancelable {
     private openZipFileStream;
     private extractEntry;
     private writeEntryToFile;
+    private readStreamContent;
     private modeFromEntry;
     private createSymlink;
     private isOverwrite;