node-7z v3.0.0

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.

// 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.

// 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.

// 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.

// 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.

// calculates SHA256 for a.iso.
const myStream = Seven.hash('a.iso', {
  hashMethod: 'sha256'
})

List

Lists contents of an archive.

// 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.

// 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.

// 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.

// 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

Special options

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

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 *.exe and *.dll files to solid archive archive.7z using 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']
})

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 :heart: from quentinrossetti