Super-winrar NPM

Super WinRAR

Get super powers with nodejs+winrar

This is a rar cli Api implementation in JavaScript. It uses 0 depencies ;)

Create or read an existing rar file and do anything you want with his content like extract, read, rename, remove or even append more content!

Addendum: Super WinRar deal with huge rar files or operations like a charm ❤️

Installation

Install with npm

npm i super-winrar@latest

Usage

Create a Rar object and do stuffs..

const Rar = require('super-winrar');

// create a rar constructor with file path! (created if not exists)
const rar = new Rar('package.rar');

// handle erros, otherwise will throw an exception!
rar.on('error', err => console.log(err.message));

// will be fired on rar start and every method if password is not set so u can use once to listen for only "start" fire!
rar.once('password', async () => {
  console.log('Rar requested password!');
  // every method works with async/await or callback methods!
  const isCorrect = await rar.setPassword('abc'); // rar.setPassword('abc', isCorrect => {..})
  if (!isCorrect) {
    console.log('wrong password!');
    return rar.close(); // unique sync method without any callback, clearing all events and structure
  };
  console.log('password match!');
});

// will be fired only once after succesfull read the document (not fired if password is required but is fired once after correct password is set!)
rar.once('ready', async () => {
  rar.list((err, files) => {  // const files = await rar.list()
	if (err) return console.log(err.message);
	console.log('files', files);
  });

  try {
    // Read file contents inside rar as Buffer!
    const buffer = await rar.getFileBuffer('package.json'); // rar.getFileBuffer('New folder/index.js', (err, buffer) => {..})
    console.log(buffer.length); //271
    console.log(typeof buffer === 'object'); //true
  } catch (e) {
    console.log(e.message);
  }
});

// Every method automatically waits for "ready" fired and also got an err if password is required
// will extract "package.json" file to "extractionfolder", if files os not specified will extract everything!
rar.extract({path: './extractionfolder', files: ['package.json']}, err => { // await rar.extract({path: './extractionfolder'})
  if (err) return console.log('extraction error', err.message);
  console.log('extraction completed successfully..');
});

// Read file contents insided rar as Buffer With ReadableStream (good for avoiding memory leaks with large files)
rar.getFileBufferStream('package.json', (err, bufferStream) => {
  if (err) return console.log(err.message);
  let buffer = new Buffer.from([])
  bufferStream.on('data', data => {
    buffer = new Buffer.concat([buffer, data])
  });
  bufferStream.on('error', error => {
    console.log('streaming err', error.message)
    // handle streaming error
  });
  bufferStream.once('end', () => console.log('buffer size', buffer.length)); //271
});

Constructor

Rar

Create a new rar document if not exists or read and return the rar document;

path: the path of destination ".rar" file. required

new Rar (path: string)

Exemple:

const rar = new Rar('myRar.rar');

Events

ready

Will be fired only once after succesfull read the document (not fired if password is required but fired after correct password set!)

Exemple:

rar.on('ready', async () => {
  // do something..
});

password

Will be fired on rar start and every method if password is not set so u can use once to listen for only "start" fire;

Exemple:

rar.on('password', async () => {
  console.log('document has requested password!')
});

error

Will be fired case got any error while opening or creating the rar;

Exemple:

rar.on('error', async (error: object) => {
  console.log(error.message);
});

Methods

setPassword()

Set the document password, if password is correct then all next methods will use the same password;

parameters:

password required
callback optional (isCorrect)

setPassword(password: string, callback(isCorrect: boolean): function => {});

Exemple:

rar.setPassword('abc', async (isCorrect) => {
  if (!isCorrect) return console.log('Password is not correct :(');
  console.log('Password correct!');
});

// or async/await

const anyAsyncFunction = async () => {
  const isCorrect = await rar.setPassword('abc');
  if (isCorrect) console.log('Correct password!');
};

list()

List all document folders and files recursively;

parameters:

opts optional
callback optional (isCorrect)

list(opts: object, (err: error, files: object): function => {});

Exemple:

rar.list((err, files) => {
  if (err) return console.log(err.message);
  console.log('files', files);
});

// or async/await

