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 a 'data' event
• Friendly function calls
• Write to file or write to memory
• Full JSLint complience and runs in Strict Mode
• MIT Licensed

The Tar object is actually a NodeJS stream, and each chunk is written to a stream. The Tar object supports the usual events: data, error, end. This module can either be used stricly like the normal tar utility would be by piping the output to standard out, or the chunks can be used as they come.

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

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 stay away if that bothers you. 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 fs and stream modules.

Examples

To tar all of the files in a directory:

var Tar = require('./tar'),
    overrides = {
		owner: "jameson",
		group: "jameson"
	},
	tape = new Tar();

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

tape.pipe(process.stdout);

To tar a bunch of random files together:

var Tar = require('./tar'),
	overrides = {
		owner: "jameson",
		group: "jameson"
	},
	tape = new Tar(),
	files;

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

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

tape.pipe(process.stdout);

Note, the "./" is not really necessary, but I do it for clarity. All files that are tarred will preserve the directory structure of the path of each file that was given. 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. 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
• 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