archiver - npm Package Compare versions
Comparing version 0.20.0 to 0.21.0
37
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; |
322
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. | ||
| */ |
| /** | ||
| * 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 | ||
| */ |
| /** | ||
| * 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. | ||
| */ |
| /** | ||
| * 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. | ||
| */ |
| { | ||
| "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", |
208
README.md
@@ -1,7 +0,5 @@ | ||
| # Archiver v0.20.0 [](https://travis-ci.org/archiverjs/node-archiver) [](https://ci.appveyor.com/project/ctalkington/node-archiver/branch/master) | ||
| # Archiver v0.21.0 [](https://travis-ci.org/archiverjs/node-archiver) [](https://ci.appveyor.com/project/ctalkington/node-archiver/branch/master) | ||
| a streaming interface for archive generation | ||
| [](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 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by20.56%
37427
- Lines of code
- increased by70.18%
1113
Worsened metrics
- Dev dependency count
- increased by28.57%
9
- Number of lines in readme file
- decreased by-82.93%
42
No dependency changes