Skip to content

q2s2t/node-7z

Repository files navigation

node-7z

A Node.js wrapper for 7-Zip

Release Dependencies Status Linux Build Windows Build Code coverage Code Maintainability Known Vulnerabilities

Usage

import Seven from 'node-7z'

// myStream is a Readable stream
const myStream = Seven.extractFull('./archive.7z', './output/dir/', {
  $progress: true
})

myStream.on('data', function (data) {
  doStuffWith(data) //? { status: 'extracted', file: 'extracted/file.txt" }
})

myStream.on('progress', function (progress) {
  doStuffWith(progress) //? { percent: 67, fileCount: 5, file: undefinded }
})

myStream.on('end', function () {
    // end of the operation, get the number of folders involved in the operation
  myStream.info.get('Folders') //? '4'
})

myStream.on('error', (err) => handleError(err))

Table of content

Installation

npm install --save node-7z

You should have the a 7-Zip executable (v16.02 or greater) available in your system.

  • On Debian and Ubuntu install the p7zip-full package or use 7-Zip 21.02 alpha or higher
  • On Mac OSX use Homebrew brew install p7zip
  • On Windows get 7-Zip from 7-Zip download page.

By default the module calls the 7z binary, it should be available in your PATH.

An alternative is to add the 7zip-bin module to your project. This module contains an up-to-date version of 7-Zip for all available plaforms. Then you can do:

import sevenBin from '7zip-bin'
import { extractFull } from 'node-7z'

const pathTo7zip = sevenBin.path7za
const seven = extractFull('./archive.7z', './output/dir/', {
  $bin: pathTo7zip
})

API

See the 7-Zip documentation for the full list of usages and options (switches).

Commands

Add

Adds files to an archive.

Arguments Type Description
archive string Archive to create
source string|string[] Source files to add to the archive. Multiple sources can be given using an Array
[options] Object Options object. Can be omitted
// adds all *.txt files from current folder and its subfolders to archive Files.7z.
const myStream = Seven.add('Files.7z', '*.txt', {
  recursive: true
})

Delete

Deletes files from an archive.

Arguments Type Description
archive string Archive to target
target string|string[] Target files to remove from the archive. Multiple targets can be given using an Array
[options] Object Options object. Can be omitted
// deletes *.bak files from archive archive.zip.
const myStream = Seven.delete('archive.zip', '*.bak')

Extract

Extracts files from an archive to the current directory or to the output directory. This command copies all extracted files to one directory.

Arguments Type Description
archive string Archive to extract files from
output string Output directory
[options] Object Options object. Can be omitted
// extracts all *.cpp files from archive archive.zip to c:\soft folder.
const myStream = Seven.extract('archive.zip', 'c:/soft', {
  recursive: true,
  $cherryPick: '*.cpp'
})

Extract with full paths

Extracts files from an archive with their full paths in the current directory, or in an output directory if specified.

Arguments Type Description
archive string Archive to extract files from
output string Output directory
[options] Object Options object. Can be omitted
// extracts all *.cpp files from the archive archive.zip to c:\soft folder.
const myStream = Seven.extractFull('archive.zip', 'c:/soft', {
  recursive: true,
  $cherryPick: '*.cpp'
})

Hash

Calculates hash values for files.

Arguments Type Description
target string|string[] Target files to calculate the hash of. Multiple targets can be given using an Array
[options] Object Options object. Can be omitted
// calculates SHA256 for a.iso.
const myStream = Seven.hash('a.iso', {
  hashMethod: 'sha256'
})

List

Lists contents of an archive.

Arguments Type Description
archive string Archive to list the file from
[options] Object Options object. Can be omitted
// list all the *.txt and *.js files in archive.zip
const myStream = Seven.list('archive.zip', {
  $cherryPick: ['*.txt*', '*.js'],
})

Rename

Renames files in an archive.

