search

TheTechsTech / node-7z-archive

ESM front-end to 7-Zip, featuring alternative 7z CLI tool, binaries for Linux, Windows, Mac OSX, and seamlessly create 7zip SFX self extracting archives targeting different platforms.
MIT License
13 stars 7 forks source link

readme

node-7z-archive

NPM

Dependencies Status Node.js CI codecov MaintainabilityRelease

ESM front-end to 7-Zip, featuring alternative full 7z CLI tool, binaries for Linux, Windows, Mac OSX, seamlessly create 7zip SFX self extracting archives targeting different platforms.

Usage

This library use Promises, it's API is consistent with standard use:

import { fullArchive } from 'node-7z-archive';

fullArchive('myArchive.7z', 'destination', { p: 'myPassword' } /* 7z options/switches */)
// Equivalent to `on('data', function (files) { // ... });`
.progress(function (files) {
  console.log('Some files are extracted: %s', files);
})

// When all is done
.then(function () {
  console.log('Extracting done!');
})

// On error
.catch(function (err) {
  console.error(err);
});

How to create Sfx - Self Extracting Archives.

Executables will be built using 7-zip version 19.00 on Windows OS for Windows targets. Linux and Apple macOS will use 7-zip version 17.02 for all targets.

import { createSfxWindows, createSfxLinux, createSfxMac } from 'node-7z-archive';

Each will in turn call: createSfx(name, files, destination, options, type, platform, extension) as:

Installation

This package will download the 7zip binaries at install time. Host system does not need to have 7zip installed or in PATH.

The binaries will be downloaded from:

On Linux - Release compiled and available at releases previously https://sourceforge.net/projects/p7zip.

On Windows - https://www.7-zip.org/download.html.

On Mac OSX - Release compiled and available at releases previously https://rudix.org/.

npm install --save node-7z-archive

CLI

For using full 7zip from command line without installation package.

npm install -g node-7z-archive

Will have createArchive, deleteArchive, extractArchive, fullArchive, listArchive, renameArchive, testArchive, updateArchive, createSfx available globally. To always see available commands, and binary location type:

7zip

Outputs:

Full 7zip Console Commands.

 ESM front-end to 7-Zip, featuring alternative full 7z CLI tools, binaries for Linux, Windows, Mac OSX, seamlessly create 7zip SFX self extracting archives targeting different platforms.

 **Commands**

 Adds files to archive.
 Usage: `createArchive` archivePath files ...options

 Deletes files from archive.
 Usage: `deleteArchive` archivePath files ...options

 Extracts files from an archive to the current directory or to the output directory.
 Usage: `extractArchive` archivePath destination ...options

 Extracts files from an archive with their full paths in the current directory, or in an output directory
 Usage: `fullArchive` archivePath destination ...options

 Extracts only the selected files from an archive to the current directory, or in an output directory
 Usage: `onlyArchive` archivePath destination files ...options'

 Lists contents of archive.
 Usage: `listArchive` archivePath ...options

 Renames files in archive.
 Usage: `renameArchive` archivePath file pairs ...options

 Tests archive files.
 Usage: `testArchive` archivePath ...options

 Update older files in the archive and add files that are not already in the archive.
 Usage: `updateArchive` archivePath files ...options

 Create an Sfx - self extracting installation package for targeted platform.
 Usage: `createSfx` platform packageName files --dir [save/to] --gui | --console ...options

-----------------------------------------------------------------
 The `7z` and `7za` binary on your system is located in directory: ...\...\node-7z-archive\binaries\...

This package is a rewrite of node-7z-forall. The original author has removed the version it was a fork of node-7z. The methods are still backwards compatible with previous naming of add, delete, extract, extractFull, list, rename, test, update.

API

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

The type of the list of files can be either String or Array.

import SevenZip from 'node-7z-archive';

const { SevenZip } = require('node-7z-archive');

By method name: import { createArchive, deleteArchive, extractArchive, fullArchive, listArchive, renameArchive, testArchive, updateArchive } from 'node-7z-archive';

