Archiver API
#
Archiver Class#
constructor#
Parametersformat
- String - The archive format to use.options
- Object
#
OptionsThe options
object may include the following properties as well as all Stream.duplex options:
#
Core OptionsstatConcurrency
- Number (default 4) - Sets the number of workers used to process the internal fs stat queue.
#
ZIP Optionscomment
- String - Sets the zip archive comment.forceLocalTime
- Boolean - Forces the archive to contain local file times instead of UTC.forceZip64
- Boolean - Forces the archive to contain ZIP64 headers.namePrependSlash
- Boolean - Prepends a forward slash to archive file paths.store
- Boolean - Sets the compression method to STORE.zlib
- Object - Passed to zlib to control compression.
#
TAR Optionsgzip
- Boolean - Compress the tar archive using gzip.gzipOptions
- Object - Passed to zlib to control compression.
See tar-stream documentation for additional properties.
#
abortAborts 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.
#
ParametersNone
#
appendAppends 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.
#
Parameterssource
- Buffer | Stream | String - The input source.data
- Object - The entry data.
#
directoryAppends a directory and its files, recursively, given its dirpath.
#
Parametersdirpath
- String - The source directory path.destpath
- String - The destination path within the archive.data
- Object - The entry data.
#
fileAppends a file given its filepath using a lazystream wrapper to prevent issues with open file limits.
When the instance has received, processed, and emitted the file, the entry event is fired.
#
Parametersfilepath
- String - The source filepath.data
- Object - The entry data.
#
finalizeFinalizes 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.
#
ParametersNone
#
globAppends multiple files that match a glob pattern.
#
Parameterspattern
- String - The glob pattern to match.options
- Object - See node-readdir-glob.data
- Object - The entry data.
#
pointerReturns the current length (in bytes) that has been emitted.
#
ParametersNone
#
setFormatSets the module format name used for archiving.
#
Parametersformat
- String - The name of the format.
#
setModuleSets the module used for archiving.
#
Parametersmodule
- Function - The function for archiver to interact with.
#
symlinkAppends a symlink to the instance.
This does NOT interact with filesystem and is used for programmatically creating symlinks.
#
Parametersfilepath
- String - The symlink path (within archive).target
- String - The target path (within archive).mode
- Number - The entry permissions.
#
Events#
Event: entryFires when the entry's input has been processed and appended to the archive.
The entry
event object contains the following properties:
#
Event: progressThe progress
event object contains the following properties:
entries
- Object - An object containing the following properties:total
- Number - The number of entries that have been appended.processed
- Number - The number of entries that have been processed.
fs
- Object - An object containing the following properties:totalBytes
- Number - The number of bytes that have been appended. Calculated asynchronously and might not be accurate: it growth while entries are added. (based on fs.Stats)processedBytes
- Number - The number of bytes that have been processed. (based on fs.Stats)
#
Event: errorThe error
event object contains the following properties:
message
- String - The message of the error.code
- String - The error code assigned to this error.data
- Object - Additional data provided for reporting or debugging (where available).
#
Event: warningThe warning
event object contains the following properties:
message
- String - The message of the error.code
- String - The error code assigned to this error.data
- Object - Additional data provided for reporting or debugging (where available).
#
Entry DataThe entry data object may contain the following properties:
#
Core Entry Propertiesname
- String - Sets the entry name including internal path.date
- String | Date - Sets the entry date.mode
- Number - Sets the entry permissions.prefix
- String - Sets a path prefix for the entry name. Useful when working with methods like directory or glob.stats
- fs.Stats - Sets the stat data for this entry allowing for reduction of fs.stat calls.
#
ZIP Entry PropertiesnamePrependSlash
- Boolean - Prepends a forward slash to archive file paths.store
- Boolean - Sets the compression method to STORE.
#
Format Registration#
registerFormatRegisters a format for use with archiver.
#
Parametersformat
- String - The name of the format.module
- Function - The function for archiver to interact with.
#
moduleThe module
function should consist of the following:
- a Readable Stream interface that contains the resulting archive data.
- a
module.prototype.append
function. - a
module.prototype.finalize
function.
#
module.prototype.append#
module.prototype.finalize#
isFormatRegisteredCheck if the format is already registered.
#
Parametersformat
- String - The name of the format.