Arguments Type Description
archive string Archive to target
target Array[string[]] Pair of target/new names files to remove rename. Multiple targets can be given using an Array
[options] Object Options object. Can be omitted
// renames old.txt to new.txt and 2.txt to folder\2new.txt .
const myStream = Seven.rename('a.7z', [
  ['old.txt', 'new.txt'],
  ['2.txt', 'folder/2new.txt']
])

Test integrity

Tests archive files.

Arguments Type Description
archive string Archive to test
[options] Object Options object. Can be omitted
// tests *.doc files in archive archive.zip.
const myStream = Seven.list('archive.zip', {
  recursive: true,
  $cherryPick: '*.doc'
})

Update

Updates older files in the archive and adds files that are not already in the archive.

Arguments Type Description
archive string Archive to create
source string|string[] Source files to update from the file-system to the archive. Multiple sources can be given using an Array
[options] Object Options object. Can be omitted
// updates *.doc files to archive archive.zip.
const myStream = Seven.add('archive.zip', '*.doc')

Options

Switches

In the 7-Zip world, command flags are called switches. In order to use them you can pass their name and value in the Options object

Name Type Description Switches
alternateStreamExtract boolean "Extract file as alternate stream, if there is ':' character in name" -snc
alternateStreamReplace boolean Replace ':' character to '_' character in paths of alternate streams -snr
deleteFilesAfter boolean Delete files after compression -sdel
fullyQualifiedPaths boolean Usefully qualified file paths -spf
hardlinks boolean Store hard links as links (WIM and TAR formats only) -snh
largePages boolean Set Large Pages mode -spl
latestTimeStamp boolean Set archive timestamp from the most recently modified file -stl
noArchiveOnFail boolean Stop archive creating, if 7-Zip can't open some input file. -sse
noRootDuplication boolean Eliminate duplication of root folder for extract command -spe
noWildcards boolean Disable wildcard matching for file names -spd
ntSecurity boolean Store NT security -sni
sortByType boolean Sort files by type while adding to solid 7z archive -mqs
openFiles boolean Compress files open for writing -ssw
recursive boolean Recurse subdirectories. For -r0 usage see raw -r
symlinks boolean Store symbolic links as links (WIM and TAR formats only) -snl
techInfo boolean Show technical information -slt
timeStats boolean Show execution time statistics -bt
toStdout boolean Write data to stdout -so
yes boolean Assume Yes on all queries -y
alternateStreamStore boolean Store NTFS alternate Streams -sns
caseSensitive boolean Set Sensitive Case mode -ssc
archiveNameMode string Set Archive name mode -sa
archiveType string Type of archive -t
cpuAffinity string Set CPU thread affinity mask (hexadecimal number). -stm
excludeArchiveType string Exclude archive type -stx
fromStdin string Read data from StdIn -si
hashMethod string Set hash function -scrc
listFileCharset string Set charset for list files -scs
logLevel string Set output log level -bb
multiBlockSize string Creates multi-block xz archives of [Size]m|g block size -ms
outputDir string Set Output directory -o
overwrite string Overwrite mode -ao
password string Set Password -p
sfx string Create SFX archive -sfx
updateOptions string Update options -u
workingDir string Set Working directory -w
excludeArchive string[] Exclude archive filenames -ax
exclude string[] Exclude filenames -x
include string[] Include filenames -i
includeArchive string[] Include archive filenames -ai
method string[] Set Compression Method -m
outputStreams string[] Set output stream for output/error/progress -bs
volumes string[] Create Volumes -v

Special options

Those options are not provided by 7-Zip but are features of this module.

Name Type Description
$progress boolean Progress percentage gets fired. Shortcut for { outputStreams: ['b1'] } Use if you want access to the progress event. Has an impact on performances.
$defer boolean Create the stream but do not spawn child process
$childProcess ChildProcess Attach an external child process to be parsed
$bin string Path to an other 7-Zip binary. Default: 7z
$cherryPick string[] Some commands accepts more specific targets, see example above
$raw string[] Pass raw arguments to the child_process.spawn()command
$spawnOptions Object Pass options to the child_process.spawn()command