Options: 7-Zip Switches, use without initial '-'.

  -- : Stop switches and @listfile parsing
  -ai[r[-|0]]{@listfile|!wildcard} : Include archives
  -ax[r[-|0]]{@listfile|!wildcard} : eXclude archives
  -ao{a|s|t|u} : set Overwrite mode
  -an : disable archive_name field
  -bb[0-3] : set output log level
  -bd : disable progress indicator
  -bs{o|e|p}{0|1|2} : set output stream for output/error/progress line
  -bt : show execution time statistics
  -i[r[-|0]]{@listfile|!wildcard} : Include filenames
  -m{Parameters} : set compression Method
    -mmt[N] : set number of CPU threads
    -mx[N] : set compression level: -mx1 (fastest) ... -mx9 (ultra)
  -o{Directory} : set Output directory
  -p{Password} : set Password
  -r[-|0] : Recurse subdirectories
  -sa{a|e|s} : set Archive name mode
  -scc{UTF-8|WIN|DOS} : set charset for console input/output
  -scs{UTF-8|UTF-16LE|UTF-16BE|WIN|DOS|{id}} : set charset for list files
  -scrc[CRC32|CRC64|SHA1|SHA256|*] : set hash function for x, e, h commands
  -sdel : delete files after compression
  -seml[.] : send archive by email
  -sfx[{name}] : Create SFX archive
  -si[{name}] : read data from stdin
  -slp : set Large Pages mode
  -slt : show technical information for l (List) command
  -snh : store hard links as links
  -snl : store symbolic links as links
  -sni : store NT security information
  -sns[-] : store NTFS alternate streams
  -so : write data to stdout
  -spd : disable wildcard matching for file names
  -spe : eliminate duplication of root folder for extract command
  -spf : use fully qualified file paths
  -ssc[-] : set sensitive case mode
  -sse : stop archive creating, if it can't open some input file
  -ssw : compress shared files
  -stl : set archive timestamp from the most recently modified file
  -stm{HexMask} : set CPU thread affinity mask (hexadecimal number)
  -stx{Type} : exclude archive type
  -t{Type} : Set type of archive
  -u[-][p#][q#][r#][x#][y#][z#][!newArchiveName] : Update options
  -v{Size}[b|k|m|g] : Create volumes
  -w[{path}] : assign Work directory. Empty path means a temporary directory
  -x[r[-|0]]{@listfile|!wildcard} : eXclude filenames
  -y : assume Yes on all queries

createArchive(filepath, files, options)

Arguments

Progress

Error

deleteArchive(filepath, files, options)

Arguments

Error

extractArchive(filepath, dest, options)

Arguments

Progress

Error

fullArchive(filepath, dest, options)

Arguments

Progress

Error

listArchive(filepath, options)

Arguments

Progress

Then - Resolved

Error

onlyArchive(filepath, dest, files, options)

Arguments

Progress

Error

renameArchive(filepath, files, options)

Arguments

Progress

Error

testArchive(filepath, options)

Arguments

Progress

Error

updateArchive(filepath, files, options)

Arguments

Progress

Error

Advanced usage

Compression method

With the 7z binary compression is made like that:

# 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

With node-7z-archive you can translate it like that:

import { createArchive } from 'node-7z-archive';

createArchive('archive.7z', '*.exe', {
  m0: '=BCJ',
  m1: '=LZMA:d=21'
})
.then(function () {
  // Do stuff...
});

createArchive, deleteArchive and updateArchive multiple files

When adding, deleting or updating archives you can pass either a string or an array as second parameter (the files parameter).

import { deleteArchive } from 'node-7z-archive';

deleteArchive('bigArchive.7z', [ 'file1', 'file2' ])
.then(function () {
  // Do stuff...
});

Wildcards

You can extract with wildcards to specify one or more file extensions. To do this add a wildcards attribute to the options object. The wildcard attribute takes an Array as value. In this array each item is a wildcard.

import { fullArchive } from 'node-7z-archive';

fullArchive('archive.zip', 'destination/', {
  wildcards: [ '*.txt', '*.md' ], // extract all text and Markdown files
  r: true // in each subfolder too
})
.progress(function (files) {
  // Do stuff with files...
})
.then(function () {
  // Do stuff...
});

Note that the r (for recursive) attribute is passed in this example.

Raw inputs

Sometimes you just want to use the lib as the original command line. For instance you want to apply to switches with different values (e.g.: -i!*.jpg -i!*.png to target only two types of extensions).

In such cases the default behavior of the options argument is not enough. You can use the custom raw key in your options object and pass it an Array of values.

import { listArchive } from 'node-7z-archive';

listArchive('archive.zip', {
  raw: [ '-i!*.jpg', '-i!*.png' ], // only images
})
.progress(function (files) {
  // Do stuff with files...
})
.then(function () {
  // Do stuff...
});