Launch Week Day 5: Introducing Reachability for PHP.Learn More →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

archiver

Package Overview
Dependencies
Maintainers
1
Versions
83
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

archiver - npm Package Compare versions

Comparing version
0.20.0
 to
0.21.0
+30
-7
index.js
/**
* node-archiver
* Archiver Vending
*
* Copyright (c) 2015 Chris Talkington.
* Licensed under the MIT license.
* https://github.com/archiverjs/node-archiver/blob/master/LICENSE
* @ignore
* @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
* @copyright (c) 2012-2014 Chris Talkington, contributors.
*/
var Archiver = require('./lib/core');

@@ -13,6 +12,21 @@

var vending = module.exports = function(format, options) {
/**
* Dispenses a new Archiver instance.
*
* @constructor
* @param {String} format The archive format to use.
* @param {Object} options See [Archiver]{@link Archiver}
* @return {Archiver}
*/
var vending = function(format, options) {
return vending.create(format, options);
};
/**
* Creates a new Archiver instance.
*
* @param {String} format The archive format to use.
* @param {Object} options See [Archiver]{@link Archiver}
* @return {Archiver}
*/
vending.create = function(format, options) {

@@ -30,2 +44,9 @@ if (formats[format]) {

/**
* Registers a format for use with archiver.
*
* @param {String} format The name of the format.
* @param {Function} module The function for archiver to interact with.
* @return void
*/
vending.registerFormat = function(format, module) {

@@ -49,2 +70,4 @@ if (formats[format]) {

vending.registerFormat('tar', require('./lib/plugins/tar'));
vending.registerFormat('json', require('./lib/plugins/json'));
vending.registerFormat('json', require('./lib/plugins/json'));
module.exports = vending;
+311
-11
lib/core.js
/**
* node-archiver
* Archiver Core
*
* Copyright (c) 2012-2014 Chris Talkington, contributors.
* Licensed under the MIT license.
* https://github.com/archiverjs/node-archiver/blob/master/LICENSE-MIT
* @ignore
* @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
* @copyright (c) 2012-2014 Chris Talkington, contributors.
*/

@@ -19,3 +19,8 @@ var fs = require('fs');

var Archiver = module.exports = function(format, options) {
/**
* @constructor
* @param {String} format The archive format to use.
* @param {(CoreOptions|TransformOptions)} options See also {@link ZipOptions} and {@link TarOptions}.
*/
var Archiver = function(format, options) {
if (!(this instanceof Archiver)) {

@@ -61,2 +66,8 @@ return new Archiver(format, options);

/**
* Internal logic for `abort`.
*
* @private
* @return void
*/
Archiver.prototype._abort = function() {

@@ -72,2 +83,10 @@ this._state.aborted = true;

/**
* Internal helper for appending files.
*
* @private
* @param {String} filepath The source filepath.
* @param {EntryData} data The entry data.
* @return void
*/
Archiver.prototype._append = function(filepath, data) {

@@ -96,2 +115,8 @@ data = data || {};

/**
* Internal logic for `finalize`.
*
* @private
* @return void
*/
Archiver.prototype._finalize = function() {

@@ -110,2 +135,8 @@ if (this._state.finalizing || this._state.finalized || this._state.aborted) {

/**
* Checks the various state variables to determine if we can `finalize`.
*
* @private
* @return {Boolean}
*/
Archiver.prototype._maybeFinalize = function() {

@@ -124,2 +155,12 @@ if (this._state.finalizing || this._state.finalized || this._state.aborted) {

/**
* Appends an entry to the module.
*
* @private
* @fires Archiver#entry
* @param {(Buffer|Stream)} source
* @param {EntryData} data
* @param {Function} callback
* @return void
*/
Archiver.prototype._moduleAppend = function(source, data, callback) {

@@ -145,2 +186,8 @@ if (this._state.aborted) {

/**
* Fires when the entry's input has been processed and appended to the archive.
*
* @event Archiver#entry
* @type {EntryData}
*/
this.emit('entry', data);

@@ -153,2 +200,8 @@ this._entries.push(data);

/**
* Finalizes the module.
*
* @private
* @return void
*/
Archiver.prototype._moduleFinalize = function() {

@@ -165,2 +218,8 @@ if (typeof this._module.finalize === 'function') {

/**
* Pipes the module to our internal stream with error bubbling.
*
* @private
* @return void
*/
Archiver.prototype._modulePipe = function() {

@@ -172,2 +231,9 @@ this._module.on('error', this._onModuleError.bind(this));

/**
* Determines if the current module supports a defined feature.
*
* @private
* @param {String} key
* @return {Boolean}
*/
Archiver.prototype._moduleSupports = function(key) {

@@ -181,2 +247,8 @@ if (!this._module.supports || !this._module.supports[key]) {

/**
* Unpipes the module from our internal stream.
*
* @private
* @return void
*/
Archiver.prototype._moduleUnpipe = function() {

@@ -187,2 +259,10 @@ this._module.unpipe(this);

/**
* Normalizes entry data with fallbacks for key properties.
*
* @private
* @param {Object} data
* @param {fs.Stats} stats
* @return {Object}
*/
Archiver.prototype._normalizeEntryData = function(data, stats) {

@@ -194,2 +274,3 @@ data = util.defaults(data, {

mode: null,
prefix: null,
sourcePath: null,

@@ -206,2 +287,7 @@ stats: false

if (data.name) {
if (typeof data.prefix === 'string' && '' !== data.prefix) {
data.name = data.prefix + '/' + data.name;
data.prefix = null;
}
data.name = util.sanitizePath(data.name);

@@ -240,2 +326,9 @@

/**
* Error listener that re-emits error on to our internal stream.
*
* @private
* @param {Error} err
* @return void
*/
Archiver.prototype._onModuleError = function(err) {

@@ -245,2 +338,9 @@ this.emit('error', err);

/**
* Checks the various state variables after queue has drained to determine if
* we need to `finalize`.
*
* @private
* @return void
*/
Archiver.prototype._onQueueDrain = function() {

@@ -257,2 +357,10 @@ if (this._state.finalizing || this._state.finalized || this._state.aborted) {

/**
* Appends each queue task to the module.
*
* @private
* @param {Object} task
* @param {Function} callback
* @return void
*/
Archiver.prototype._onQueueTask = function(task, callback) {

@@ -268,2 +376,10 @@ if (this._state.finalizing || this._state.finalized || this._state.aborted) {

/**
* Performs a file stat and reinjects the task back into the queue.
*
* @private
* @param {Object} task
* @param {Function} callback
* @return void
*/
Archiver.prototype._onStatQueueTask = function(task, callback) {

@@ -300,2 +416,8 @@ if (this._state.finalizing || this._state.finalized || this._state.aborted) {

/**
* Unpipes the module and ends our internal stream.
*
* @private
* @return void
*/
Archiver.prototype._shutdown = function() {

@@ -306,2 +428,11 @@ this._moduleUnpipe();

/**
* Tracks the bytes emitted by our internal stream.
*
* @private
* @param {Buffer} chunk
* @param {String} encoding
* @param {Function} callback
* @return void
*/
Archiver.prototype._transform = function(chunk, encoding, callback) {

@@ -315,2 +446,10 @@ if (chunk) {

/**
* Updates and normalizes a queue task using stats data.
*
* @private
* @param {Object} task
* @param {fs.Stats} stats
* @return {Object}
*/
Archiver.prototype._updateQueueTaskWithStats = function(task, stats) {

@@ -335,2 +474,14 @@ if (stats.isFile()) {

/**
* Aborts the archiving process, taking a best-effort approach, by:
*
* - removing any pending queue tasks
* - allowing any active queue workers to finish
* - detaching internal module pipes
* - ending both sides of the Transform stream
*
* It will NOT drain any remaining sources.
*
* @return {this}
*/
Archiver.prototype.abort = function() {

@@ -346,2 +497,13 @@ if (this._state.aborted || this._state.finalized) {

/**
* Appends an input source (text string, buffer, or stream) to the instance.
*
* When the instance has received, processed, and emitted the input, the `entry`
* event is fired.
*
* @fires Archiver#entry
* @param {(Buffer|Stream|String)} source The input source.
* @param {EntryData} data See also {@link ZipEntryData} and {@link TarEntryData}.
* @return {this}
*/
Archiver.prototype.append = function(source, data) {

@@ -384,2 +546,28 @@ if (this._state.finalize || this._state.aborted) {

/**
* Appends multiple entries from passed array of src-dest mappings.
*
* A [lazystream]{@link https://github.com/jpommerening/node-lazystream} wrapper is
* used to prevent issues with open file limits.
*
* @deprecated 0.21.0
* @param {Object[]} mappings
* @param {(EntryData|Function)} mappings[].data See also {@link ZipEntryData}
* and {@link TarEntryData}.
* @param {(String|Array)} mappings[].src Pattern(s) to match, relative to the `cwd`.
* @param {String} mappings[].dest Destination path prefix.
* @param {String} mappings[].expand Process a dynamic src-dest file mapping.
* @param {String} mappings[].cwd All `src` matches are relative to (but don't include)
* this path. requires `expand`.
* @param {String} mappings[].ext Replace any existing extension with this value in
* generated `dest` paths. requires `expand`.
* @param {String} mappings[].extDot Used to indicate where the period indicating
* the extension is located. requires `expand`.
* @param {String} mappings[].flatten Remove all path parts from generated `dest`
* paths. requires `expand`.
* @param {*} mappings[].* See [node-glob]{@link https://github.com/isaacs/node-glob#properties}
* and [minimatch]{@link https://github.com/isaacs/minimatch#properties} documentation
* for additional properties.
* @return {this}
*/
Archiver.prototype.bulk = function(mappings) {

@@ -438,2 +626,11 @@ if (this._state.finalize || this._state.aborted) {

/**
* Appends a directory and its files, recursively, given its dirpath.
*
* @param {String} dirpath The source directory path.
* @param {String} destpath The destination path within the archive.
* @param {(EntryData|Function)} data See also [ZipEntryData]{@link ZipEntryData} and
* [TarEntryData]{@link TarEntryData}.
* @return {this}
*/
Archiver.prototype.directory = function(dirpath, destpath, data) {

@@ -474,3 +671,4 @@ if (this._state.finalize || this._state.aborted) {

var entryData = _.extend({}, data);
entryData.name = util.sanitizePath(destpath + '/' + file.relative);
entryData.name = file.relative;
entryData.prefix = destpath;
entryData.stats = file.stats;

@@ -502,2 +700,15 @@

/**
* Appends a file given its filepath using a
* [lazystream]{@link https://github.com/jpommerening/node-lazystream} wrapper to
* prevent issues with open file limits.
*
* When the instance has received, processed, and emitted the file, the `entry`
* event is fired.
*
* @param {String} filepath The source filepath.
* @param {EntryData} data See also [ZipEntryData]{@link ZipEntryData} and
* [TarEntryData]{@link TarEntryData}.
* @return {this}
*/
Archiver.prototype.file = function(filepath, data) {

@@ -519,2 +730,11 @@ if (this._state.finalize || this._state.aborted) {

/**
* Appends multiple files that match a [glob pattern]{@link https://github.com/isaacs/node-glob#glob-primer}.
*
* @param {String} pattern The glob pattern to match.
* @param {Object} options See [node-glob]{@link https://github.com/isaacs/node-glob#options}.
* @param {EntryData} data See also [ZipEntryData]{@link ZipEntryData} and
* [TarEntryData]{@link TarEntryData}.
* @return {this}
*/
Archiver.prototype.glob = function(pattern, options, data) {

@@ -527,3 +747,3 @@ this._pending++;

glob(pattern, options, function(err, files) {
var globber = glob(pattern, options, function(err, files) {
if (err) {

@@ -535,3 +755,10 @@ this.emit('error', err);

files.forEach(function(file) {
this._append(file, data);
entryData = _.extend({}, data);
if (options.cwd) {
entryData.name = file;
file = globber._makeAbs(file);
}
this._append(file, entryData);
}, this);

@@ -546,2 +773,12 @@

/**
* Finalizes the instance and prevents further appending to the archive
* structure (queue will continue til drained).
*
* The `end`, `close` or `finish` events on the destination stream may fire
* right after calling this method so you should set listeners beforehand to
* properly detect stream completion.
*
* @return {this}
*/
Archiver.prototype.finalize = function() {

@@ -567,3 +804,8 @@ if (this._state.aborted) {

// needs to be deprecated in 0.16/removed in 0.17
/**
* Sets the module format name used for archiving.
*
* @param {String} format The name of the format.
* @return {this}
*/
Archiver.prototype.setFormat = function(format) {

@@ -580,3 +822,8 @@ if (this._format) {

// needs to be deprecated in 0.16/removed in 0.17
/**
* Sets the module used for archiving.
*
* @param {Function} module The function for archiver to interact with.
* @return {this}
*/
Archiver.prototype.setModule = function(module) {

@@ -599,2 +846,7 @@ if (this._state.aborted) {

/**
* Returns the current length (in bytes) that has been emitted.
*
* @return {Number}
*/
Archiver.prototype.pointer = function() {

@@ -604,5 +856,53 @@ return this._pointer;

/**
* Middleware-like helper that has yet to be fully implemented.
*
* @private
* @param {Function} plugin
* @return {this}
*/
Archiver.prototype.use = function(plugin) {
this._streams.push(plugin);
return this;
};
};
module.exports = Archiver;
/**
* @typedef {Object} CoreOptions
* @global
* @property {Number} [statConcurrency=4] Sets the number of workers used to
* process the internal fs stat queue.
*/
/**
* @typedef {Object} TransformOptions
* @property {Boolean} [allowHalfOpen=true] If set to false, then the stream
* will automatically end the readable side when the writable side ends and vice
* versa.
* @property {Boolean} [readableObjectMode=false] Sets objectMode for readable
* side of the stream. Has no effect if objectMode is true.
* @property {Boolean} [writableObjectMode=false] Sets objectMode for writable
* side of the stream. Has no effect if objectMode is true.
* @property {Boolean} [decodeStrings=true] Whether or not to decode strings
* into Buffers before passing them to _write(). `Writable`
* @property {String} [encoding=NULL] If specified, then buffers will be decoded
* to strings using the specified encoding. `Readable`
* @property {Number} [highWaterMark=16kb] The maximum number of bytes to store
* in the internal buffer before ceasing to read from the underlying resource.
* `Readable` `Writable`
* @property {Boolean} [objectMode=false] Whether this stream should behave as a
* stream of objects. Meaning that stream.read(n) returns a single value instead
* of a Buffer of size n. `Readable` `Writable`
*/
/**
* @typedef {Object} EntryData
* @property {String} name Sets the entry name including internal path.
* @property {(String|Date)} [date=NOW()] Sets the entry date.
* @property {Number} [mode=D:0755/F:0644] Sets the entry permissions.
* @property {String} [prefix] Sets a path prefix for the entry name. Useful
* when working with methods like `directory` or `glob`.
* @property {fs.Stats} [stats] Sets the fs stat data for this entry allowing
* for reduction of fs stat calls when stat data is already known.
*/
+45
-6
lib/plugins/json.js
/**
* node-archiver
* JSON Format Plugin
*
* Copyright (c) 2012-2014 Chris Talkington, contributors.
* Licensed under the MIT license.
* https://github.com/archiverjs/node-archiver/blob/master/LICENSE-MIT
* @module plugins/json
* @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
* @copyright (c) 2012-2014 Chris Talkington, contributors.
*/

@@ -14,3 +14,7 @@ var inherits = require('util').inherits;

var Json = module.exports = function(options) {
/**
* @constructor
* @param {(JsonOptions|TransformOptions)} options
*/
var Json = function(options) {
if (!(this instanceof Json)) {

@@ -33,2 +37,11 @@ return new Json(options);

/**
* [_transform description]
*
* @private
* @param {Buffer} chunk
* @param {String} encoding
* @param {Function} callback
* @return void
*/
Json.prototype._transform = function(chunk, encoding, callback) {

@@ -38,2 +51,8 @@ callback(null, chunk);

/**
* [_writeStringified description]
*
* @private
* @return void
*/
Json.prototype._writeStringified = function() {

@@ -44,2 +63,10 @@ var fileString = JSON.stringify(this.files);

/**
* [append description]
*
* @param {(Buffer|Stream)} source
* @param {EntryData} data
* @param {Function} callback
* @return void
*/
Json.prototype.append = function(source, data, callback) {

@@ -71,5 +98,17 @@ var self = this;

/**
* [finalize description]
*
* @return void
*/
Json.prototype.finalize = function() {
this._writeStringified();
this.end();
};
};
module.exports = Json;
/**
* @typedef {Object} JsonOptions
* @global
*/
+71
-6
lib/plugins/tar.js
/**
* node-archiver
* TAR Format Plugin
*
* Copyright (c) 2012-2014 Chris Talkington, contributors.
* Licensed under the MIT license.
* https://github.com/archiverjs/node-archiver/blob/master/LICENSE-MIT
* @module plugins/tar
* @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
* @copyright (c) 2012-2014 Chris Talkington, contributors.
*/

@@ -13,3 +13,7 @@ var zlib = require('zlib');

var Tar = module.exports = function(options) {
/**
* @constructor
* @param {TarOptions} options
*/
var Tar = function(options) {
if (!(this instanceof Tar)) {

@@ -40,2 +44,9 @@ return new Tar(options);

/**
* [_onCompressorError description]
*
* @private
* @param {Error} err
* @return void
*/
Tar.prototype._onCompressorError = function(err) {

@@ -45,2 +56,10 @@ this.engine.emit('error', err);

/**
* [append description]
*
* @param {(Buffer|Stream)} source
* @param {TarEntryData} data
* @param {Function} callback
* @return void
*/
Tar.prototype.append = function(source, data, callback) {

@@ -77,2 +96,7 @@ var self = this;

/**
* [finalize description]
*
* @return void
*/
Tar.prototype.finalize = function() {

@@ -82,2 +106,7 @@ this.engine.finalize();

/**
* [on description]
*
* @return this.engine
*/
Tar.prototype.on = function() {

@@ -87,2 +116,9 @@ return this.engine.on.apply(this.engine, arguments);

/**
* [pipe description]
*
* @param {String} destination
* @param {Object} options
* @return this.engine
*/
Tar.prototype.pipe = function(destination, options) {

@@ -96,2 +132,7 @@ if (this.compressor) {

/**
* [unpipe description]
*
* @return this.engine
*/
Tar.prototype.unpipe = function() {

@@ -103,2 +144,26 @@ if (this.compressor) {

}
};
};
module.exports = Tar;
/**
* @typedef {Object} TarOptions
* @global
* @property {Boolean} [gzip=false] Compress the tar archive using gzip.
* @property {Object} [gzipOptions] Passed to [zlib]{@link https://nodejs.org/api/zlib.html#zlib_class_options}
* to control compression.
* @property {*} [*] See [tar-stream]{@link https://github.com/mafintosh/tar-stream} documentation for additional properties.
*/
/**
* @typedef {Object} TarEntryData
* @global
* @property {String} name Sets the entry name including internal path.
* @property {(String|Date)} [date=NOW()] Sets the entry date.
* @property {Number} [mode=D:0755/F:0644] Sets the entry permissions.
* @property {String} [prefix] Sets a path prefix for the entry name. Useful
* when working with methods like `directory` or `glob`.
* @property {fs.Stats} [stats] Sets the fs stat data for this entry allowing
* for reduction of fs stat calls when stat data is already known.
* @property {Boolean} [store=ZipOptions.store] Sets the compression method to STORE.
*/
+53
-6
lib/plugins/zip.js
/**
* node-archiver
* ZIP Format Plugin
*
* Copyright (c) 2012-2014 Chris Talkington, contributors.
* Licensed under the MIT license.
* https://github.com/archiverjs/node-archiver/blob/master/LICENSE-MIT
* @module plugins/zip
* @license [MIT]{@link https://github.com/archiverjs/node-archiver/blob/master/LICENSE}
* @copyright (c) 2012-2014 Chris Talkington, contributors.
*/

@@ -11,3 +11,7 @@ var engine = require('zip-stream');

var Zip = module.exports = function(options) {
/**
* @constructor
* @param {ZipOptions} options
*/
var Zip = function(options) {
if (!(this instanceof Zip)) {

@@ -30,2 +34,8 @@ return new Zip(options);

/**
* @param {(Buffer|Stream)} source
* @param {ZipEntryData} data
* @param {Function} callback
* @return void
*/
Zip.prototype.append = function(source, data, callback) {

@@ -35,2 +45,5 @@ this.engine.entry(source, data, callback);

/**
* @return void
*/
Zip.prototype.finalize = function() {

@@ -40,2 +53,5 @@ this.engine.finalize();

/**
* @return this.engine
*/
Zip.prototype.on = function() {

@@ -45,2 +61,5 @@ return this.engine.on.apply(this.engine, arguments);

/**
* @return this.engine
*/
Zip.prototype.pipe = function() {

@@ -50,4 +69,32 @@ return this.engine.pipe.apply(this.engine, arguments);

/**
* @return this.engine
*/
Zip.prototype.unpipe = function() {
return this.engine.unpipe.apply(this.engine, arguments);
};
};
module.exports = Zip;
/**
* @typedef {Object} ZipOptions
* @global
* @property {String} [comment] Sets the zip archive comment.
* @property {Boolean} [store=false] Sets the compression method to STORE.
* @property {Object} [zlib] Passed to [zlib]{@link https://nodejs.org/api/zlib.html#zlib_class_options}
* to control compression.
* @property {*} [*] See [zip-stream]{@link https://github.com/archiverjs/node-zip-stream} documentation for additional properties.
*/
/**
* @typedef {Object} ZipEntryData
* @global
* @property {String} name Sets the entry name including internal path.
* @property {(String|Date)} [date=NOW()] Sets the entry date.
* @property {Number} [mode=D:0755/F:0644] Sets the entry permissions.
* @property {String} [prefix] Sets a path prefix for the entry name. Useful
* when working with methods like `directory` or `glob`.
* @property {fs.Stats} [stats] Sets the fs stat data for this entry allowing
* for reduction of fs stat calls when stat data is already known.
* @property {Boolean} [store=ZipOptions.store] Sets the compression method to STORE.
*/
+4
-1
package.json
{
"name": "archiver",
"version": "0.20.0",
"version": "0.21.0",
"description": "a streaming interface for archive generation",

@@ -28,2 +28,3 @@ "homepage": "https://github.com/archiverjs/node-archiver",

"test": "mocha --reporter dot",
"gendocs": "jsdoc -c jsdoc.json readme.md",
"bench": "node benchmark/simple/pack-zip.js"

@@ -42,2 +43,3 @@ },

"devDependencies": {
"jsdoc": "~3.4.0",
"chai": "~3.4.0",

@@ -47,2 +49,3 @@ "mocha": "~2.3.3",

"mkdirp": "~0.5.0",
"minami": "~1.1.0",
"stream-bench": "~0.1.2",

@@ -49,0 +52,0 @@ "tar": "~2.2.1",

+2
-206
README.md

@@ -1,7 +0,5 @@

# Archiver v0.20.0 [![Build Status](https://travis-ci.org/archiverjs/node-archiver.svg?branch=master)](https://travis-ci.org/archiverjs/node-archiver) [![Build status](https://ci.appveyor.com/api/projects/status/38kqu3yp159nodxe/branch/master?svg=true)](https://ci.appveyor.com/project/ctalkington/node-archiver/branch/master)
# Archiver v0.21.0 [![Build Status](https://travis-ci.org/archiverjs/node-archiver.svg?branch=master)](https://travis-ci.org/archiverjs/node-archiver) [![Build status](https://ci.appveyor.com/api/projects/status/38kqu3yp159nodxe/branch/master?svg=true)](https://ci.appveyor.com/project/ctalkington/node-archiver/branch/master)
a streaming interface for archive generation
[![NPM](https://nodei.co/npm/archiver.png)](https://nodei.co/npm/archiver/)
## Install

@@ -22,206 +20,4 @@

#### Transform
Visit the [API documentation](http://archiverjs.com/docs) for a list of all methods available.
Inherits [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform) methods.
#### create(format, options)
Creates an Archiver instance based on the format (zip, tar, etc) passed. Parameters can be passed directly to `Archiver` constructor for convenience.
#### abort()
Aborts the archiving process, taking a best-effort approach, by:
* removing any pending queue tasks
* allowing any active queue workers to finish
* detaching internal module pipes
* ending both sides of the Transform stream
*It will NOT drain any remaining sources.*
#### append(input, data)
Appends an input source (text string, buffer, or stream) to the instance. When the instance has received, processed, and emitted the input, the `entry` event is fired.
Replaced `#addFile` in v0.5.
```js
archive.append('string', { name:'string.txt' });
archive.append(new Buffer('string'), { name:'buffer.txt' });
archive.append(fs.createReadStream('mydir/file.txt'), { name:'stream.txt' });
archive.append(null, { name:'dir/' });
```
#### bulk(mappings)
*As of v0.19, it is recommended to use the asynchronous [glob](#globpattern-options-data) method especially in server environments. `bulk` will likely be deprecated in a future release.*
Appends multiple entries from passed array of src-dest mappings. A [lazystream](https://github.com/jpommerening/node-lazystream) wrapper is used to prevent issues with open file limits.
Globbing patterns are supported through use of the bundled [file-utils](https://github.com/SBoudrias/file-utils) module.
The `data` property can be set (per src-dest mapping) to define data for matched entries.
```js
archive.bulk([
{ src: ['mydir/**'], data: { date: new Date() } },
{ src: ['mydir/**'], data: function(data) {
data.date = new Date();
return data;
}},
{ expand: true, cwd: 'mydir', src: ['**'], dest: 'newdir' }
]);
```
As of v0.15, the `data` property can also be a function that receives data for each matched entry and is expected to return it after making any desired adjustments.
For more detail on this feature, please see [BULK.md](https://github.com/archiverjs/node-archiver/blob/master/BULK.md).
#### directory(dirpath[, destpath, data])
Appends a directory and its files, recursively, given its dirpath. This is meant to be a simpler approach to something previously only possible with `bulk`. The use of `destpath` allows one to define a custom destination path within the resulting archive and `data` allows for setting data on each entry appended.
```js
// mydir/ -> archive.ext/mydir/
archive.directory('mydir');
// mydir/ -> archive.ext/abc/
archive.directory('mydir', 'abc');
// mydir/ -> archive.ext/
archive.directory('mydir', false, { date: new Date() });
archive.directory('mydir', false, function(data) {
data.date = new Date();
return data;
});
```
As of v0.15, the `data` property can also be a function that receives data for each entry and is expected to return it after making any desired adjustments.
#### file(filepath, data)
Appends a file given its filepath using a [lazystream](https://github.com/jpommerening/node-lazystream) wrapper to prevent issues with open file limits. When the instance has received, processed, and emitted the file, the `entry` event is fired.
```js
archive.file('mydir/file.txt', { name:'file.txt' });
```
#### glob(pattern, options, data)
Appends multiple files that match a [glob pattern](https://github.com/isaacs/node-glob#glob-primer). Supports passing [glob options](https://github.com/isaacs/node-glob#options) as a second parameter and entry data as a third parameter.
```js
archive.glob('directory/**/*', { nodir: true }, { date: new Date() });
```
#### finalize()
Finalizes the instance and prevents further appending to the archive structure (queue will continue til drained). The `end`, `close` or `finish` events on the destination stream may fire right after calling this method so you should set listeners beforehand to properly detect stream completion.
*You must call this method to get a valid archive and end the instance stream.*
#### pointer()
Returns the current byte length emitted by archiver. Use this in your end callback to log generated size.
#### use(plugin)
Add a plugin to the middleware stack. Currently this is designed for passing the module to use (replaces registerFormat/setFormat/setModule)
## Events
Inherits [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform) events.
#### entry
Fired when the entry's input has been processed and appended to the archive. Passes entry data as first argument.
## Zip
### Options
#### comment `string`
Sets the zip comment.
#### statConcurrency `number`
Sets the number of workers used to process the internal fs stat queue. Defaults to 4.
#### store `boolean`
If true, all entries will be archived without compression. Defaults to `false`.
#### zlib `object`
Passed to node's [zlib](http://nodejs.org/api/zlib.html#zlib_options) module to control compression. Options may vary by node version.
### Entry Data
#### name `string` `required`
Sets the entry name including internal path.
#### date `string|Date`
Sets the entry date. This can be any valid date string or instance. Defaults to current time in locale.
When using the `bulk` or `file` methods, fs stat data is used as the default value.
#### store `boolean`
If true, this entry will be archived without compression. Defaults to global `store` option.
#### comment `string`
Sets the entry comment.
#### mode `number`
Sets the entry permissions. Defaults to octal 0755 (directory) or 0644 (file).
When using the `bulk` or `file` methods, fs stat data is used as the default value.
#### stats `fs.Stats`
Sets the fs stat data for this entry. This allows for reduction of fs stat calls when stat data is already known.
## Tar
### Options
#### gzip `boolean`
Compresses the tar archive using gzip, default is false.
#### gzipOptions `object`
Passed to node's [zlib](http://nodejs.org/api/zlib.html#zlib_options) module to control compression. Options may vary by node version.
#### statConcurrency `number`
Sets the number of workers used to process the internal fs stat queue. Defaults to 4.
### Entry Data
#### name `string` `required`
Sets the entry name including internal path.
#### date `string|Date`
Sets the entry date. This can be any valid date string or instance. Defaults to current time in locale.
When using the `bulk` or `file` methods, fs stat data is used as the default value.
#### mode `number`
Sets the entry permissions. Defaults to octal 0755 (directory) or 0644 (file).
When using the `bulk` or `file` methods, fs stat data is used as the default value.
#### stats `fs.Stats`
Sets the fs stat data for this entry. This allows for reduction of fs stat calls when stat data is already known.
## Custom Formats

@@ -228,0 +24,0 @@