Merge pull request #56 from dduponchel/WIP_perfs

Improve performances

index.html

@@ -280,7 +280,6 @@ <h4 id="doc_file_name">file(name)</h4>
         <dd>The file if any, <code>null</code> otherwise. The file has the following structure :
           <ul>
             <li><code>name</code> the absolute path of the file</li>
-            <li><code>data</code> the data contained in the file</li>
             <li><code>options</code> the options of the file. The available options are :
               <ul>
                 <li><code>base64</code>, boolean, cf <a href="#doc_file_name_data_options">file(name, data [,options])</a></li>
@@ -302,12 +301,11 @@ <h4 id="doc_file_name">file(name)</h4>
 zip.file("file.txt", "content");
 
 zip.file("file.txt").name // "file.txt"
-zip.file("file.txt").data // "content"
+zip.file("file.txt").asText() // "content"
 zip.file("file.txt").options.dir // false
 
 // utf8 example
 var zip = new JSZip(zipFromAjaxWithUTF8);
-zip.file("amount.txt").data // "&#226;&#130;&#172;15" <!-- something like that -->
 zip.file("amount.txt").asText() // "&euro;15"
 zip.file("amount.txt").asArrayBuffer() // an ArrayBuffer containing &euro;15
 zip.file("amount.txt").asUint8Array() // an Uint8Array containing &euro;15
@@ -339,7 +337,7 @@ <h4 id="doc_file_regex">file(regex)</h4>
 folder.file(/^file/); // array of size 2, the relative paths start with file
 
 // arrays contain objects in the form:
-// {name: "file2.txt", data: "content", dir: false}</pre>
+// {name: "file2.txt", dir: false, asText : function () {...}, ...}</pre>
 
       <h4 id="doc_file_name_data_options">file(name, data [,options])</h4>
       <dl>
@@ -359,7 +357,7 @@ <h4 id="doc_file_name_data_options">file(name, data [,options])</h4>
              <li><code>date</code> (Date) use it to specify the last modification date.
              If not set the current date is used.</li>
              <li><code>compression</code> (String), default null. If set, specifies the file compression method to use. If not, the default file compression is used, cf <a href="#doc_generate_options">generate(options)</a>.</li>
-             <li><code>optimizedBinaryString</code> (boolean), default false. Set it to true if (and only if) the input
+             <li><code>optimizedBinaryString</code> (boolean), default false. Set it to true if (and only if) the input is a string and
              has already been prepared with a 0xFF mask.</li>
           </ul>
         </dd>
@@ -464,9 +462,16 @@ <h4 id="doc_generate_options">generate(options)</h4>
       HTML5 note : when using type = "uint8array", "arraybuffer" or "blob", be sure to check if the browser supports it (you can use <a href="#jszip_support"><code>JSZip.support</code></a>).
       This method will throw an exception otherwise.
       <pre class="example">
-content = zip.generate();
+content = zip.generate(); // base64
 location.href="data:application/zip;base64,"+content;</pre>
 
