231 lines
9.3 KiB
Markdown
231 lines
9.3 KiB
Markdown
# node-unrar-js
|
|
|
|
[](https://github.com/YuJianrong/node-unrar.js/actions?query=workflow%3ABuild)
|
|
[](https://badge.fury.io/js/node-unrar-js)
|
|
[](https://opensource.org/licenses/mit-license.php)
|
|
[](https://www.typescriptlang.org/)
|
|
|
|
`node-unrar.js` is a npm module to extract rar archive in pure JavaScript. It's combined by a Javascript adoption layer and JavaScript unRar library compiled by [Emscripten](http://emscripten.org/) from the [C++ unrar library](http://www.rarlab.com/rar/unrarsrc-6.1.7.tar.gz) which hosted on <http://www.rarlab.com/rar_add.htm> .
|
|
|
|
## Installation
|
|
|
|
You can install the module via `npm`:
|
|
|
|
```bash
|
|
npm install node-unrar-js
|
|
```
|
|
|
|
## Features
|
|
|
|
- Fully support for RAR archive, because it comes from the official source code.
|
|
- Unicode support, for both comment and file path/name.
|
|
- API for Extraction to both memory and file system.
|
|
- Both Commonjs module (for nodejs) and ES2015 module (for webpack) are supported.
|
|
|
|
## Unsupported Features
|
|
|
|
- Volume archives are not supported.
|
|
- Synchronize File System IO functions are used in File Extraction.
|
|
|
|
## API to create the extractor
|
|
|
|
- `async function createExtractorFromData(options: ExtractorFromDataOptions): Promise<Extractor<Uint8Array>>` - Create the in Memory Extractor
|
|
|
|
Options `ExtractorFromDataOptions`:
|
|
|
|
- `data: ArrayBuffer` : ArrayBuffer object of the RAR archive file
|
|
- `password?: string` : _Optional_ password
|
|
- `wasmBinary? ArrayBuffer;` : _Optional_ Use in browser/webpack, the wasm binary must be loaded in the code and send to this function to load the wasm code
|
|
|
|
- `async function createExtractorFromFile(options: ExtractorFromFileOptions): Promise<Extractor>` - Get the File Extractor
|
|
|
|
Options `ExtractorFromFileOptions`:
|
|
|
|
- `filepath: string` : File path of the RAR archive file
|
|
- `targetPath?: string` : _Optional_ target folder
|
|
- `password?: string` : _Optional_ password
|
|
- `filenameTransform?: (filename: string) => string`: _Optional_ transform the file name before it's created on file system
|
|
- `wasmBinary? ArrayBuffer;` : _Optional_ Use in nodejs/webpack, the wasm binary must be loaded in the code and send to this function to load the wasm code in webpack based nodejs project (please read [Used in Webpack-bundled NodeJS Project](#use-in-webpack-bundled-nodejs-project) for more details).
|
|
|
|
_Node_: This function is not available in EM2015 Module since the EM2015 Module is used for webpack in Browser.
|
|
|
|
## API of the extractor
|
|
|
|
- `getFileList(): ArcList` : Get the file header and file list of the archive.
|
|
|
|
Members in `ArcList`:
|
|
|
|
- `arcHeader: ArcHeader` : The header of the archive
|
|
- `fileHeaders: Generator<FileHeader>` : The iterator of the `FileHeader` objects
|
|
|
|
```js
|
|
{
|
|
arcHeader: {
|
|
comment: "",
|
|
flags: {
|
|
authInfo: false,
|
|
headerEncrypted: false,
|
|
lock: false,
|
|
recoveryRecord: false,
|
|
solid: false,
|
|
volume: false,
|
|
},
|
|
}, fileHeaders: (Iterator)
|
|
{
|
|
crc: 0,
|
|
flags: {
|
|
directory: false,
|
|
encrypted: false,
|
|
solid: false,
|
|
},
|
|
method: "Storing",
|
|
name: "FileName",
|
|
packSize: 0,
|
|
time: "2017-04-03T10:41:42.000",
|
|
unpSize: 0,
|
|
unpVer: "2.9",
|
|
comment: "",
|
|
},
|
|
}
|
|
```
|
|
|
|
- `extract(options: ExtractOptions)`: Extract the files.
|
|
- Options `ExtractOptions`:
|
|
- `files?: string[] | ((fileHeader: FileHeader) => boolean)` _Optional_ Extract all the files if `files` is empty
|
|
- `string[]`: Extract the specific files only
|
|
- `(fileHeader: FileHeader) => boolean`: Extract only the filtered file (_eg. extract only the files without password_).
|
|
- `password?: string`: _Optional_ password for the extracted files only (Different password can be applied to any single file in RAR archive).
|
|
- The return values are different for `createExtractorFromData` and `createExtractorFromFile`:
|
|
- `ArcFiles<Uint8Array>` for `createExtractorFromData`
|
|
- `ArcFiles` for `createExtractorFromFile`
|
|
- Members in `ArcFiles`:
|
|
- `arcHeader: ArcHeader` : The header of the archive
|
|
- `files: Generator<ArcFile>` : The iterator of the `ArcFile` objects
|
|
- Members in `ArcFile`:
|
|
- `fileHeader: FileHeader` : The header of the extracted file
|
|
- `extraction?: Uint8Array` : The extracted content of the file (`createExtractorFromData` only). If the `ArcFile` is a folder (`ArcFile.fileHeader.flags.directory` is `true`), the `extraction` will be undefined, otherwise it will be the content of the file (in `Uint8Array).
|
|
|
|
```js
|
|
{
|
|
arcHeader: {...} // Same as the arcHeader above
|
|
files: (Iterator)
|
|
{
|
|
fileHeader: {...} // Same as the fileHeader above
|
|
extraction?: Uint8Array // createExtractorFromData only
|
|
]
|
|
}
|
|
```
|
|
|
|
**Note: The returned iterators from the two apis are lazy, it means the file header/content will not be parsed/extracted if any file is not iterated yet.**
|
|
|
|
## Exception
|
|
|
|
The customized Error Object `UnrarError` will be thrown for any exception in extracting. The definition of the Object is:
|
|
|
|
```Typescript
|
|
class UnrarError extends Error {
|
|
reason: FailReason;
|
|
file?: string | undefined; // Will be filled for any exception in extraction of a file
|
|
}
|
|
```
|
|
|
|
The following code is used in the `FailReason`:
|
|
|
|
| FailReason | Message |
|
|
| --------------------- | ---------------------------------------------------------- |
|
|
| ERAR_NO_MEMORY | Not enough memory |
|
|
| ERAR_BAD_DATA | Archive header or data are damaged |
|
|
| ERAR_BAD_ARCHIVE | File is not RAR archive |
|
|
| ERAR_UNKNOWN_FORMAT | Unknown archive format |
|
|
| ERAR_EOPEN | File open error |
|
|
| ERAR_ECREATE | File create error |
|
|
| ERAR_ECLOSE | File close error |
|
|
| ERAR_EREAD | File read error |
|
|
| ERAR_EWRITE | File write error |
|
|
| ERAR_SMALL_BUF | Buffer for archive comment is too small, comment truncated |
|
|
| ERAR_UNKNOWN | Unknown error |
|
|
| ERAR_MISSING_PASSWORD | Password for encrypted file or header is not specified |
|
|
| ERAR_EREFERENCE | Cannot open file source for reference record |
|
|
| ERAR_BAD_PASSWORD | Wrong password is specified |
|
|
|
|
## Memory Leak
|
|
|
|
Note: although the return value `fileHeaders` and `files` are iterators, they must be traversed to the end! Otherwise the C++ object for archive extraction will not be destructed and cause memory leak.
|
|
|
|
## Example
|
|
|
|
```js
|
|
const fs = require("fs");
|
|
const unrar = require("node-unrar-js");
|
|
|
|
async function main() {
|
|
// Read the archive file into a typedArray
|
|
const buf = Uint8Array.from(fs.readFileSync("a.rar")).buffer;
|
|
const extractor = await unrar.createExtractorFromData({ data: buf });
|
|
|
|
const list = extractor.getFileList();
|
|
const listArcHeader = list.arcHeader; // archive header
|
|
const fileHeaders = [...list.fileHeaders]; // load the file headers
|
|
|
|
const extracted = extractor.extract({ files: ["1.txt"] });
|
|
// extracted.arcHeader : archive header
|
|
const files = [...extracted.files]; //load the files
|
|
files[0].fileHeader; // file header
|
|
files[0].extraction; // Uint8Array content, createExtractorFromData only
|
|
}
|
|
main();
|
|
```
|
|
|
|
## Demo in Webpack
|
|
|
|
This package can also be used in browser by Webpack, please visit the [demo project](https://github.com/YuJianrong/node-unrar.js/tree/master/demo/web) to see how to use it in webpack.
|
|
|
|
## Use in Webpack-bundled NodeJS Project
|
|
|
|
In most cases the exported ESModule is used in browser by Webpack, but in case if the NodeJs project (or an Electron project) is bundled by Webpack, the `wasmBinary` data must be loaded manually just like the browser by Webpack, it can be loaded like this:
|
|
|
|
```Typescript
|
|
import fs from 'fs';
|
|
import { createExtractorFromFile } from 'node-unrar-js/esm';
|
|
|
|
const wasmBinary = fs.readFileSync(require.resolve('node-unrar-js/esm/js/unrar.wasm'));
|
|
|
|
const extractor = await createExtractorFromFile({ wasmBinary, filepath: './WithComment.rar' });
|
|
|
|
// const list = extractor.getFileList();
|
|
```
|
|
|
|
Note: the package must be loaded from `'node-unrar-js/esm'` instead of `'node-unrar-js'` to enable the function `createExtractorFromFile` in ES Module.
|
|
|
|
## TypeScript
|
|
|
|
This module is written in [TypeScript](https://www.typescriptlang.org/), you can import it directly in TypeScript and get the benefit of static type checking and auto-complete of IDE.
|
|
|
|
## Development and Contribution
|
|
|
|
If you want to compile the module by yourself, please follow the steps below:
|
|
|
|
- Install the [docker](https://www.docker.com/)
|
|
|
|
- Download the c++ source of unRar library by:
|
|
|
|
`npm run downloadUnrarSrc`
|
|
|
|
- Build for debug:
|
|
|
|
`npm run build:debug`
|
|
|
|
- Build for release
|
|
|
|
`npm run build:release`
|
|
|
|
- Run Test
|
|
|
|
`npm run test`
|
|
|
|
## License
|
|
|
|
This module is licensed under MIT.
|
|
|
|
### [Changelog](https://github.com/YuJianrong/node-unrar.js/blob/master/CHANGELOG.md)
|