CD2H gitForager

node-modules/compressing

Name: compressing

Owner: node_modules

Description: Everything you need for compressing and uncompressing

Created: 2016-12-14 08:37:34.0

Updated: 2018-05-20 03:27:00.0

Pushed: 2017-07-27 06:33:54.0

Homepage: null

Size: 48

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

compressing

The missing compressing and uncompressing lib for node.

Currently supported:

tar
gzip
tgz
zip

Install

install compressing

Usage

Compress a single file

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

promise style

t compressing = require('compressing');

ompress a file
ressing.gzip.compressFile('file/path/to/compress', 'path/to/destination.gz')
n(compressDone)
ch(handleError);

ompress a file buffer
ressing.gzip.compressFile(buffer, 'path/to/destination.gz')
n(compressDone)
ch(handleError);

ompress a stream
ressing.gzip.compressFile(stream, 'path/to/destination.gz')
n(compressDone)
ch(handleError);

stream style

t compressing = require('compressing');

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

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

ou should take care of stream errors in caution, use multipipe to handle error in one place
t pipe = require('multipipe';)
t sourceStream = fs.createReadStream('file/path/to/compress')
t gzipStream = new compressing.gzip.FileStream();
t destStream = fs.createWriteStream('path/to/destination.gz');
(sourceStream, gzipStream, destStream, 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

t compressing = require('compressing');
ressing.tar.compressDir('dir/path/to/compress', 'path/to/destination.tar')
n(compressDone)
ch(handleError);

stream style

t compressing = require('compressing');

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

tream
n('error', handleError)
ipe(fs.createWriteStream('path/to/destination.tar'))
n('error', handleError);

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

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

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

ile
tream.addEntry('file/path/to/compress');

uffer
tream.addEntry(buffer);

tream
tream.addEntry(stream);

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

Uncompress a file

promise style

t compressing = require('compressing');

ncompress a file
ressing.tgz.uncompress('file/path/to/uncompress.tgz', 'path/to/destination/dir')
n(uncompressDone)
ch(handleError);

ncompress a file buffer
ressing.tgz.uncompress(buffer, 'path/to/destination/dir')
n(uncompressDone)
ch(handleError);

ncompress a stream
ressing.tgz.uncompress(stream, 'path/to/destination/dir')
n(uncompressDone)
ch(handleError);

Note: tar, tgz and zip have the same uncompressing API as above: destination should be a path of a directory, while that of gzip is slightly different: destination must be a file or filestream.

And working with urllib is super easy. Let's download a tgz file and uncompress to a directory:

t urllib = require('urllib');
t targetDir = require('os').tmpdir();
t compressing = require('compressing');

ib.request('http://registry.npmjs.org/pedding/-/pedding-1.1.0.tgz', {
reaming: true,
llowRedirect: true,

n(result => compressing.tgz.uncompress(result.res, targetDir))
n(() => console.log('uncompress done'))
ch(console.error);

stream style

t compressing = require('compressing');
t mkdirp = require('mkdirp');

tion onEntry(header, stream, next) => {
ream.on('end', next);

 header.type => file | directory
 header.name => path name

 (header.type === 'file') {
stream.pipe(fs.createWriteStream(path.join(destDir, header.name)));
else { // directory
mkdirp(path.join(destDir, header.name), err => {
  if (err) return handleError(err);
  stream.resume();
});



compressing.tgz.UncompressStream({ source: 'file/path/to/uncompress.tgz' })
n('error', handleError)
n('finish', handleFinish) // uncompressing is done
n('entry', onEntry);

t's a writable stream, so you can pipe to it
reateReadStream('file/path/to/uncompress')
n('error', handleError)
ipe(new compressing.tgz.UncompressStream())
n('error', handleError)
n('finish', handleFinish) // uncompressing is done
n('entry', onEntry);

Note: tar, tgz and zip have the same uncompressing streaming API as above: it's a writable stream, and entries will be emitted while uncompressing one after one another, while that of gzip is slightly different: gzip.UncompressStream is a transform stream, so no entry event will be emitted and you can just pipe to another stream

This constrants is brought by Gzip algorithm itself, it only support compressing one file and uncompress one file.

compressing.gzip.UncompressStream({ source: 'file/path/to/uncompress.gz' })
n('error', handleError)
ipe(fs.createWriteStream('path/to/dest/file'))
n('error', 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(source, dest, opts)
tgz.compressDir(source, dest, opts)
zip.compressDir(source, dest, opts)

Params

source {String|Buffer|Stream} - source 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

uncompress

Use this API to uncompress a file. This is a convenient method, which wraps UncompressStream API below, but you can handle error in one place. RECOMMANDED.

tar.uncompress(source, dest, opts)
tgz.uncompress(source, dest, opts)
zip.uncompress(source, dest, opts)
gzip.uncompress(source, dest, opts)

Params

source {String|Buffer|Stream} - source to be uncompressed
dest {String|Stream} - uncompressing destination. When uncompressing tar, tgz and zip, it should be a directory path (eg. /path/to/xx). When uncompressing gzip, it should be a file path 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.

UncompressStream

The writable stream to uncompress anything as you need.

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

Gzip only support compressing and uncompressing one single file. So gzip.UncompressStream is a transform stream which is different from others.

Constructor

new gzip.UncompressStream(opts)
new tar.UncompressStream(opts)
new tgz.UncompressStream(opts)
new zip.UncompressStream(opts)

Common params:

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

CAUTION for zip.UncompressStream

Due to the design of the .zip file format, it's impossible to interpret a .zip file without loading all data into memory.

Although the API is streaming style(try to keep it handy), it still loads all data into memory.

https://github.com/thejoshwolfe/yauzl#no-streaming-unzip-api

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.