Connection: add ability to explicitly close the current mailbox without auto-expunging

README.md

@@ -391,7 +391,7 @@ Connection Instance Methods
 
 * **openBox**(< _string_ >mailboxName[, < _boolean_ >openReadOnly=false], < _function_ >callback) - _(void)_ - Opens a specific mailbox that exists on the server. `mailboxName` should include any necessary prefix/path. `callback` has 2 parameters: < _Error_ >err, < _Box_ >mailbox.
 
-* **closeBox**(< _function_ >callback) - _(void)_ - Closes the currently open mailbox. **Any messages marked as Deleted in the mailbox will be removed if the mailbox was NOT opened in read-only mode.** Additionally, logging out or opening another mailbox without closing the current one first will NOT cause deleted messages to be removed. `callback` has 1 parameter: < _Error_ >err.
+* **closeBox**([< _boolean_ >autoExpunge=true, ]< _function_ >callback) - _(void)_ - Closes the currently open mailbox. If `autoExpunge` is true, any messages marked as Deleted in the currently open mailbox will be removed if the mailbox was NOT opened in read-only mode. If `autoExpunge` is false, you disconnect, or you open another mailbox, messages marked as Deleted will **NOT** be removed from the currently open mailbox. `callback` has 1 parameter: < _Error_ >err.
 
 * **addBox**(< _string_ >mailboxName, < _function_ >callback) - _(void)_ - Creates a new mailbox on the server. `mailboxName` should include any necessary prefix/path. `callback` has 1 parameter: < _Error_ >err.
 

lib/Connection.js

@@ -291,18 +291,44 @@ Connection.prototype.openBox = function(name, readOnly, cb) {
   });
 };
 
-// also deletes any messages in this box marked with \Deleted
-Connection.prototype.closeBox = function(cb) {
-  var self = this;
+Connection.prototype.closeBox = function(shouldExpunge, cb) {
   if (this._box === undefined)
     throw new Error('No mailbox is currently selected');
 
-  this._enqueue('CLOSE', function(err) {
-    if (!err)
-      self._box = undefined;
+  var self = this;
 
-    cb(err);
-  });
+  if (typeof shouldExpunge === 'function') {
+    cb = shouldExpunge;
+    shouldExpunge = true;
+  }
+
+  if (shouldExpunge) {
+    this._enqueue('CLOSE', function(err) {
+      if (!err)
+        self._box = undefined;
+
+      cb(err);
+    });
+  } else {
+    if (this.serverSupports('UNSELECT')) {
+      // use UNSELECT if available, as it claims to be "cleaner" than the
+      // alternative "hack"
+      this._enqueue('UNSELECT', function(err) {
+        if (!err)
+          self._box = undefined;
+
+        cb(err);
+      });
+    } else {
+      // "HACK": close the box without expunging by attempting to SELECT a
+      // non-existent mailbox
+      var badbox = 'NODEJSIMAPCLOSINGBOX' + Date.now();
+      this._enqueue('SELECT "' + badbox + '"', function(err) {
+        self._box = undefined;
+        cb();
+      });
+    }
+  }
 };
 
 Connection.prototype.addBox = function(name, cb) {