joegreen88 / js-unzip

Unzip files with JavaScript

JSUnzip

A javascript library for reading the contents of zip files. Also contains JSInflate.

var myZip = ... // Get it with an XHR request, HTML5 files, etc.
var unzipper = new JSUnzip(myZip);
unzipper.isZipFile();      // true or false

JSUnzip.readEntries()

unzipper.readEntries();    // Creates "entries"
unzipper.entries;          // Array of JSUnzip.ZipEntry objects.

JSUnzip.getEntry()

Provides a way to instanciate JSUnzip.ZipEntry objects one at a time without using readEntries().

var unzipper = new JSUnzip(myZip);
for (e = unzipper.getEntry(); e !== false; e = unzipper.getEntry()) {
	e; // JSUnzip.ZipEntry object
}

JSUnzip.getEntry(true)

Pass a true argument to get just the uncompressed, raw binary data from the JSUnzip.ZipEntry object.

var unzipper = new JSUnzip(myZip);
for (data = unzipper.getEntry(true); data !== false; data = unzipper.getEntry(true)) {
	if (typeof(data) === "string") { // data will be null if the compression method used for the item is not applicable.
		data; // A string containing the raw file data for the entry. Already decompressed/inflated where applicable. 
	}
}

Working with JSUnzip.ZipEntry objects

After readEntries is called, an array of JSUnzip.ZipEntry objects is created, one per file in the Zip archive.

entry = myZip.entries[0];

// Attributes
entry.fileName;          // The file name of the entry. Contains the full path.
                         // Examples:
                         //   "foo.txt"
                         //   "directory/bar.jpg"
entry.data;              // The raw (compressed) data
entry.compressionMethod; // Number representing compression method.
                         //   1: No compression. File can be used as-is.
                         //   8: DEFLATE. The most common compression method.
                         //      Use a inflate algorithm to uncompress, such
                         //      as http://github.com/augustl/js-inflate/
entry.compressedSize;    // The size of the commpressed data
entry.uncompressedSize;  // The size of the data when it's uncompressed
entry.signature;         // The magic number used to determine if it is in fact
                         // a zip file.
entry.versionNeeded;     // Zip specification version needed to work with the file.
entry.bitFlag;           // Flag for various states

// Functions (mostly for internal use)
entry.isEncrypted();
entry.isUsingUtf8();
entry.isUzingZip64();    // Zip64 is for 4gb+ files. Not supported by this lib.

See http://www.pkware.com/documents/casestudies/APPNOTE.TXT for more information about the Zip format, such as all the compression methods.

Uncompressing manually with JSInflate

Almost all Zip files are compressed with the deflate algorithm. You can use JSInflate, included, to uncompress these Zips.

var blob = ...; // A HTML5 binary file, for example.
var unzipper = new JSUnzip(blob);
if (unzipper.isZipFile()) {
  unzipper.readEntries();
  for (entry = unzipper.getEntry(); entry !== false; entry = unzipper.getEntry()) {
    if (entry.compressionMethod === 0) {
      var uncompressed = entry.data; 
    } else if (entry.compressionMethod === 8) {
      var uncompressed = JSInflate.inflate(entry.data);
    }
  }
}

Credits

• August Lilleaas for the js-unzip and js-inflate libraries. https://github.com/augustl/js-unzip and https://github.com/augustl/js-inflate
• Jacob Seidelin for his JavaScript EXIF Reader.
• Jonas Höglund for his cute little zip parser.
• “Cheeso” for his js zip library.

About

Licensed under the MIT license.