const anyAsyncFunction = async () => {
  const files = await rar.list();
  console.log('files', files);
};

files:

[
  {
	"path": "index.js",
	"isDirectory": false,
	"modified": 2022-03-03T13:16:27.000Z,
	"compression": "RAR 5.0(v50) -m3 -md=1M",
	"size": 2253,
	"packedSize": 773,
	"ratio": "34%",
	"CRC32": "38A5A912"
  },
  {
	"path": "New folder",
	"isDirectory": true,
	"modified": 2022-03-03T13:16:27.000Z,
	"compression": "RAR 5.0(v50) -m0 -md=0K"
  }
]

extract()

Extract specified files/folders or if not specified all document got extract to destination path;

parameters:

opts optional
callback optional (err)

extract(opts: object, (err: error): function => {});

Exemple:

rar.extract({path: './extractToThisFolder', files: ['fileInsideRar.txt', 'folderInsideRar']}, async (err) => {
  if (err) return console.log(err.message);
  console.log('extraction completed!');
});

// or async/await

const anyAsyncFunction = async () => {
  await rar.extract({path: './extractToThisFolder'});
  console.log('Extracted all files!');
};

getFileBuffer()

Read file content inside rar as Buffer;

parameters:

pathInsideRar required
callback optional (err, buffer)

getFileBuffer(pathInsideRar: string, (err: error, buffer: object): function => {});

Exemple:

rar.getFileBuffer('fileInsideRar.txt', async (err, buffer) => {
  if (err) return console.log(err.message);
  console.log('File size is', buffer.length);
  console.log('File data', buffer.toString());
});

// or async/await

const anyAsyncFunction = async () => {
  const buffer = await rar.getFileBuffer('fileInsideRar.txt');
  console.log(buffer.toString('utf-8')) // file content as 'utf-8 string'
};

getFileBufferStream()

Read file content inside rar as Buffer but the Buffer "data" is sent as Readable stream;

parameters:

pathInsideRar required
callback optional (err, stream)

getFileBufferStream(pathInsideRar: string, (err: error, stream: object): function => {});

Exemple:

rar.getFileBufferStream('fileInsideRar.txt', async (err, bufferStream) => {
  if (err) return console.log(err.message);
  let buffer = new Buffer.from([])
  bufferStream.on('data', data => {
    buffer = new Buffer.concat([buffer, data])
  });
  // handle streaming error
  bufferStream.on('error', error => {
    console.log('streaming err', error.message)
  });
  bufferStream.once('end', () => {
    console.log('File size is', buffer.length);
    console.log('File data', buffer.toString());
  });
});

// or async/await

const anyAsyncFunction = async () => {
  const stream = await rar.getFileBufferStream('fileInsideRar.txt');
  bufferStream.on('data', data => {
    // do something
  })
};

append()

Append a file/folder to rar document, if is a folder then all his subdirectories and files will be append to document;

parameters:

files required
callback optional (err)

append(files: object, (err: error): function => {});

Exemple:

rar.append(['package.json', 'node_modules'], async (err) => {
  if (err) return console.log(err.message);
  console.log('Items append to document!');
});

// or async/await

const anyAsyncFunction = async () => {
  await rar.append(['index.js'])
};

remove()

Remove a file/folder from rar document, if is a folder then all his subdirectories and files will be removed from document, if all document files got removed then he got deleted;

parameters:

files required
callback optional (err)

remove(files: object, (err: error): function => {});

Exemple:

rar.remove(['package.json', 'node_modules'], async (err) => {
  if (err) return console.log(err.message);
  console.log('Items removed from document!');
});

// or async/await

const anyAsyncFunction = async () => {
  await rar.remove(['index.js'])
};

rename()

Rename a file/folder inside the rar document;

parameters:

oldpath required
newPath required
callback optional (err)

rename(oldpath: string, newPath: string, (err: error): function => {});

Exemple:

rar.rename(['package.json', 'package.txt'], async (err) => {
  if (err) return console.log(err.message);
  console.log('File inside rar package.json renamed to package.txt!');
});

// or async/await

const anyAsyncFunction = async () => {
  await rar.rename(['index.js', 'index.ts'])
};