cross-7zip
Version:
Cross-platform 7-Zip for Node.js
383 lines (377 loc) • 11.4 kB
TypeScript
type UnzipOptions = {
/**
* Specifies the path to the zipped file.
*/
archive: string;
/**
* Specifies the path to the output directory.
*/
destination: string;
/**
* Password for the archive.
*/
password?: string;
};
type ZipOptions = {
/**
* Specifies the path to the output zipped file.
*/
destination: string;
/**
* Specifies the paths to the files to add to the zipped file.
*/
files: string[];
/**
* Compression level, where 1 is the fastest and 9 is the best compression.
*/
level?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
/**
* Password for the archive.
*/
password?: string;
/**
* Overwrites the existing ZIP file instead of updating it.
*/
overwrite?: boolean;
};
/**
* A wrapper class for extracting files from a 7-Zip archive using the
* command-line tool.
*
* @example
* ```ts
* import { SevenUnzip } from 'cross-7zip';
*
* function extractArchiveSync(): void {
* try {
* const sevenUnzip = new SevenUnzip({
* archive: 'example.7z',
* destination: 'outputFolder',
* password: 'secure 123'
* });
*
* sevenUnzip.runSync();
* console.log('Extraction completed successfully.');
* } catch (error) {
* console.error('An error occurred during extraction:', error);
* }
* }
*
* async function extractArchive(): Promise<void> {
* try {
* const sevenUnzip = new SevenUnzip()
* .setArchive('example.7z')
* .setDestination('outputFolder')
* .setPassword('secure 123');
*
* await sevenUnzip.run();
* console.log('Extraction completed successfully.');
* } catch (error) {
* console.error('An error occurred during extraction:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzip.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzip.test.ts)
* or
* [sevenZipUnzipSync.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzipSync.test.ts).
*/
declare class SevenUnzip {
private readonly _options;
/**
* Gets the path to the 7-Zip executable.
*/
get command(): string | undefined;
/**
* Generates the arguments for the 7-Zip command-line execution.
*/
get args(): string[];
/**
* Creates an instance of `SevenZip` with optional extraction settings.
*
* @param options Partial extraction options.
*/
constructor(options?: Partial<UnzipOptions>);
/**
* Sets the archive file to extract.
*
* @param archive The path to the archive file.
* @returns The `SevenUnzip` instance for method chaining.
*/
setArchive(archive: string): this;
/**
* Sets the destination path for the extraction.
*
* @param destination The path to the output folder.
* @returns The `SevenUnzip` instance for method chaining.
*/
setDestination(destination: string): this;
/**
* Sets a password for extracting encrypted archives.
*
* @param password The password string.
* @returns The `SevenUnzip` instance for method chaining.
*/
setPassword(password: string): this;
/**
* Returns a string representation of the 7-Zip command with its arguments.
*
* This method constructs the full command-line string that would be executed,
* ensuring that each argument is properly quoted to handle paths with spaces.
*
* @returns The formatted command-line string.
*/
toString(): string;
/**
* Runs the extraction process **asynchronously**.
*
* @throws {Error} If the 7-Zip executable is not found.
*/
run(): Promise<void>;
/**
* Runs the extraction process **synchronously**.
*
* @throws {Error} If the 7-Zip executable is not found.
*/
runSync(): void;
}
/**
* A wrapper class for creating 7-Zip archives using the command-line tool.
*
* @example
* ```ts
* import { SevenZip } from 'cross-7zip';
*
* function createArchiveSync(): void {
* try {
* const zip = new SevenZip({
* destination: 'example.7z',
* files: ['document.txt', 'image.png', 'folder'],
* level: 5,
* passwrod: 'secure 123',
* overwrite: true
* });
*
* zip.runSync();
* console.log('Archive created successfully.');
* } catch (error) {
* console.error('An error occurred during compression:', error);
* }
* }
*
* async function createArchive(): Promise<void> {
* try {
* const zip = new SevenZip()
* .setDestination('example.7z')
* .setFiles(['document.txt', 'image.png', 'folder'])
* .setLevel(5)
* .setPassword('secure 123')
* .setOverwrite();
*
* await zip.run();
* console.log('Archive created successfully.');
* } catch (error) {
* console.error('An error occurred during compression:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzip.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzip.test.ts)
* or
* [sevenZipUnzipSync.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzipSync.test.ts).
*/
declare class SevenZip {
private readonly _options;
/**
* Gets the path to the 7-Zip executable.
*/
get command(): string | undefined;
/**
* Generates the arguments for the 7-Zip command-line execution.
*/
get args(): string[];
/**
* Creates an instance of `SevenZip` with optional compression settings.
*
* @param options Partial zip options.
*/
constructor(options?: Partial<ZipOptions>);
/**
* Sets the destination path for the output `.7z` file.
*
* @param destination The output file path.
* @returns The `SevenZip` instance for method chaining.
*/
setDestination(destination: string): this;
/**
* Sets the list of files and folders to be compressed.
*
* @param files An array of file or directory paths.
* @returns The `SevenZip` instance for method chaining.
*/
setFiles(files: string[]): this;
/**
* Sets the compression level (1-9).
*
* @param level Compression level, where 1 is the fastest and 9 is the best compression.
* @returns The `SevenZip` instance for method chaining.
*/
setLevel(level: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): this;
/**
* Enables overwrite mode, allowing an existing archive to be replaced.
*
* @returns The `SevenZip` instance for method chaining.
*/
setOverwrite(overwrite?: boolean): this;
/**
* Sets a password for the archive.
*
* @param password The encryption password.
* @returns The `SevenZip` instance for method chaining.
*/
setPassword(password: string): this;
/**
* Returns a string representation of the 7-Zip command with its arguments.
*
* This method constructs the full command-line string that would be executed,
* ensuring that each argument is properly quoted to handle paths with spaces.
*
* @returns The formatted command-line string.
*/
toString(): string;
/**
* Runs the compression process **asynchronously**.
*
* @throws {Error} If the 7-Zip executable is not found.
*/
run(): Promise<void>;
/**
* Runs the compression process **synchronously**.
*
* @throws {Error} If the 7-Zip executable is not found.
*/
runSync(): void;
}
/**
* Compresses multiple files into a zipped file **asynchronously**.
*
* @param options An object containing options for the compression process.
*
* @throws {Error} Will throw an error if the 7-Zip executable is not found.
*
* @example
* ```ts
* import { ZipOptions, sevenZip } from 'cross-7zip';
*
* async function createArchive(): Promise<void> {
* try {
* const zipOptions: ZipOptions = {
* destination: 'example.7z',
* files: ['document.txt', 'image.png', 'folder']
* };
*
* await sevenZip(zipOptions);
* console.log('Archive created successfully.');
* } catch (error) {
* console.error('An error occurred during compression:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzip.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzip.test.ts).
*/
declare function sevenZip(options: ZipOptions): Promise<void>;
/**
* Extracts files from a specified zipped file **asynchronously**.
*
* @param options An object containing options for the extraction process.
*
* @throws {Error} Will throw an error if the 7-Zip executable is not found.
*
* @example
* ```ts
* import { UnzipOptions, sevenUnzip } from 'cross-7zip';
*
* async function extractFiles(): Promise<void> {
* try {
* const unzipOptions: UnzipOptions = {
* archive: 'example.7z',
* destination: './output'
* };
*
* await sevenUnzip(unzipOptions);
* console.log('Extraction completed successfully.');
* } catch (error) {
* console.error('An error occurred during extraction:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzip.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzip.test.ts).
*/
declare function sevenUnzip(options: UnzipOptions): Promise<void>;
/**
* Compresses multiple files into a zipped file **synchronously**.
*
* @param options An object containing options for the compression process.
*
* @throws {Error} Will throw an error if the 7-Zip executable is not found.
*
* @example
* ```ts
* import { ZipOptions, sevenZipSync } from 'cross-7zip';
*
* function createArchiveSync(): void {
* try {
* const zipOptions: ZipOptions = {
* destination: 'example.7z',
* files: ['document.txt', 'image.png', 'folder']
* };
*
* sevenZipSync(zipOptions);
* console.log('Archive created successfully.');
* } catch (error) {
* console.error('An error occurred during compression:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzipSync.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzipSync.test.ts).
*/
declare function sevenZipSync(options: ZipOptions): void;
/**
* Extracts files from a specified zipped file **synchronously**.
*
* @param options An object containing options for the extraction process.
*
* @throws {Error} Will throw an error if the 7-Zip executable is not found.
*
* @example
* ```ts
* import { sevenUnzipSync } from 'cross-7zip';
*
* function extractFilesSync(): void {
* try {
* const unzipOptions: UnzipOptions = {
* archive: 'example.7z',
* destination: './output'
* };
*
* sevenUnzipSync(unzipOptions);
* console.log('Extraction completed successfully.');
* } catch (error) {
* console.error('An error occurred during extraction:', error);
* }
* }
* ```
*
* For additional examples, see the
* [sevenZipUnzipSync.test.ts](https://github.com/rdarida/cross-7zip/blob/main/tests/sevenZipUnzipSync.test.ts).
*/
declare function sevenUnzipSync(options: UnzipOptions): void;
export { SevenUnzip, SevenZip, type UnzipOptions, type ZipOptions, sevenUnzip, sevenUnzipSync, sevenZip, sevenZipSync };