+      <pre class="example">
+var blobLink = document.getElementById('blobLink');
+blobLink.download = "hello.zip";
+blobLink.href = window.URL.createObjectURL(
+   zip.generate({type:"blob"})
+);</pre>
+
       <pre class="example">
 content = zip.generate({type:"string"});
 for (var c = 0; c &lt; content.length; c++) {
@@ -484,6 +489,8 @@ <h4 id="doc_load_data_options">load(data, options)</h4>
           <ul>
             <li><code>base64</code> (boolean) <code>true</code> if the data is base64 encoded, <code>false</code> for binary. Default : <code>false</code>.</li>
             <li><code>checkCRC32</code> (boolean) <code>true</code> if the read data should be checked against its CRC32. Default : <code>false</code>.</li>
+            <li><code>optimizedBinaryString</code> (boolean), default false. Set it to true if (and only if) the input is a string and
+            has already been prepared with a 0xFF mask.</li>
           </ul>
         </dd>
         <dt>Returns : </dt>
@@ -514,7 +521,7 @@ <h4 id="doc_filter_predicate">filter(predicate)</h4>
         <dd><code>predicate</code> (function) the predicate to use : <code>function (relativePath, file) {...}</code> It takes 2 arguments : the relative path and the file.
           <ul>
             <li><code>relativePath</code> (String) The filename and its path, reliatively to the current folder.</li>
-            <li><code>file</code> (Object) The file being tested. Like the result of <a href="#doc_file_name"><code>file(name)</code></a>, the file has the form <code>{name:"...", data:"...", options:{...}}</code>.</li>
+            <li><code>file</code> (Object) The file being tested. Like the result of <a href="#doc_file_name"><code>file(name)</code></a>, the file has the form <code>{name:"...", options:{...}, asText:function,...}</code>.</li>
             <li>Return true if the file should be included, false otherwise.</li>
           </ul>
         </dd>
@@ -526,7 +533,7 @@ <h4 id="doc_filter_predicate">filter(predicate)</h4>
 zip.file("readme.txt", "content");
 zip.filter(function (relativePath, file){
   // relativePath == "readme.txt"
-  // file = {name:"dir/readme.txt",data:"content",options:{...}}
+  // file = {name:"dir/readme.txt",options:{...},asText:function}
   return true/false;
 });</pre>
 
@@ -543,11 +550,13 @@ <h4 id="jszip_support">JSZip.support</h4>
       </p>
 
       <h3 id="zip_load_limits">Loading zip files, limitations</h3>
+      <h4>Not supported features</h4>
       <p>
       All the features of zip files are not supported.
       Classic zip files will work but encrypted zip, multi-volume, etc are not supported
       and the load() method will throw an <code>Error</code>.
       </p>
+      <h4>ZIP64 and 32bit integers</h4>
       <p>
       ZIP64 files can be loaded, but only if the zip file is not "too big". ZIP64 uses 64bits integers
       but Javascript represents all numbers as
@@ -559,17 +568,30 @@ <h3 id="zip_load_limits">Loading zip files, limitations</h3>
       So if all the 64bits integers can fit into 32 bits integers, everything will be fine. If
       it's not the case, you will have other problems anyway (see next limitation).
       </p>
+      <h4>Performance issues</h4>
       <p>
       An other limitation comes from the browser (and the machine running the browser).
-      A compressed zip file of 10M is common and easily opened by desktop application,
-      but not in a browser. The processing of such a beast is likely to be painful :
-      the browser will eat hundreds of megabytes while using CPU like never.<br/>
-      If you use an old browser, things will be worse. For example, IE6 and IE7 are
-      quite slow to to execute the unit tests, and they completely freeze as soon as
-      they try to handle larger files.<br />
-      Conclusion : reading small files is OK, reading others is not.
+      A compressed zip file of 10MB is "easily" opened by firefox/chrome/opera/IE10 but
+      will crash older IE. Also keep in mind that strings in javascript are encoded in UTF-16 :
+      a 10MB ascii text file will take 20MB of memory.
       </p>
       <p>
+      If you're having performance issues, please consider the following :
+      <ul>
+         <li>Don't use IE &lt; 10. Everything is better with WebGL support.</li>
+         <li>
+            If you load the file from an ajax call, ask your XHR an ArrayBuffer.
+            Loading a string is asking for troubles.
+         </li>
+         <li>
+            If you want to get the content of an ASCII file as a string, consider using
+            <code>asBinary()</code> instead of <code>asText()</code>. The transformation
+            "binary string" -&gt; "utf string" is a consuming process.
+         </li>
+      </ul>
+      </p>
+      <h4>The output zip will differ from the input zip</h4>
+      <p>
       Reading and generating a zip file won't give you back the same file.
       Some data are discarded (file metadata) and other are added (subfolders).
       </p>
@@ -586,6 +608,30 @@ <h3>1.0.0 <span>2013-02-14</span></h3>
       <p>
       First release after a long period without version.
       </p>
+
+      <h2 id="migrating_guide">Migrating Guide</h2>
+      <h3>From 1.0.x to ?</h3>
+      <p>
+         <ul>
+            <li><code>JSZipBase64</code> has been renamed to <code>JSZip.base64</code>.</li>
+            <li>
+               The <code>data</code> attribute doesn't exist anymore :
+               use the getters <code>asText()</code>, <code>asBinary()</code>, etc
+            </li>
+            <li>
+               The compression/decompression methods now give their input type with the
+               <code>compressInputType</code> and <code>uncompressInputType<code> attributes.
+         </ul>
+
+         Example for the data attribute :
+         <pre>// before
+zip.file("test.txt").data;
+zip.files["test.txt"].data;
+
+// after
+zip.file("test.txt").asText();
+zip.files["test.txt"].asText();
+      </p>
    </div>
 
    <div id="who" class="grid_3">
@@ -598,6 +644,7 @@ <h3>License</h3>
 
       <h3>Version</h3>
       <p>1.0.1</p>
+      <p>See the <a href="#migrating_guide">migrating guide</a> when updating the library !</p>
 
       <h3>Todo</h3>
       <ul>