test and document calling close instead of readEntry. closes #24

README.md

@@ -182,6 +182,7 @@ so it is safe to call this method before attaching event listeners.
 
 After calling this method, calling this method again before the response event has been emitted will cause undefined behavior.
 Calling this method after the `end` event has been emitted will cause undefined behavior.
+Calling this method after calling `close()` will cause undefined behavior.
 
 #### openReadStream(entry, callback)
 
@@ -208,11 +209,18 @@ but enforcing the `uncompressedSize` is implemented here as a security feature.
 
 Causes all future calls to `openReadStream()` to fail,
 and closes the fd after all streams created by `openReadStream()` have emitted their `end` events.
-If this object's `end` event has not been emitted yet, this function causes undefined behavior.
 
 If the `autoClose` option is set to `true` (see `open()`),
 this function will be called automatically effectively in response to this object's `end` event.
 
+If the `lazyEntries` option is set to `false` (see `open()`) and this object's `end` event has not been emitted yet,
+this function causes undefined behavior.
+If the `lazyEntries` option is set to `true`,
+you can call this function instead of calling `readEntry()` to abort reading the entries of a zipfile.
+
+It is safe to call this function multiple times; after the first call, successive calls have no effect.
+This includes situations where the `autoClose` option effectively calls this function for you.
+
 #### isOpen
 
 `Boolean`. `true` until `close()` is called; then it's `false`.

test/test.js

@@ -170,6 +170,7 @@ listZipFiles(path.join(__dirname, "failure")).forEach(function(zipfilePath) {
   });
 });
 
+// fromRandomAccessReader with errors
 pend.go(function(cb) {
   util.inherits(TestRandomAccessReader, yauzl.RandomAccessReader);
   function TestRandomAccessReader() {
@@ -194,6 +195,46 @@ pend.go(function(cb) {
   });
 });
 
+// read some entries, then close.
+pend.go(function(cb) {
+  var prefix = "read some entries then close: ";
+  // this zip file should have at least 3 entries in it
+  yauzl.open(path.join(__dirname, "success/unicode.zip"), {lazyEntries: true}, function(err, zipfile) {
+    if (err) throw err;
+
+    var entryCount = 0;
+
+    zipfile.readEntry();
+    zipfile.on("entry", function(entry) {
+      entryCount += 1;
+      console.log(prefix + "entryCount: " + entryCount);
+      if (entryCount < 3) {
+        zipfile.readEntry();
+      } else if (entryCount === 3) {
+        zipfile.close();
+        console.log(prefix + "close()");
+      } else {
+        throw new Error(prefix + "read too many entries");
+      }
+    });
+    zipfile.on("close", function() {
+      console.log(prefix + "closed");
+      if (entryCount === 3) {
+        console.log(prefix + "pass");
+        cb();
+      } else {
+        throw new Error(prefix + "not enough entries read before closed");
+      }
+    });
+    zipfile.on("end", function() {
+      throw new Error(prefix + "we weren't supposed to get to the end");
+    });
+    zipfile.on("error", function(err) {
+      throw err;
+    });
+  });
+});
+
 pend.wait(function() {
   // if you don't see this, something never happened.
   console.log("done");