Events

Event: data

The data event is emitted for each processed file. The payload is an object. WARNING only the data.file proprety is guaranteed to be present

mySevenStream.on('data', function (data) {
  console.log(data)
  // {
  //   file: 'path/of/the/file/in/the/archive',
  //   status: 'renamed|tested|updated|skipped|deleted|extracted',
  //   attributes: '....A', size: 9, sizeCompressed: 3, (only list command)
  //   hash: 'FEDC304F', size: 9 (only hash command)
  //   techInfo: Map(8) { (only list command with `techInfo` switch)
  //      'Path' => 'DirHex/sub2/e825776890f2b',
  //      'Size' => '9',
  //      'Modified' => '2018-09-29 09:06:15',
  //      'Attributes' => 'A_ -rw-r--r--',
  //      'CRC' => 'FEDC304F',
  //      'Encrypted' => '-',
  //      'Method' => 'LZMA2:12',
  //      'Block' => '0'
  //   }
  // }
})

Event: end

An .info proprety can contain meta-data (type Map)

myStream.info
// Map {
//   '7-Zip [64] 16.02 ' => 'Copyright (c) 1999-2016 Igor Pavlov : 2016-05-21',
//   'Creating archive' => './test/_tmp/txt-and-md-only.7z',
//   'Items to compress' => '6',
//   'Files read from disk' => '6',
//   'Archive size' => '212 bytes (1 KiB)' }

Event: error

mySevenStream.on('error', function (err) {
  // a standard error
  // `err.stderr` is a string that can contain extra info about the error
})

Advanced usage

Compression method

Using the CLI, compression is done like this:

# adds all .exe files to solid archive archive.7z using the LZMA method
# with 2 MB dictionary and BCJ filter.
7z a archive.7z *.exe -m0=BCJ -m1=LZMA:d=21

Using this module:

const compress = Seven.add('archive.7z', '*.exe', {
  method: ['0=BCJ', '1=LZMA:d=21']
})

Encrypt metadata (hide filenames in password protected archives)

This operation is supported only in the 7z file format. Using the CLI, if you want to password protect an archive while also hiding filenames you write:

# adds all .exe files with a password and also encrypt metadata, thus hiding filenames
7z a archive.7z *.exe -p -mhe

Using this module:

const compress = Seven.add('archive.7z', '*.exe', {
  password: "your-password-here",
  method: ['he']
})

Raw inputs

Thanks to sketchpunk #9 for this one

Sometimes you just want to use the lib as the original command line. For instance you want to apply to switches with different values. You can use the custom $raw key in your options object and pass it an Array of values.

const compress = Seven.add('archive.7z', '*.gif', {
  $raw: [ '-i!*.jpg', '-i!*.png' ], // only images
})

Emoji and Unicode

Due to a 7z limitation emojis and special characters can't be used as values when passed to an option object (ex: password). But they can be used in archive, filenames and destinations.

Use the { charset: 'UTF-8' } for special characters.

Log level

The default log level (-bb switch) is set to:

3 :show information about additional operations (Analyze, Replicate) for "Add" / "Update" operations.

It's a base feature of node-7z and is required for the module to work as expected. A diffrent value should not be used.

Security

Values given by the package are not sanitized, you just get the raw output from the 7-Zip binary. Remember to never trust user input and sanitize accordingly.

External child process

You can pipe a child procress from an other source and pass it to node-7z. An use case may be that the 7-Zip process runs on an other machine and the sdtio is piped in the application.

const external = // an external child process
const myStream = Seven.add('dummy', 'dummy', {
  $defer: true
})
myStream.on('data', data => yourLogicWith(data))
Seven.listen(myStream)

With ❤️ from quentinrossetti