simple-archiver v1.0.1
Simple Archiver
Archive multiple files, directories, buffers, streams and strings; supports 'zip' and 'tar' formats; can output a Buffer (default), Stream or to a path.
Can extract archives from a path, Buffer or Stream to a specified path.
Install
npm install simple-archiver --save
Usage
Archive
var archive = require('simple-archiver').archive;
archive(path)
.then(archiveBuffer => console.log('Done! We should do something with the buffer.'))
.catch(console.log);
archive(['/path/file.txt', '/path/auto-detect-dir-or-file-type', '/and-so-on']); // .then(...).catch(...);
// You can include Buffers, Streams and Strings in the archive as well (giving them a name)
archive([
{ data: '/path/file', type: 'file', name: 'new-file-name' },
{ data: '/path/dir', type: 'directory', name: 'new-dir-name' },
{ data: buffer, type: 'buffer', name: 'file1' },
{ data: stream, type: 'stream', name: 'file2' },
{ data: 'string', type: 'string', name: 'file3' }
], {
format: 'tar',
output: '/path/archive.tar'
}); // we're making it a 'tar' archive and saving it to a path
For optimal performance, you would use objects specifying the type and name of each entry. While not optimal, the type can be determined automatically, but the name can only be determined for paths (files and directories).
Extract
var extract = require('simple-archiver').extract;
// archive can be a path (String), Buffer or Stream
let archive = '/myarchive.tar';
extract(archive, '/path', { format: 'tar' }) // the format is 'zip' by default, so you have to specify it for 'tar'
.then(() => console.log('Extraction finished!'))
.catch(console.log);
Details
archive (entries, options)
=> Promise
Resolves to an archive Buffer (default), Stream or path depending on the chosen output.
- entries
Array of Objects | Array of Strings | Object | String
Object properties:
data
- The data you wish to archive: file/directory path (String), Buffer, Stream or String (to save as a file);type
- (optional) Entry type: 'file', 'directory', 'other'; The type can be automatically determined (but if you know it, use it); Buffer, Stream and String are handled automatically and are classified here as 'other'; you can use any name instead of 'other' since it's the default;name
- (optional) The name the entry will have in the archive; may be a path within the archive (e.g. '/path/name'); Optional for 'file' and 'directory' (basenames are used by default), recommended for 'other' (a counter will be used if missing, starts at 0);
- options
(Optional) Object
Object properties:
format
- (optional) Archive format: 'zip' (default), 'tar';output
- (optional) Output type: 'buffer' (default), 'stream', '/path'; If you enter a path string, the archive will be saved there and the resolve value will be the path string;
extract (archive, destination, options)
=> Promise
Extraction has finished when the promise resolves
- archive
String | Buffer | Stream
The archive path (String), Buffer or Stream.
- destination
String
The path to save the archive contents to.
- options
(Optional) Object
Object properties:
format
- (optional) Archive format: 'zip' (default), 'tar';
Note: Extract doesn't know the format of your archive, so if it's not 'zip', remember to set it.
Extras
archiver
Used by archive() and provided to you if you need access to advanced options.
unzip & tar
Used by extract() and provided as unzip and tar from the module.
Note: Since unzip has been unmaintained for a very long time, it has been forked a number of times; this package uses a fork of a fork in order to keep things up to date and maintain a degree of control over its dependencies.
Issues & Features
You're welcome to make any feature requests, but remember that this package relies on the above three
Thanks
A big thank you to the above package creators and collaborators for making this possible.