node-7z

A Node.js wrapper for 7-Zip

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

• Usage
• Installation
• API
  • Commands
  • Options
  • Events
• Advanced usage

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