A Node.js wrapper for 7-Zip
\n\n[![Release][npm-image]][npm-url]\n[![Dependencies Status][david-image]][david-url]\n[![Linux Build][circleci-image]][circleci-url]\n[![Windows Build][appveyor-image]][appveyor-url]\n[![Code coverage][coverage-image]][coverage-url]\n[![Code Maintainability][maintainability-image]][maintainability-url]\n[![Known Vulnerabilities][vulnerabilities-image]][vulnerabilities-url]\n\n## Usage\n\n```js\nimport Seven from 'node-7z'\n\n// myStream is a Readable stream\nconst myStream = Seven.extractFull('./archive.7z', './output/dir/', {\n $progress: true\n})\n\nmyStream.on('data', function (data) {\n doStuffWith(data) //? { status: 'extracted', file: 'extracted/file.txt\" }\n})\n\nmyStream.on('progress', function (progress) {\n doStuffWith(progress) //? { percent: 67, fileCount: 5, file: undefinded }\n})\n\nmyStream.on('end', function () {\n // end of the operation, get the number of folders involved in the operation\n myStream.info.get('Folders') //? '4'\n})\n\nmyStream.on('error', (err) => handleError(err))\n\n```\n\n## Table of content\n\n * [Usage](#usage)\n * [Installation](#installation)\n * [API](#api)\n * [Commands](#commands)\n * [Options](#options)\n * [Events](#events)\n * [Advanced usage](#advanced-usage)\n\n\n## Installation\n\n```sh\nnpm install --save node-7z\n```\n\nYou should have the a 7-Zip executable (v16.02 or greater) available in your system.\n\n> - On Debian and Ubuntu install the p7zip-full package or use 7-Zip 21.02 alpha or higher\n> - On Mac OSX use Homebrew `brew install p7zip`\n> - On Windows get 7-Zip from [7-Zip download page](https://www.7-zip.org/download.html).\n>\n> By default the module calls the `7z` binary, it should be available in your\n> PATH.\n\nAn alternative is to add the `7zip-bin` module to your project. This module\ncontains an up-to-date version of 7-Zip for all available plaforms. Then you\ncan do:\n\n```js\nimport sevenBin from '7zip-bin'\nimport { extractFull } from 'node-7z'\n\nconst pathTo7zip = sevenBin.path7za\nconst seven = extractFull('./archive.7z', './output/dir/', {\n $bin: pathTo7zip\n})\n```\n\n## API\n\n> See the [7-Zip documentation](http://sevenzip.sourceforge.jp/chm/cmdline/index.htm)\n> for the full list of usages and options (switches).\n\n### Commands\n\n#### Add\nAdds files to an archive.\n\n| Arguments | Type | Description |\n|-----------|--------------------|-------------|\n| archive | `string` | Archive to create |\n| source | `string\\|string[]` | Source files to add to the archive. Multiple sources can be given using an `Array` |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// adds all *.txt files from current folder and its subfolders to archive Files.7z.\nconst myStream = Seven.add('Files.7z', '*.txt', {\n recursive: true\n})\n```\n\n#### Delete\nDeletes files from an archive.\n\n| Arguments | Type | Description |\n|-----------|--------------------|-------------|\n| archive | `string` | Archive to target |\n| target | `string\\|string[]` | Target files to remove from the archive. Multiple targets can be given using an `Array` |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// deletes *.bak files from archive archive.zip.\nconst myStream = Seven.delete('archive.zip', '*.bak')\n```\n\n#### Extract\nExtracts files from an archive to the current directory or to the output directory. This command copies all extracted files to one directory.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to extract files from |\n| output | `string` | Output directory |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// extracts all *.cpp files from archive archive.zip to c:\\soft folder.\nconst myStream = Seven.extract('archive.zip', 'c:/soft', {\n recursive: true,\n $cherryPick: '*.cpp'\n})\n```\n\n#### Extract with full paths\nExtracts files from an archive with their full paths in the current directory, or in an output directory if specified.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to extract files from |\n| output | `string` | Output directory |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// extracts all *.cpp files from the archive archive.zip to c:\\soft folder.\nconst myStream = Seven.extractFull('archive.zip', 'c:/soft', {\n recursive: true,\n $cherryPick: '*.cpp'\n})\n```\n\n#### Hash\nCalculates hash values for files.\n\n| Arguments | Type | Description |\n|-----------|--------------------|-------------|\n| target | `string\\|string[]` | Target files to calculate the hash of. Multiple targets can be given using an `Array` |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// calculates SHA256 for a.iso.\nconst myStream = Seven.hash('a.iso', {\n hashMethod: 'sha256'\n})\n```\n\n#### List\nLists contents of an archive.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to list the file from |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// list all the *.txt and *.js files in archive.zip\nconst myStream = Seven.list('archive.zip', {\n $cherryPick: ['*.txt*', '*.js'],\n})\n```\n\n#### Rename\nRenames files in an archive.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to target |\n| target | `Array[string[]]` | Pair of target/new names files to remove rename. Multiple targets can be given using an `Array` |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// renames old.txt to new.txt and 2.txt to folder\\2new.txt .\nconst myStream = Seven.rename('a.7z', [\n ['old.txt', 'new.txt'],\n ['2.txt', 'folder/2new.txt']\n])\n```\n\n#### Test integrity\nTests archive files.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to test |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// tests *.doc files in archive archive.zip.\nconst myStream = Seven.list('archive.zip', {\n recursive: true,\n $cherryPick: '*.doc'\n})\n```\n\n#### Update\nUpdates older files in the archive and adds files that are not already in the archive.\n\n| Arguments | Type | Description |\n|-----------|-------------------|-------------|\n| archive | `string` | Archive to create |\n| source | `string\\|string[]` | Source files to update from the file-system to the archive. Multiple sources can be given using an `Array` |\n| [options] | `Object` | [Options object](#options). Can be omitted |\n\n```js\n// updates *.doc files to archive archive.zip.\nconst myStream = Seven.add('archive.zip', '*.doc')\n```\n\n### Options\n\n#### Switches\n\nIn 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](#options)\n\n| Name | Type | Description | Switches |\n|--------------------------|------------|-----------------------------------------------------------------------|----------|\n| `alternateStreamExtract` | `boolean` | \"Extract file as alternate stream, if there is ':' character in name\" | `-snc` |\n| `alternateStreamReplace` | `boolean` | Replace ':' character to '_' character in paths of alternate streams | `-snr` |\n| `deleteFilesAfter` | `boolean` | Delete files after compression | `-sdel` |\n| `fullyQualifiedPaths` | `boolean` | Usefully qualified file paths | `-spf` |\n| `hardlinks` | `boolean` | Store hard links as links (WIM and TAR formats only) | `-snh` |\n| `largePages` | `boolean` | Set Large Pages mode | `-spl` |\n| `latestTimeStamp` | `boolean` | Set archive timestamp from the most recently modified file | `-stl` |\n| `noArchiveOnFail` | `boolean` | Stop archive creating, if 7-Zip can't open some input file. | `-sse` |\n| `noRootDuplication` | `boolean` | Eliminate duplication of root folder for extract command | `-spe` |\n| `noWildcards` | `boolean` | Disable wildcard matching for file names | `-spd` |\n| `ntSecurity` | `boolean` | Store NT security | `-sni` |\n| `sortByType` | `boolean` | Sort files by type while adding to solid 7z archive | `-mqs` |\n| `openFiles` | `boolean` | Compress files open for writing | `-ssw` |\n| `recursive` | `boolean` | Recurse subdirectories. For `-r0` usage see `raw` | `-r` |\n| `symlinks` | `boolean` | Store symbolic links as links (WIM and TAR formats only) | `-snl` |\n| `techInfo` | `boolean` | Show technical information | `-slt` |\n| `timeStats` | `boolean` | Show execution time statistics | `-bt` |\n| `toStdout` | `boolean` | Write data to stdout | `-so` |\n| `yes` | `boolean` | Assume Yes on all queries | `-y` |\n| `alternateStreamStore` | `boolean` | Store NTFS alternate Streams | `-sns` |\n| `caseSensitive` | `boolean` | Set Sensitive Case mode | `-ssc` |\n| `archiveNameMode` | `string` | Set Archive name mode | `-sa` |\n| `archiveType` | `string` | Type of archive | `-t` |\n| `cpuAffinity` | `string` | Set CPU thread affinity mask (hexadecimal number). | `-stm` |\n| `excludeArchiveType` | `string` | Exclude archive type | `-stx` |\n| `fromStdin` | `string` | Read data from StdIn | `-si` |\n| `hashMethod` | `string` | Set hash function | `-scrc` |\n| `listFileCharset` | `string` | Set charset for list files | `-scs` |\n| `logLevel` | `string` | Set output log level | `-bb` |\n| `multiBlockSize` | `string` | Creates multi-block xz archives of `[Size]m\\|g` block size | `-ms` |\n| `outputDir` | `string` | Set Output directory | `-o` |\n| `overwrite` | `string` | Overwrite mode | `-ao` |\n| `password` | `string` | Set Password | `-p` |\n| `sfx` | `string` | Create SFX archive | `-sfx` |\n| `updateOptions` | `string` | Update options | `-u` |\n| `workingDir` | `string` | Set Working directory | `-w` |\n| `excludeArchive` | `string[]` | Exclude archive filenames | `-ax` |\n| `exclude` | `string[]` | Exclude filenames | `-x` |\n| `include` | `string[]` | Include filenames | `-i` |\n| `includeArchive` | `string[]` | Include archive filenames | `-ai` |\n| `method` | `string[]` | Set Compression Method | `-m` |\n| `outputStreams` | `string[]` | Set output stream for output/error/progress | `-bs` |\n| `volumes` | `string[]` | Create Volumes | `-v` |\n\n#### Special options\n\nThose options are not provided by 7-Zip but are features of this module.\n\n| Name | Type | Description |\n|-----------------|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|\n| `$progress` | `boolean` | Progress percentage gets fired. Shortcut for `{ outputStreams: ['b1'] }` Use if you want access to the `progress` event. Has an impact on performances. |\n| `$defer` | `boolean` | Create the stream but do not spawn child process |\n| `$childProcess` | [`ChildProcess`](https://nodejs.org/api/child_process.html#child_process_class_childprocess) | Attach an external child process to be parsed |\n| `$bin` | `string` | Path to an other 7-Zip binary. Default: `7z` |\n| `$cherryPick` | `string[]` | Some commands accepts more specific targets, see example above |\n| `$raw` | `string[]` | Pass raw arguments to the `child_process.spawn()`command |\n| `$spawnOptions` | [`Object`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | Pass `options` to the `child_process.spawn()`command |\n\n### Events\n\n#### Event: `data`\n\nThe `data` event is emitted for each processed file. The payload is an object. WARNING only the `data.file` proprety is guaranteed to be present\n\n```js\nmySevenStream.on('data', function (data) {\n console.log(data)\n // {\n // file: 'path/of/the/file/in/the/archive',\n // status: 'renamed|tested|updated|skipped|deleted|extracted',\n // attributes: '....A', size: 9, sizeCompressed: 3, (only list command)\n // hash: 'FEDC304F', size: 9 (only hash command)\n // techInfo: Map(8) { (only list command with `techInfo` switch)\n // 'Path' => 'DirHex/sub2/e825776890f2b',\n // 'Size' => '9',\n // 'Modified' => '2018-09-29 09:06:15',\n // 'Attributes' => 'A_ -rw-r--r--',\n // 'CRC' => 'FEDC304F',\n // 'Encrypted' => '-',\n // 'Method' => 'LZMA2:12',\n // 'Block' => '0'\n // }\n // }\n})\n```\n\n#### Event: `end`\n\nAn `.info` proprety can contain meta-data (type [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map))\n\n```js\nmyStream.info\n// Map {\n// '7-Zip [64] 16.02 ' => 'Copyright (c) 1999-2016 Igor Pavlov : 2016-05-21',\n// 'Creating archive' => './test/_tmp/txt-and-md-only.7z',\n// 'Items to compress' => '6',\n// 'Files read from disk' => '6',\n// 'Archive size' => '212 bytes (1 KiB)' }\n```\n\n#### Event: `error`\n\n```js\nmySevenStream.on('error', function (err) {\n // a standard error\n // `err.stderr` is a string that can contain extra info about the error\n})\n```\n\n## Advanced usage\n\n### Compression method\n\nUsing the CLI, compression is done like this:\n\n```sh\n# adds *.exe and *.dll files to solid archive archive.7z using LZMA method\n# with 2 MB dictionary and BCJ filter.\n7z a archive.7z *.exe -m0=BCJ -m1=LZMA:d=21\n```\n\nUsing this module:\n\n```js\nconst compress = Seven.add('archive.7z', '*.exe', {\n method: ['0=BCJ', '1=LZMA:d=21']\n})\n```\n\n### Raw inputs\n\n> Thanks to sketchpunk #9 for this one\n\nSometimes you just want to use the lib as the original command line. For\ninstance you want to apply to switches with different values. You can use the\n custom `$raw` key in your `options` object and pass it an *Array* of\nvalues.\n\n```js\nconst compress = Seven.add('archive.7z', '*.gif', {\n $raw: [ '-i!*.jpg', '-i!*.png' ], // only images\n})\n```\n\n### Emoji and Unicode\n\nDue to a `7z` limitation emojis and special characters can't be used as values\nwhen passed to an `option` object (ex: password). But they can be used in\narchive, filenames and destinations.\n\nUse the `{ charset: 'UTF-8' }` for special characters.\n\n### Log level\n\nThe default log level (`-bb` switch) is set to:\n\n> 3 :show information about additional operations (Analyze, Replicate) for \"Add\" / \"Update\" operations.\n\nIt's a base feature of `node-7z` and is required for the module to work as\nexpected. A diffrent value should not be used.\n\n### Security\n\nValues given by the package are not sanitized, you just get the raw output from\nthe 7-Zip binary. Remember to never trust user input and sanitize accordingly.\n\n### External child process\n\nYou can pipe a child procress from an other source and pass it to `node-7z`. An\nuse case may be that the 7-Zip process runs on an other machine and the sdtio is\npiped in the application.\n\n```js\nconst external = // an external child process\nconst myStream = Seven.add('dummy', 'dummy', {\n $defer: true\n})\nmyStream.on('data', data => yourLogicWith(data))\nSeven.listen(myStream)\n```\n\n***\nWith :heart: from [quentinrossetti](http://quentinrossetti.me/)\n\n[david-url]: https://david-dm.org/quentinrossetti/node-7z\n[david-image]: http://img.shields.io/david/quentinrossetti/node-7z.svg\n[circleci-url]: https://circleci.com/gh/quentinrossetti/workflows/node-7z\n[circleci-image]: https://img.shields.io/circleci/project/github/quentinrossetti/node-7z.svg?logo=linux\n[appveyor-url]: https://ci.appveyor.com/project/quentinrossetti/node-7z\n[appveyor-image]: https://img.shields.io/appveyor/ci/quentinrossetti/node-7z.svg?logo=windows\n[npm-url]: https://www.npmjs.org/package/node-7z\n[npm-image]: http://img.shields.io/npm/v/node-7z.svg\n[coverage-url]: https://codeclimate.com/github/quentinrossetti/node-7z\n[coverage-image]: https://img.shields.io/codeclimate/coverage/quentinrossetti/node-7z.svg\n[maintainability-url]: https://codeclimate.com/github/quentinrossetti/node-7z\n[maintainability-image]: https://img.shields.io/codeclimate/maintainability/quentinrossetti/node-7z.svg\n[vulnerabilities-image]: https://snyk.io/test/github/quentinrossetti/node-7z/badge.svg?targetFile=package.json\n[vulnerabilities-url]: https://snyk.io/test/github/quentinrossetti/node-7z?targetFile=package.json\n","maintainers":[{"name":"quentinrossetti","email":"code@bleu.gdn"}],"time":{"modified":"2022-06-21T11:36:05.453Z","created":"2014-08-25T10:38:41.321Z","0.0.1":"2014-08-25T10:38:41.321Z","0.0.2":"2014-08-25T13:37:27.735Z","0.1.0":"2014-08-26T12:16:10.800Z","0.1.1":"2014-08-26T12:21:07.549Z","0.1.2":"2014-10-20T17:09:00.704Z","0.1.3":"2014-10-23T18:15:04.769Z","0.2.0":"2014-10-24T16:01:16.791Z","0.3.0":"2015-02-06T12:47:54.981Z","0.4.0":"2015-12-06T21:32:47.862Z","1.0.0":"2018-12-05T21:11:44.857Z","1.0.1":"2018-12-29T17:49:20.093Z","1.1.0":"2019-02-10T20:03:38.755Z","1.1.1":"2019-07-17T17:18:48.514Z","2.0.2":"2019-10-27T20:37:28.860Z","2.0.1":"2019-10-27T20:37:57.945Z","2.0.0":"2019-10-27T20:38:06.896Z","2.0.3":"2019-10-27T20:44:45.300Z","2.0.4":"2019-11-23T16:00:08.497Z","2.0.5":"2019-12-24T11:01:42.556Z","2.1.0":"2020-02-15T12:33:27.728Z","2.1.1":"2020-02-15T12:45:07.019Z","2.1.2":"2020-10-11T20:52:36.879Z","3.0.0":"2021-07-11T19:23:48.649Z"},"homepage":"https://github.com/quentinrossetti/node-7zip.git","keywords":["node","7z","7za","7zr","p7zip","7zip","wrapper"],"repository":{"type":"git","url":"git+https://github.com/quentinrossetti/node-7z.git"},"contributors":[],"author":{"name":"Quentin Rossetti","email":"quentin.rossetti@gmail.com"},"bugs":{"url":"https://github.com/quentinrossetti/node-7zip/issues"},"license":"ISC","readmeFilename":"README.md","users":{"godion":true,"nickeljew":true,"td3":true}}