zip-lib 1.2.3 → 1.3.1

package/README.md

@@ -1,5 +1,5 @@
 # zip-lib
-zip and unzip library for node.
+A zip and unzip library for Node.js with promise-based APIs, support for compressing to `Buffer` or extracting from `Buffer`, and advanced features like entry filtering, cancellation, and symlink-aware handling.
 
 [![npm Package](https://img.shields.io/npm/v/zip-lib.svg)](https://www.npmjs.org/package/zip-lib)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/fpsqdb/zip-lib/blob/master/LICENSE)
@@ -34,76 +34,121 @@ npm install zip-lib
     - Class: [Unzip](#class-unzip)
     - Options: [IZipOptions](#izipoptions)
     - Options: [IExtractOptions](#iextractoptions)
+    - Event: [IEntryEvent](#event-ientryevent)
 
 ## Zip
 You can use **zip-lib** to compress files or folders.
 
 ### Zip single file
 
-```js
-const zl = require("zip-lib");
-
-zl.archiveFile("path/to/file.txt", "path/to/target.zip").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function zipToFile() {
+	try {
+		await zl.archiveFile("path/to/file.txt", "path/to/target.zip");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
+
+async function zipToBuffer() {
+	try {
+		const buffer = await zl.archiveFile("path/to/file.txt");
+		console.log("done", buffer.byteLength);
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ### Zip single folder
 
-```js
-const zl = require("zip-lib");
-
-zl.archiveFolder("path/to/folder", "path/to/target.zip").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function zipToFile() {
+	try {
+		await zl.archiveFolder("path/to/folder", "path/to/target.zip");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
+
+async function zipToBuffer() {
+	try {
+		const buffer = await zl.archiveFolder("path/to/folder");
+		console.log("done", buffer.byteLength);
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ## Unzip
 
-```js
-const zl = require("zip-lib");
-
-zl.extract("path/to/target.zip", "path/to/target").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function unzipFromFile() {
+	try {
+		await zl.extract("path/to/target.zip", "path/to/target");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
+
+async function unzipFromBuffer(zipBuffer: Buffer) {
+	try {
+		await zl.extract(zipBuffer, "path/to/target");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ## Advanced usage
 
-### Sets the compression level
-
-```js
-const zl = require("zip-lib");
-
-zl.archiveFolder("path/to/folder", "path/to/target.zip", { compressionLevel: 9 }).then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+### Set the compression level
+
+```ts
+import * as zl from "zip-lib";
+
+async function zipToFile() {
+	try {
+		await zl.archiveFolder("path/to/folder", "path/to/target.zip", {
+			compressionLevel: 9,
+		});
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ### Zip multiple files and folders
 
-```js
-const zl = require("zip-lib");
-
-const zip = new zl.Zip();
-// Adds a file from the file system
-zip.addFile("path/to/file.txt");
-// Adds a folder from the file system, putting its contents at the root of archive
-zip.addFolder("path/to/folder");
-// Generate zip file.
-zip.archive("path/to/target.zip").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function zipToFile() {
+	try {
+		const zip = new zl.Zip();
+		// Adds a file from the file system
+		zip.addFile("path/to/file.txt");
+		// Adds a folder from the file system, putting its contents at the root of the archive
+		zip.addFolder("path/to/folder");
+		// Generate the zip file.
+		await zip.archive("path/to/target.zip");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 The `path/to/folder` directory is as follows:
@@ -117,7 +162,7 @@ path/to/folder
 └── file_in_root.ext
 ```
 
-And the generated `path/to/target.zip` archive file directory will be as follows:
+And the contents of the generated `path/to/target.zip` archive will be as follows:
 
 ```
 path/to/target.zip
@@ -131,21 +176,24 @@ path/to/target.zip
 
 ### Zip with metadata
 
-```js
-const zl = require("zip-lib");
-
-const zip = new zl.Zip();
-// Adds a file from the file system
-zip.addFile("path/to/file.txt", "renamedFile.txt");
-zip.addFile("path/to/file2.txt", "folder/file.txt");
-// Adds a folder from the file system, and naming it `new folder` within the archive
-zip.addFolder("path/to/folder", "new folder");
-// Generate zip file.
-zip.archive("path/to/target.zip").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function zipToFile() {
+	try {
+		const zip = new zl.Zip();
+		// Adds a file from the file system
+		zip.addFile("path/to/file.txt", "renamedFile.txt");
+		zip.addFile("path/to/file2.txt", "folder/file.txt");
+		// Adds a folder from the file system and names it `new folder` within the archive
+		zip.addFolder("path/to/folder", "new folder");
+		// Generate the zip file.
+		zip.archive("path/to/target.zip");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 The `path/to/folder` directory is as follows:
@@ -159,7 +207,7 @@ path/to/folder
 └── file_in_root.ext
 ```
 
-And the generated `path/to/target.zip` archive file directory will be as follows:
+And the contents of the generated `path/to/target.zip` archive will be as follows:
 
 ```
 path/to/target.zip
@@ -167,7 +215,7 @@ path/to/target.zip
 ├── renamedFile.txt
 ├── folder
 │   ├── file.txt
-│── new folder
+├── new folder
     ├── dir1
     │   ├── file.ext
     ├── dir2
@@ -175,208 +223,251 @@ path/to/target.zip
 ```
 
 ### Unzip with entry callback
-Using `onEntry` callback we can know the current progress of extracting and control the extraction operation. See [IExtractOptions](#iextractoptions).
-
-```js
-const zl = require("zip-lib");
-
-const unzip = new zl.Unzip({
-    // Called before an item is extracted.
-    onEntry: function (event) {
-        console.log(event.entryCount, event.entryName);
-    }
-})
-unzip.extract("path/to/target.zip", "path/to/target").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+Using the `onEntry` callback, we can track extraction progress and control the extraction process. See [IExtractOptions](#iextractoptions).
+
+```ts
+import * as zl from "zip-lib";
+
+async function unzipFromFile() {
+	try {
+		const unzip = new zl.Unzip({
+			// Called before an item is extracted.
+			onEntry: (event) => {
+				console.log(event.entryCount, event.entryName);
+			},
+		});
+		await unzip.extract("path/to/target.zip", "path/to/target");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ### Unzip and exclude specified entries
 The following code shows how to exclude the `__MACOSX` folder in the zip file when extracting. See [IExtractOptions](#iextractoptions).
 
-```js
-const zl = require("zip-lib");
-
-const unzip = new zl.Unzip({
-    // Called before an item is extracted.
-    onEntry: function (event) {
-        if (/^__MACOSX\//.test(event.entryName)) {
-            // entry name starts with __MACOSX/
-            event.preventDefault();
-        }
-    }
-})
-unzip.extract("path/to/target.zip", "path/to/target").then(function () {
-    console.log("done");
-}, function (err) {
-    console.log(err);
-});
+```ts
+import * as zl from "zip-lib";
+
+async function unzipFromFile() {
+	try {
+		const unzip = new zl.Unzip({
+			// Called before an item is extracted.
+			onEntry: (event) => {
+				if (/^__MACOSX\//.test(event.entryName)) {
+					// entry name starts with __MACOSX/
+					event.preventDefault();
+				}
+			},
+		});
+		await unzip.extract("path/to/target.zip", "path/to/target");
+		console.log("done");
+	} catch (error) {
+		console.error(error);
+	}
+}
 ```
 
 ### Cancel zip
 If the `cancel` method is called after the archive is complete, nothing will happen.
 
-```js
-const zl = require("zip-lib");
+```ts
+import * as zl from "zip-lib";
 
 const zip = new zl.Zip();
-zip.addFile("path/to/file.txt");
-zip.archive("path/to/target.zip").then(function () {
-    console.log("done");
-}, function (err) {
-    if (err.name === "Canceled") {
-        console.log("cancel");
-    } else {
-        console.log(err);
-    }
-});
-
-// Cancel zip
-zip.cancel();
+async function zipToFile() {
+	try {
+		zip.addFile("path/to/file.txt");
+		await zip.archive("path/to/target.zip");
+		console.log("done");
+	} catch (error) {
+		if (error instanceof Error && error.name === "Canceled") {
+			console.log("cancel");
+		} else {
+			console.log(error);
+		}
+	}
+}
+
+function cancel() {
+	zip.cancel();
+}
 ```
 
 ### Cancel unzip
 If the `cancel` method is called after the extract is complete, nothing will happen.
 
-```js
-const zl = require("zip-lib");
+```ts
+import * as zl from "zip-lib";
 
 const unzip = new zl.Unzip();
-unzip.extract("path/to/target.zip", "path/to/target").then(function () {
-    console.log("done");
-}, function (err) {
-    if (err.name === "Canceled") {
-        console.log("cancel");
-    } else {
-        console.log(err);
-    }
-});
-
-// cancel
-unzip.cancel();
+async function unzipFromFile() {
+	try {
+		await unzip.extract("path/to/target.zip", "path/to/target");
+		console.log("done");
+	} catch (error) {
+		if (error instanceof Error && error.name === "Canceled") {
+			console.log("cancel");
+		} else {
+			console.log(error);
+		}
+	}
+}
+
+function cancel() {
+	unzip.cancel();
+}
 ```
 
 ## API
 
+Choose the API based on how much control you need:
+
+- Use [`archiveFile`](#archivefile), [`archiveFolder`](#archivefolder), and [`extract`](#extract) for simple one-shot operations.
+- Use [`Zip`](#class-zip) when you need to add multiple files or folders, rename entries, or cancel compression.
+- Use [`Unzip`](#class-unzip) when you need to filter entries with `onEntry` or cancel extraction.
+
 ### Method: archiveFile <a id="archivefile"></a>
 
-**archiveFile(file, zipFile, [options])**
+Compress a single file.
 
-Compress a single file to zip.
+```ts
+archiveFile(file: string, options?: IZipOptions): Promise<Buffer>
+archiveFile(file: string, zipFile: string, options?: IZipOptions): Promise<void>
+```
 
-- `file`: String
-- `zipFile`: String
-- `options?`: [IZipOptions](#izipoptions) (optional)
+- `file`: Path to the source file.
+- `zipFile`: Optional output zip file path.
+- `options`: Optional [IZipOptions](#izipoptions).
 
-Returns: `Promise<viod>`
+If `zipFile` is provided, the archive is written to disk and the method returns `Promise<void>`. Otherwise it returns the generated zip as a `Buffer`.
 
 ### Method: archiveFolder <a id="archivefolder"></a>
 
-**archiveFolder(folder, zipFile, [options])**
+Compress all contents of a folder.
 
-Compress all the contents of the specified folder to zip.
+```ts
+archiveFolder(folder: string, options?: IZipOptions): Promise<Buffer>
+archiveFolder(folder: string, zipFile: string, options?: IZipOptions): Promise<void>
+```
 
-- `folder`: String
-- `zipFile`: String
-- `options?`: [IZipOptions](#izipoptions) (optional)
+- `folder`: Path to the source folder.
+- `zipFile`: Optional output zip file path.
+- `options`: Optional [IZipOptions](#izipoptions).
 
-Returns: `Promise<void>`
+If `zipFile` is provided, the archive is written to disk and the method returns `Promise<void>`. Otherwise it returns the generated zip as a `Buffer`.
 
 ### Method: extract <a id="extract"></a>
 
-**extract(zipFile, targetFolder, [options])**
-
-Extract the zip file to the specified location.
-
-- `zipFile`: String
-- `targetFolder`: String
-- `options?`: [IExtractOptions](#iextractoptions) (optional)
-
-Returns: `Promise<void>`
-
-### Class: Zip<a id="class-zip"></a>
-Compress files or folders to a zip file.
-
-**Constructor: new Zip([options])**
+Extract a zip file or zip buffer to a target folder.
 
-- `options?`: [IZipOptions](#izipoptions)
-
-**Method: addFile(file, [metadataPath])**
-
-Adds a file from the file system at realPath into the zipfile as metadataPath.
-
-- `file`: String
-- `metadataPath?`: String (optional) - Typically metadataPath would be calculated as path.relative(root, realPath). A valid metadataPath must not start with `/` or `/[A-Za-z]:\//`, and must not contain `..`.
-
-Returns: `void`
+```ts
+extract(zipFile: string, targetFolder: string, options?: IExtractOptions): Promise<void>
+extract(zipBuffer: Buffer, targetFolder: string, options?: IExtractOptions): Promise<void>
+```
 
-**Method: addFolder(folder, [metadataPath])**
+- `zipFile`: Path to a zip file on disk.
+- `zipBuffer`: A zip archive in memory.
+- `targetFolder`: Destination folder.
+- `options`: Optional [IExtractOptions](#iextractoptions).
 
-Adds a folder from the file system at realPath into the zipfile as metadataPath.
+### Class: Zip <a id="class-zip"></a>
 
-- `folder`: String
-- `metadataPath?`: String (optional) - Typically metadataPath would be calculated as path.relative(root, realPath). A valid metadataPath must not start with `/` or `/[A-Za-z]:\//`, and must not contain `..`.
+Build an archive incrementally when the top-level helpers are not enough.
 
-Returns: `void`
+**Constructor**
 
-**Method: archive(zipFile)**
+```ts
+new Zip(options?: IZipOptions)
+```
 
-Generate zip file.
+- `options`: Optional [IZipOptions](#izipoptions).
 
-- `zipFile`: String
+**Methods**
 
-Returns: `Promise<viod>`
+```ts
+addFile(file: string, metadataPath?: string): void
+addFolder(folder: string, metadataPath?: string): void
+archive(): Promise<Buffer>
+archive(zipFile: string): Promise<void>
+cancel(): void
+```
 
-**Method: cancel()**
+- `addFile`: Adds one file to the archive.
+- `addFolder`: Adds one folder to the archive.
+- `metadataPath`: Optional path stored inside the zip. A valid `metadataPath` must not start with `/` or `/[A-Za-z]:\//`, and must not contain `..`.
+- `archive()`: Returns the zip as a `Buffer`.
+- `archive(zipFile)`: Writes the zip directly to disk.
+- `cancel()`: Cancels compression. Calling it after completion has no effect.
 
-Cancel compression. If the `cancel` method is called after the archive is complete, nothing will happen.
+Use `metadataPath` to rename files or folders inside the archive. It is typically computed with `path.relative(root, realPath)`.
 
-Returns: `void`
+### Class: Unzip <a id="class-unzip"></a>
 
-### Class: Unzip<a id="class-unzip"></a>
-Extract the zip file.
+Extract with entry filtering and cancellation support.
 
-**Constructor: new Unzip([options])**
+**Constructor**
 
-- `options?`: [IZipOptions](#izipoptions) (optional)
+```ts
+new Unzip(options?: IExtractOptions)
+```
 
-**Method: extract(zipFile, targetFolder)**
+- `options`: Optional [IExtractOptions](#iextractoptions).
 
-Extract the zip file to the specified location.
+**Methods**
 
-- `zipFile`: String
-- `targetFolder`: String
+```ts
+extract(zipFile: string, targetFolder: string): Promise<void>
+extract(zipBuffer: Buffer, targetFolder: string): Promise<void>
+cancel(): void
+```
 
-Returns: `Promise<void>`
+- `extract(...)`: Extracts from a zip file path or a `Buffer`.
+- `cancel()`: Cancels extraction. Calling it after completion has no effect.
 
-**Method: cancel()**
+### Options: IZipOptions <a id="izipoptions"></a>
 
-If the `cancel` method is called after the extract is complete, nothing will happen.
+```ts
+interface IZipOptions {
+  followSymlinks?: boolean;
+  compressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+}
+```
 
-Returns: `void`
+- `followSymlinks`: Default `false`. If `true`, adds the target of a symbolic link. If `false`, adds the symbolic link itself.
+- `compressionLevel`: Default `6`. Use `0` to store file data without compression, or `1`-`9` to deflate file data.
 
-### Options: IZipOptions <a id="izipoptions"></a>
+### Options: IExtractOptions <a id="iextractoptions"></a>
 
-Object
-- `followSymlinks?`: Boolean (optional) - Indicates how to handle when the given path is a symbolic link. The default value is `false`.<br>`true`: add the target of the symbolic link to the zip.<br>`false`: add symbolic link itself to the zip.
-- `compressionLevel?`: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 - Sets the compression level. The default value is `6`.<br>`0`: the file data will be stored.<br>`1-9`: the file data will be deflated.
+```ts
+interface IExtractOptions {
+  overwrite?: boolean;
+  safeSymlinksOnly?: boolean;
+  symlinkAsFileOnWindows?: boolean;
+  onEntry?: (event: IEntryEvent) => void;
+}
+```
 
-### Options: IExtractOptions <a id="iextractoptions"></a>
+- `overwrite`: Default `false`. If `true`, deletes the target directory before extraction.
+- `safeSymlinksOnly`: Default `false`. If `true`, refuses to create symlinks whose targets are outside the extraction root.
+- `symlinkAsFileOnWindows`: Default `true`. On Windows, if `true`, symbolic links are extracted as regular files. If `false`, the library tries to create real symbolic links instead. This may fail with `EPERM` when the current process is not allowed to create symlinks. Keep the default for better compatibility; set this to `false` only if you want to preserve symlinks as symlinks.
+- `onEntry`: Called before an entry is extracted. Use it to inspect or skip entries.
 
-Object
-- `overwrite?`: Boolean (optional) - If it is true, the target directory will be deleted before extract. The default value is `false`.
-- `safeSymlinksOnly`: Boolean (optional) - Controls the creation phase of symlinks. The default value is `false`.<br>`true`: Refuses to create any symlink whose target is outside the extraction root.<br>`false`: Allows creating external symlinks. **Note:** Subsequent write operations to these links will still be intercepted by the separate AFWRITE security layer.
-- `symlinkAsFileOnWindows?`: Boolean (optional) - Extract symbolic links as files on Windows. This value is only available on Windows and ignored on other platforms. The default value is `true`.<br>If `true`, the symlink in the zip will be extracted as a normal file on Windows.<br>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.
+> 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. If `symlinkAsFileOnWindows` is `false` and the current process is not allowed to create symlinks, extraction may fail with `EPERM`.
 
-    > ⚠**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.
+### Event: IEntryEvent
 
-- `onEntry?`: Function (optional) - Called before an item is extracted.<br>Arguments:
-    - `event`: Object - Represents an event that an entry is about to be extracted.
-        - `entryName`: String (readonly) - Entry name.
-        - `entryCount`: Number (readonly) - Total number of entries.
-        - `preventDefault()`: Function - Prevent extracting current entry. This method can be used to prevent extraction of the current item. By calling this method we can control which items can be extracted.
+```ts
+interface IEntryEvent {
+  readonly entryName: string;
+  readonly entryCount: number;
+  preventDefault(): void;
+}
+```
 
+- `entryName`: The current entry name.
+- `entryCount`: The total number of entries in the archive.
+- `preventDefault()`: Skips the current entry.
 # License
-Licensed under the [MIT](https://github.com/fpsqdb/zip-lib/blob/master/LICENSE) license.
+Licensed under the [MIT](https://github.com/fpsqdb/zip-lib/blob/master/LICENSE) license.

package/lib/fs.d.ts

@@ -20,5 +20,6 @@ export declare function readdirp(folder: string): Promise<FileEntry[]>;
 export declare function getFileEntry(target: string): Promise<FileEntry>;
 export declare function ensureFolder(folder: string): Promise<FolderStat>;
 export declare function pathExists(target: string): Promise<boolean>;
+export declare function statFolder(folder: string): Promise<FolderStat | undefined>;
 export declare function rimraf(target: string): Promise<void>;
 export declare function isRootPath(target: string): boolean;