Skip to content

Latest commit

 

History

History
408 lines (315 loc) · 12.7 KB

README.md

File metadata and controls

408 lines (315 loc) · 12.7 KB
Raw

node-7z-forall

NPM

Dependencies Status Node.js CI codecov MaintainabilityRelease

A CommonJs and ESM frontend to 7-Zip, downloads binaries in for Linux, Windows, and Mac OSX, with methods to create SFX self extracting 7z archives targeting different platforms.

This is for version 2.x WIP, for version 1.x see 1x branch.

There is another module node-7z-archive that is ESM only, has an alternative CLI interface, and using the full 7zip version, mostly a BC rewrite.

Usage

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

// CommonJS
const Zip = require('node-7z-forall');
const extractFull = Zip.extractFull;

// ESM for Node JS v12+
import { extractFull } from 'node-7z-forall';

extractFull('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 16.04 for all targets.

  • createSfxWindows(name, files, destination, options, type);

  • createSfxLinux(name, files, destination, options, type);

  • createSfxMac(name, files, destination, options, type);

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

/**
 * Creates self extracting archive, an Installation Package.
 *
 * @param {String} name Application name.
 * @param {Array} files Files to add.
 * @param {String} destination Application root for the `SfxPackages` directory, will default to package root.
 * - All Sfx package archives are stored in the **created** `SfxPackages` directory.
 * - The `destination` directory must already exists.
 * @param {Object} options Object for Installer config and 7-zip switch options.
 *
 * `{`
 *
 * `title:` - Window title message, Default "`name` installation package created on `Current running platform OS`"
 *
 * `beginPrompt:` - Begin Prompt message, Default "Do you want to install `name`?""
 *
 * `installPath:` - "path_to_extract", Sets the extraction path. The extraction folder will not be deleted after the extraction.
 *
 * `progress:` - Value can be "yes" or "no". Default value is "yes".
 *
 * `runProgram:` - Command for executing. Default value is "setup.exe".
 * Substring `% % T` will be replaced with path to temporary folder,
 * where files were extracted
 *
 * `directory:` - Directory prefix for `RunProgram`. Default value is `.\`
 *
 * `executeFile:` Name of file for executing
 *
 * `executeParameters:` Parameters for `ExecuteFile`
 *
 * `}`
 *
 * `NOTE:` There are two ways to run program: `RunProgram` and `ExecuteFile`.
 * - Use `RunProgram`, if you want to run some program from .7z archive.
 * - Use `ExecuteFile`, if you want to open some document from .7z archive or
 * if you want to execute some command from Windows.
 * @param {String} type Application type `gui` or `console`. Default `gui`. Only `console` possible on **Linux** and **Mac** OS.
 * @param {String} platform What platform application targeting? Either `win32`, `darwin`, or `linux`.
 * @param {String} extension Binary extension name.
 *
 * @resolve {String} The created application full path location.
 * @progress {array} Listed files and directories.
 * @reject {Error} The error as issued by 7-Zip.
 *
 * @returns {Promise} Promise
 */
createSfx(
  name,
  files,
  destination = {PACKAGE_ROOT} + '/SfxPackages',
  options = {
      title: 'Windows Title',
      beginPrompt: 'Begin installation?',
      progress: 'no',
      runProgram: 'start',
      directory: './',
    ....
  },
  type = 'gui',
  platform = 'win32',
  extension = '.exe'
);

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 - https://sourceforge.net/projects/p7zip

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

On Mac OSX - https://rudix.org/

npm install --save node-7z-forall

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.

const Zip = require('node-7z-forall');

Or:

import Zip from 'node-7z-forall';

By method name: import { add, delete, extract, extractFull, list, test, update } from 'node-7z-forall';

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

Add: Zip.add(archive, files, options)

Arguments

  • archive Path to the archive you want to create.
  • files The file list to add.
  • options An object of options (7-Zip switches).

Progress

  • files A array of all the added files. The / character is used as a path separator on every platform.

Error

  • err An Error object.

Delete: Zip.delete(archive, files, options)

Arguments

  • archive Path to the archive you want to delete files from.
  • files The file list to delete.
  • options An object of options (7-Zip switches).

Error

  • err An Error object.

Extract: Zip.extract(archive, dest, options)

Arguments

  • archive The path to the archive you want to extract.
  • dest Where to extract the archive.
  • options An object of options.

Progress

  • files A array of all the extracted files AND directories. The / character is used as a path separator on every platform.

Error

  • err An Error object.

Extract with full paths: Zip.extractFull(archive, dest, options)

Arguments

  • archive The path to the archive you want to extract.
  • dest Where to extract the archive (creates folders for you).
  • options An object of options.

Progress

  • files A array of all the extracted files AND directories. The / character is used as a path separator on every platform.

Error

  • err An Error object.

List contents of archive: Zip.list(archive, options)

Arguments

  • archive The path to the archive you want to analyse.
  • options An object of options.

Progress

  • files A array of objects of all the extracted files AND directories. The / character is used as a path separator on every platform. Object's properties are: date, attr, size and name.

Then - Resolved

  • spec An object of tech spec about the archive. Properties are: path, type, method, physicalSize and headersSize (Some of them may be missing with non-7z archives).

Error

  • err An Error object.

Test integrity of archive: Zip.test(archive, options)

Arguments

  • archive The path to the archive you want to analyse.
  • options An object of options.

Progress

  • files A array of all the tested files. The / character is used as a path separator on every platform.

Error

  • err An Error object.

Update: Zip.update(archive, files, options)

Arguments

  • archive Path to the archive you want to update.
  • files The file list to update.
  • options An object of options (7-Zip switches).

Progress

  • files A array of all the updated files. The / character is used as a path separator on every platform.

Error

  • err An Error object.

Advanced usage

Compression method

With the 7za 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.
7za a archive.7z *.exe -m0=BCJ -m1=LZMA:d=21

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

import { add } from 'node-7z-forall';

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

Add, delete and update multiple files

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

import { delete as del } from 'node-7z-forall';

del('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 { extractFull } from 'node-7z-forall';

extractFull('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

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 (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 { list } from 'node-7z-forall';

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