Skip to content

Commit

Permalink
docs: update README.md with new ways to use API
Browse files Browse the repository at this point in the history
  • Loading branch information
@onikienko
onikienko committed Jan 15, 2025
1 parent 578c33a commit b9bb08e
Showing 1 changed file with 132 additions and 23 deletions.
155 changes: 132 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

Minimal cross-platform pack/unpack (and any command) with **7-zip** for Node.js.
It does not require **7zip** to be installed in your system.
This package includes standalone **7za** version of **7-Zip** (uses precompiled binaries from [7zip-bin](https://github.com/develar/7zip-bin) package).
This package includes a standalone **7za** version of **7-Zip** (uses precompiled binaries from [7zip-bin](https://github.com/develar/7zip-bin) package).


Supporting archive formats
Expand All @@ -25,51 +25,160 @@ Supporting platforms
- ia32
- x64

To get more details check [7zip-bin](https://github.com/develar/7zip-bin) package repo.
To get more details, check [7zip-bin](https://github.com/develar/7zip-bin) package repo.

Package should work with Electron.
You will have to unpack the binary ([`asarUnpack`](https://www.electron.build/configuration#asarunpack) option if you use `electron-builder`.)

Usage
-----

You may use `pack` and `unpack` methods for simple packing/unpacking.

You can also use `list` to get an array with the file content properties (includes date, time, attr, size, compressed and name)
You can also use `list` to get an array with the file content properties (includes date, time, attr, size, compressed, and name)

Or use `cmd` to run 7za with custom parameters (see [Command Line Version User's Guide](https://web.mit.edu/outland/arch/i386_rhel4/build/p7zip-current/DOCS/MANUAL/))

You can use package with callbacks and in async way (with promises).

### Basic examples

```javaScript
const _7z = require('7zip-min');

// unpack
_7z.unpack('path/to/archive.7z', 'where/to/unpack', err => {
// done
});
// .......
await _7z.pack('path/to/dir/or/file', 'path/to/archive.7z');
await _7z.unpack('path/to/archive.7z', 'where/to/unpack');
const list = await _7z.list('path/to/archive.7z'); // list of items inside archive
const output = await _7z.cmd(['a', 'path/to/archive.7z', 'path/to/dir/or/file']); // run custom command
```

### Examples with callbacks and promises

// unpack into the current directory (process.cwd()) if no output directory specified
_7z.unpack('path/to/archive.7z', err => {
// done
#### unpack()

```javaScript
// unpack with callback
_7z.unpack('path/to/archive.7z', 'where/to/unpack', (err, output) => {
if (err) {
console.error('Error', err.message);
} else {
// everything is Ok
console.log('stdout of the 7za command execution', output); // output just in case you need it
}
});

// pack
_7z.pack('path/to/dir/or/file', 'path/to/archive.7z', err => {
// done
// unpack with promise
_7z.unpack('path/to/archive.7z', 'where/to/unpack')
.then(output => console.log('stdout of the 7za command execution', output))
.catch(err => console.error('Error', err.message));

// unpack with async/await
(async () => {
try {
const output = await _7z.unpack('path/to/archive.7z', 'where/to/unpack');
console.log('stdout of the 7za command execution', output);
} catch (err) {
console.error('Error', err.message);
}
})();

// if no output directroy specified, it will unpack into the current directory (process.cwd())
_7z.unpack('path/to/archive.7z')
.then(output => console.log('stdout of the 7za command execution', output))
.catch(err => console.error('Error', err.message));
```

#### pack()

```javaScript
// pack with callback
_7z.pack('path/to/dir/or/file', 'path/to/archive.7z', (err, output) => {
if (err) {
console.error('Error', err.message);
} else {
// everything is Ok
console.log('stdout of the 7za command execution', output);
}
});

// list
_7z.list('path/to/archive.7z', (err, result) => {
// in result you will have an array with info list for your archive
// For each element in the archive you will have:
// name, date, time, attr, size (in bytes), compressed (compressed size in bytes), crc, method, encrypted, block
// Depending on the archive type some values may be empty or missed
// pack with promise
_7z.pack('path/to/dir/or/file', 'path/to/archive.7z')
.then(output => console.log('stdout of the 7za command execution', output))
.catch(err => console.error('Error', err.message));

// pack with async/await
(async () => {
try {
const output = await _7z.pack('path/to/dir/or/file', 'path/to/archive.7z');
console.log('stdout of the 7za command execution', output);
} catch (err) {
console.error('Error', err.message);
}
})();
```

#### list()

```javaScript
// list with callback
_7z.list('path/to/archive.7z', (err, list) => {
if (err) {
console.error('Error', err.message);
} else {
console.log('List of items inside the archive', list);
// For each element in the archive you will have:
// name, date, time, attr, size (in bytes), compressed (compressed size in bytes), crc, method, encrypted, block
// Depending on the archive type some values may be empty or missed
}
});

// cmd
// list with promise
_7z.list('path/to/archive.7z')
.then(list => console.log('List of items inside the archive', list))
.catch(err => console.error('Error', err.message));

// list with async/await
(async () => {
try {
const list = await _7z.list('path/to/archive.7z');
console.log('List of items inside the archive', list);
} catch (err) {
console.error('Error', err.message);
}
})();
```

#### cmd()

```javaScript
// cmd with callback
// in the first parameter you have to provide an array of parameters
// check 7z's Command Line Version User's Guide - https://sevenzip.osdn.jp/chm/cmdline/index.htm
// check 7z's Command Line Version User's Guide - https://web.mit.edu/outland/arch/i386_rhel4/build/p7zip-current/DOCS/MANUAL/
// the bellow command is equal to `7za a path/to/archive.7z path/to/dir/or/file` and will add `path/to/dir/or/file` to `path/to/archive.7z` archive
_7z.cmd(['a', 'path/to/archive.7z', 'path/to/dir/or/file'], err => {
// done
_7z.cmd(['a', 'path/to/archive.7z', 'path/to/dir/or/file'], (err, output) => {
if (err) {
console.error('Error', err.message);
} else {
// Execution finished succesfully
console.log('stdout of the 7za command execution', output);
}
});

// cmd with promise
_7z.cmd(['a', 'path/to/archive.7z', 'path/to/dir/or/file'])
.then(output => console.log('stdout of the 7za command execution', output))
.catch(err => console.error('Error', err.message));

// cmd with async/await
(async () => {
try {
const output = await _7z.cmd(['a', 'path/to/archive.7z', 'path/to/dir/or/file']);
console.log('stdout of the 7za command execution', output);
} catch (err) {
console.error('Error', err.message);
}
})();
```

Test
Expand Down

0 comments on commit b9bb08e

Please sign in to comment.