Fork me on GitHub

zip.js

Core API

Contents

  1. Configuration
  2. I/O
  3. Zip reading
  4. Zip reading example
  5. Zip writing
  6. Zip writing example
  7. Full example

  1. Configuration

    zip.js uses Web workers to compress and uncompress data in non-blocking background processes. If you need to disable Web workers, set zip.useWebWorkers to false (you must also import deflate.js and/or inflate.js in the web page).

    When zip.js uses Web workers it needs to know the relative path of deflate.js and inflate.js from the base URL of the web page. If the relative path from the base URL is not empty (and zip.useWebWorkers = true) then you must set zip.workerScriptsPath to the relative path of deflate.js and inflate.js files.

  2. I/O

    Reader and Writer constructors

    zip.js can handle multiple types of data thanks to a generic API. This feature is based on 2 abstract constructors: zip.Reader and zip.Writer.
    zip.Reader constructors help to read data from a file and zip.Writer constructors help to write data into a file.

    For example, if you need to read a zip and store its file into a variable, you must use a zip.Reader object to read the compressed zip data. You must also use a zip.Writer object to write uncompressed file data into the variable.

    Reader constructors

    zip.TextReader(text)

    string reader constructor

    Parameters:

    text (string)
    The string to read

    zip.BlobReader(blob)

    Blob object reader constructor

    Parameters:

    blob (Blob)
    The Blob object to read

    zip.Data64URIReader(dataURI)

    Data URI reader constructor

    Parameters:

    dataURI (string)
    The data URI to read

    zip.HttpReader(URL)

    HTTP content reader constructor

    Parameters:

    URL (string)
    The URL of the content to read

    zip.HttpRangeReader(URL)

    HTTP content reader using "Range" request header constructor

    Parameters:

    URL (string)
    The URL of the content to read

    Reader members (used internally)

    Attributes:

    size (number)
    The uncompressed data byte size

    Methods:

    zip.Reader.prototype.init(callback, onerror)

    Initialize the zip.Reader object.

    Parameters:

    success callback (Function)
    callback function
    onerror (Function)
    error callback function
    zip.Reader.prototype.readUint8Array(index, length, callback[, onerror])

    Extract an UInt8Array object beginning at index location through the specified length.

    Parameters:

    index (number)
    The beginning index
    length (number)
    The UInt8Array object length
    callback (Function)
    success callback function returning the UInt8Array object as parameter
    onerror (Function)
    error callback function

    Writer constructors

    zip.TextWriter()

    string writer constructor


    zip.BlobWriter()

    Blob object writer constructor


    zip.FileWriter(fileEntry)

    File object writer constructor

    Parameters:

    fileEntry (FileEntry)
    the FileEntry object used to write the File object

    zip.Data64URIWriter([mimeString])

    Data URI writer constructor

    Parameters:

    mimeString (string)
    the data MIME type

    Writer members (used internally)

    Methods:

    zip.Writer.prototype.init(callback[, onerror])

    Initialize the zip.Writer object.

    Parameters:

    callback (Function)
    callback function
    zip.Writer.prototype.writeUint8Array(array, callback[, onerror])

    Write an UInt8Array object at the current index.

    Parameters:

    array (UInt8Array)
    The UInt8Array to write
    callback (Function)
    success callback function
    onerror (Function)
    error callback function
    zip.Writer.prototype.getData(callback[, onerror])

    Get written data (returned type depends on zip.Reader constructor used)

    Parameters:

    callback (Function)
    success callback function returning the data as parameter
    onerror (Function)
    error callback function
  3. Zip reading

    initialization

    zip.createReader(reader, callback[, onerror])

    Create a ZipReader object. A ZipReader object helps to read the zipped content.

    Parameters:

    reader (zip.Reader)
    the zip.Reader object used to read input data
    callback (Function)
    success callback function returning the new ZipReader object as parameter
    onerror (Function)
    global error callback function

    Zip entries listing

    ZipReader.prototype.getEntries(callback)

    Get all entries from a zip.

    Parameters:

    callback (Function)
    callback function returning the Array of Entry object as parameter

    Zip entry data reading

    Entry()

    Constructor representing a zip file entry.

    Attributes:

    filename (string)
    file name
    directory (boolean)
    true if the entry is a directory
    compressedSize (number)
    compressed data size
    uncompressedSize (number)
    uncompressed data size
    lastModDate (Date)
    last modification date
    lastModDateRaw (number)
    last modification date in raw format (MS-DOS)
    comment (string)
    file comment
    crc32 (number)
    uncompressed data checksum

    Methods:

    Entry.prototype.getData(writer, onend[, onprogress, checkCrc32])

    Get the data of a zip entry.

    Parameters:

    writer (zip.Writer)
    zip.Writer object used to write output data
    onend (Function)
    success callback function returning the output data (returned type depends on zip.Writer constructor used) as parameter
    onprogress (Function)
    progress callback function returning the progress index (number) and a max value (number) as parameters
    checkCrc32 (boolean)
    pass true to verify data integrity

    Zip closing

    ZipReader.prototype.close(callback)

    Close the opened zip.

    Parameters:

    callback (Function)
    success callback function
  4. Zip reading example

    Read a zip from a Blob/File object

    // use a BlobReader to read the zip from a Blob object
    zip.createReader(new zip.BlobReader(blob), function(reader) {
    
      // get all entries from the zip
      reader.getEntries(function(entries) {
        if (entries.length) {
    
          // get first entry content as text
          entries[0].getData(new zip.TextWriter(), function(text) {
            // text contains the entry data as a String
            console.log(text);
    
            // close the zip reader
            reader.close(function() {
              // onclose callback
            });
    
          }, function(current, total) {
            // onprogress callback
          });
        }
      });
    }, function(error) {
      // onerror callback
    });
  5. Zip writing

    initialization

    zip.createWriter(writer, callback[, onerror])

    Create a ZipWriter object.

    Parameters:

    writer (zip.Writer)
    the zip.Writer object used to write output data
    callback (Function)
    success callback function returning the new ZipWriter object as parameter
    onerror (Function)
    global error callback function

    Zip entry writing

    ZipWriter.prototype.add(name, reader, onend[, onprogress, options])

    Add a new entry into the zip.

    Parameters:

    name (string)
    entry file name
    reader (zip.Reader)
    the zip.Reader object used to read entry data to add - null for directory entry
    onend (Function)
    success callback function
    onprogress (Function)
    progress callback function returning the progress index (number) and a max value (number) as parameters
    options (Object)
    entry options properties:
    directory (boolean)
    true if the entry is a directory
    level (number)
    compression level from 0 to 9
    comment (string)
    file comment
    lastModDate (Date)
    last modification date
    version (number)
    zip version

    Zip closing

    ZipWriter.prototype.close(callback)

    Close the opened zip.

    Parameters:

    callback (Function)
    success callback function returning the generated zip data (returned type depends on zip.Writer constructor used) as parameter
  6. Zip writing example

    Write a zip into a Blob object

    // use a BlobWriter to store the zip into a Blob object
    zip.createWriter(new zip.BlobWriter(), function(writer) {
    
      // use a TextReader to read the String to add
      writer.add("filename.txt", new zip.TextReader("test!"), function() {
        // onsuccess callback
    
        // close the zip writer
        writer.close(function(blob) {
          // blob contains the zip file as a Blob object
    
        });
      }, function(currentIndex, totalIndex) {
        // onprogress callback
      });
    }, function(error) {
      // onerror callback
    });
  7. Full example

    // create the blob object storing the data to compress
    var blob = new Blob([ "Lorem ipsum dolor sit amet, consectetuer adipiscing elit..." ], {
      type : "text/plain"
    });
    // creates a zip storing the file "lorem.txt" with blob as data
    // the zip will be stored into a Blob object (zippedBlob)
    zipBlob("lorem.txt", blob, function(zippedBlob) {
      // unzip the first file from zipped data stored in zippedBlob
      unzipBlob(zippedBlob, function(unzippedBlob) {
        // logs the uncompressed Blob
        console.log(unzippedBlob);
      });
    });
    
    function zipBlob(filename, blob, callback) {
      // use a zip.BlobWriter object to write zipped data into a Blob object
      zip.createWriter(new zip.BlobWriter("application/zip"), function(zipWriter) {
        // use a BlobReader object to read the data stored into blob variable
        zipWriter.add(filename, new zip.BlobReader(blob), function() {
          // close the writer and calls callback function
          zipWriter.close(callback);
        });
      }, onerror);
    }
    
    function unzipBlob(blob, callback) {
      // use a zip.BlobReader object to read zipped data stored into blob variable
      zip.createReader(new zip.BlobReader(blob), function(zipReader) {
        // get entries from the zip file
        zipReader.getEntries(function(entries) {
          // get data from the first file
          entries[0].getData(new zip.BlobWriter("text/plain"), function(data) {
            // close the reader and calls callback function with uncompressed data as parameter
            zipReader.close();
            callback(data);
          });
        });
      }, onerror);
    }
    
    function onerror(message) {
      console.error(message);
    }