tar-async

Intro

Javascript implementation of the Tar archive utility. The goal is to make tar JavaScript friendly by incorporating such ideals as:

• Evented IO with events emitted per chunk
• Friendly function calls
• Write to file or write to memory
• Customizable through options
• Full JSLint complience and runs in Strict Mode
• MIT Licensed

The Tar object is actually a NodeJS stream, so it supports the usual events: data, error, and end. Since it is a stream, this module can either be simply piped to standard out or to a file, or the chunks can be processed as they come. This makes it really convenient when working with webservers.

No compression is used, so an external compression library is necessary. This is by design and not likely to be implemented.

Install

npm install tar-async

Dependencies

The only external module that Tar uses is futures, and only the forEachAsync method at that. This module will add to the Array prototype, so any for..in loops will need to be converted to forEach loops. This module is used to allow for graceful handling of asynchronous calls in a forEach loop.

This module can be installed from npm:

npm install futures

Tar also requires the built-in fs and stream modules.

Usage Guide

This tar utility inherits from stream, so any methods that work with stream will work with this utility. Tar archives are processed in 10KiB chunks. No compression is applied because the libraries for compression are not stable enough for my liking, but that is easily implemented.

The constructor takes an array of options as its only parameter:

• addHidden- add hidden files to archive (default false)
  • a 'hidden' file/directory is defined as being prefixed by a '.'
  • no other paradigm is currently supported
• noDirs- lump all files together into a single directory (default false)
  • tar by default preserves the directory structure
  • often, only raw files are wanted, so this makes it easier to extract
• normalize- normalize each file before archiving (default true)
• recurse- recursively add files to archive (default true)
• output- output stream (default undefined)
  • must be a writable stream object
  • will throw an error if given an invalid stream object, so be careful

Files can be added to the archive until the close function is called. There are three functions that add data to the archive:

• append- Appends a file to the archive. Takes two parameters
  • filepath- Path to the file (can be relative or absolute)
  • callback- Has at most one parameter: the error if one occurred
• addFiles- Adds an array of files to the archive. Takes two parameters
  • files- Array of files. Files must be absolute or relative paths.
  • callback- Has at most one parameter: the error if one occurred
• addDirectory- Adds an entire directory to the archive. Takes two parameters:
  • filepath- Path to the directory to add (adds the directory path to each file)
  • callback- Has at most one parameter: the error if one occurred

Examples

There are a few examples in the examples directory, but if you are lazy, here are a couple brief examples.

To tar all of the files in a directory:

var Tar = require('tar'),
	options = {
		output: process.stdout
	},
	tape = new Tar(options);

tape.addDirectory("./", function (err) {
	if (err) {
		throw err;
	}
	tape.close();
});

To tar a bunch of random files together:

var Tar = require('./tar'),
	options = {
		output: process.stdout
	},
	tape = new Tar(),
	files;

files = [
	"./tar.js",
	"./header.js"
];

tape.addFiles(files, function (err) {
	if (err) {
		throw err;
	}
	tape.close();
});

All files that are tarred will preserve the directory structure of the path of each file that was given unless otherwise specified in the options. The addFiles method requires the full path on the file.

Source structure

header.js

Stores the header format and a method for formatting the header:

• headerFormat- Header structure, only used in formatHeader()
• formatHeader- writes the data from the parameter to a 512 byte header

The header is an array with two properties in each element:

• field- Corresponds to a property of an object passed in to formatHeader
• length- Length of this property in bytes

Each field in the header is a string of ASCII characters (one byte each).

tar.js

Exports a Tar object with several public methods:

• constructor- Inherits from Stream and all arguments are passed to the Stream constructor
  • options- configuration for the tar utility (discussed in 'Usage Guide')
• addFiles- adds a bunch of files to the tar recursively
• append- Appends a file, nothing too exciting here...
• addDirectory- adds files to the tar recursively

utils.js

Utilities to make life more convenient:

• clean- Creates a 'clean' Buffer (zeroed)
• pad- Stringifies the number and adds ASCII zeroes to the end (up to 12 zeroes)
  • num- the number to stringify
  • bytes- how long the resulting string should be
  • base- default is base-8