compressing

The missing compress and uncompress lib for node.

Currently uncompressing has not been supported yet.

Currently supported:

• tar
• gzip
• tgz
• zip

Install

npm install compressing

Usage

Compress a single file

Use gzip as an example, tar, tgz and zip is same as gzip.

promise style

const compressing = require('compressing');

// compress a file
compressing.gzip.compressFile('file/path/to/compress', 'path/to/destination.gz')
.then(compressDone)
.catch(handleError);

// compress a file buffer
compressing.gzip.compressFile(buffer, 'path/to/destination.gz')
.then(compressDone)
.catch(handleError);

// compress a stream
compressing.gzip.compressFile(stream, 'path/to/destination.gz')
.then(compressDone)
.catch(handleError);

stream style

const compressing = require('compressing');

new compressing.gzip.FileStream({ source: 'file/path/to/compress' })
.on('error', handleError)
.pipe(fs.createWriteStream('path/to/destination.gz'))
.on('error', handleError);

// It's a transform stream, so you can pipe to it
fs.createReadStream('file/path/to/compress')
.on('error', handleError)
.pipe(new compressing.gzip.FileStream())
.on('error', handleError)
.pipe(fs.createWriteStream('path/to/destination.gz'))
.on('error', handleError);

// You should take care of stream errors in caution, use multipipe to handle error in one place
const pipe = require('multipipe';)
const sourceStream = fs.createReadStream('file/path/to/compress')
const gzipStream = new compressing.gzip.FileStream();
const destStream = fs.createWriteStream('path/to/destination.gz');
pipe(sourceStream, gzipStream, destStream, err => handleError);

Compress a dir

Use tar as an example, tgz and zip is same as gzip.

Gzip only support compressing a single file. if you want to compress a dir with gzip, then you may need tgz instead.

promise style

const compressing = require('compressing');
compressing.tar.compressDir('dir/path/to/compress', 'path/to/destination.tar')
.then(compressDone)
.catch(handleError);

stream style

const compressing = require('compressing');

const tarStream = new compressing.tar.Stream();
tarStream.addEntry('dir/path/to/compress');

tarStream
.on('error', handleError)
.pipe(fs.createWriteStream('path/to/destination.tar'))
.on('error', handleError);

// You should take care of stream errors in caution, use multipipe to handle error in one place
const tarStream = new compressing.tar.Stream();
tarStream.addEntry('dir/path/to/compress');
const destStream = fs.createWriteStream('path/to/destination.tar');
pipe(tarStream, destStream, handleError);

Stream is very powerful, you can compress multiple entries in it;

const tarStream = new compressing.tar.Stream();
// dir
tarStream.addEntry('dir/path/to/compress');

// file
tarStream.addEntry('file/path/to/compress');

// buffer
tarStream.addEntry(buffer);

// stream
tarStream.addEntry(stream);

const destStream = fs.createWriteStream('path/to/destination.tar');
pipe(tarStream, destStream, handleError);

API

compressFile

Use this API to compress a single file. This is a convenient method, which wraps FileStream API below, but you can handle error in one place.

• gzip.compressFile(source, dest, opts)
• tar.compressFile(source, dest, opts)
• tgz.compressFile(source, dest, opts)
• zip.compressFile(source, dest, opts)

Params

• source {String|Buffer|Stream} - source to be compressed, could be a file path, buffer, or a readable stream
• dest {String|Stream} - compressing destination, could be a file path(eg. /path/to/xx.tgz), or a writable stream.
• opts {Object} - usually you don't need it

Returns a promise object.

compressDir

Use this API to compress a dir. This is a convenient method, which wraps Stream API below, but you can handle error in one place.

Note: gzip do not have a compressDir method, you may need tgz instead.

• tar.compressDir(dir, dest, opts)
• tgz.compressDir(dir, dest, opts)
• zip.compressDir(dir, dest, opts)

Params

• dir {String|Buffer|Stream} - dir path to be compressed
• dest {String|Stream} - compressing destination, could be a file path(eg. /path/to/xx.tgz), or a writable stream.
• opts {Object} - usually you don't need it

FileStream

The transform stream to compress a single file.

Note: If you are not very familiar with streams, just use compressFile() API, error can be handled in one place.

• new gzip.FileStream(opts)
• new tar.FileStream(opts)
• new tgz.FileStream(opts)
• new zip.FileStream(opts)

Common params:

• opts.source {String|Buffer|Stream} - source to be compressed, could be a file path, buffer, or a readable stream.

Gzip params:

• opts.zlib - {Object} gzip.FileStream uses zlib to compress, pass this param to control the behavior of zlib.

Tar params:

• opts.relativePath {String} - Adds a file from source into the compressed result file as opts.relativePath. Uncompression programs would extract the file from the compressed file as relativePath. If opts.source is a file path, opts.relativePath is optional, otherwise it's required.
• opts.size {Number} - Tar compression requires the size of file in advance. When opts.source is a stream, the size of it cannot be calculated unless load all content of the stream into memory(the default behavior, but loading all data into memory could be a very bad idea). Pass opts.size to avoid loading all data into memory, or a warning will be shown.
• opts.suppressSizeWarning {Boolean} - Pass true to suppress the size warning mentioned.

Tgz params:

tgz.FileStream is a combination of tar.FileStream and gzip.FileStream, so the params are the combination of params of tar and gzip.

Zip params:

• opts.relativePath {String} - Adds a file from source into the compressed result file as opts.relativePath. Uncompression programs would extract the file from the compressed file as relativePath. If opts.source is a file path, opts.relativePath is optional, otherwise it's required.
• opts.yazl {Object} - zip.FileStream compression uses yazl, pass this param to control the behavior of yazl.

Stream

The readable stream to compress anything as you need.

Note: If you are not very familiar with streams, just use compressFile() and compressDir() API, error can be handled in one place.

Gzip only support compressing a single file. So gzip.Stream is not available.

Constructor

• new tar.Stream()
• new tgz.Stream()
• new zip.Stream()

No options in all constructors.

Instance methods

• addEntry(entry, opts)

Params

• entry {String|Buffer|Stream} - entry to compress, cound be a file path, a dir path, a buffer, or a stream.
• opts.relativePath {String} - uncompression programs would extract the file from the compressed file as opts.relativePath. If entry is a file path or a dir path, opts.relativePath is optional, otherwise it's required.
• opts.ignoreBase {Boolean} - when entry is a dir path, and opts.ignoreBase is set to true, the compression will contain files relative to the path passed, and not with the path included.