Library for extracting tar files in the browser
 
Go to file
Sebastian Jørgensen 911dad267a Change to MIT license 2015-09-17 18:12:39 +02:00
build Added buffer to file. Added installation and better usage instructions. 2015-09-14 18:34:34 +02:00
spec All tests passing, some documentation. 2015-09-14 13:28:49 +02:00
src Added buffer to file. Added installation and better usage instructions. 2015-09-14 18:34:34 +02:00
.gitignore Added buffer to file. Added installation and better usage instructions. 2015-09-14 18:34:34 +02:00
LICENSE.txt Change to MIT license 2015-09-17 18:12:39 +02:00
README.md Added buffer to file. Added installation and better usage instructions. 2015-09-14 18:34:34 +02:00
bower.json one more tag 2015-09-14 19:10:40 +02:00
gulpfile.js All tests passing, some documentation. 2015-09-14 13:28:49 +02:00
karma.conf.js GPL license, tested in IE11, FF and Chrome 2015-09-14 14:27:55 +02:00
package.json Added buffer to file. Added installation and better usage instructions. 2015-09-14 18:34:34 +02:00
test-main.js tests not working 2015-09-14 11:22:54 +02:00

README.md

js-untar

Library for extracting tar files in the browser. Useful when packing all your application images/sound/json/etc. data in a standard .tar file and serving to clients as one gzipped bundle.

Browser feature requirements

As of September 2015 this includes Chrome>=20, Firefox>=13, IE>=10, Opera>=12.10 and Safari>=8. Web Worker transferable objects are used when available, increasing speed greatly. This is supported in Chrome>=21, Firefox>=18, Opera>=15 and Safari.

Installation

bower install --save js-untar

Documentation

Supports AMD, CommonJS or simply load with a script tag, which will provide a global untar function. The module is a function that returns a modified Promise with a progress callback. This callback is executed every time a file is extracted. The standard Promise.then method is also called when extraction is done, with all extracted files as argument. The extraction is done in a Web Worker to allow the main UI thread to continue.

Example:

// Load the source ArrayBuffer from a XMLHttpRequest (or any other way you may need).
var sourceBuffer = [...];

untar(sourceBuffer)
.progress(function(extractedFile) {
	... // Do something with a single extracted file.
})
.then(function(extractedFiles) {
	... // Do something with all extracted files.
});
// or
untar(sourceBuffer).then(
	function(extractedFiles) { // onSuccess
		... // Do something with all extracted files.
	},
	function(err) { // onError
		... // Handle the error.
	},
	function(extractedFile) { // onProgress
		... // Do something with a single extracted file.
	}
);

File object

The returned file object(s) has the following properties. Most of these are explained in the Tar wikipedia entry.

  • name = The full filename (including path and ustar filename prefix).
  • mode
  • uid
  • gid
  • size
  • modificationTime
  • checksum
  • type
  • linkname
  • ustarFormat
  • buffer An ArrayBuffer with the contents of the file.
  • blob A Blob object with the contents of the file.
  • getObjectUrl() A unique ObjectUrl to the data can be retrieved with this method for easy usage of extracted data in <img> tags etc. document.getElementById("targetImageElement").src = file.getObjectUrl();

If the .tar file was in the ustar format (which most are), the following properties are also defined:

  • version
  • uname
  • gname
  • devmajor
  • devminor
  • namePrefix