imapflow 1.2.7 → 1.2.9

package/lib/commands/list.js

@@ -3,23 +3,45 @@
 const { decodePath, encodePath, normalizePath } = require('../tools.js');
 const { specialUse } = require('../special-use');
 
-// Lists mailboxes from server
+/**
+ * Lists mailboxes from the server, including subscription status and special-use flags.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} reference - Reference name (namespace prefix)
+ * @param {string} mailbox - Mailbox name pattern with possible wildcards
+ * @param {Object} [options] - List options
+ * @param {boolean} [options.listOnly] - If true, return entries after LIST without LSUB or status queries
+ * @param {Object} [options.statusQuery] - Status data items to query for each listed mailbox
+ * @param {Object} [options.specialUseHints] - Hints mapping mailbox paths to special-use types (sent, junk, trash, drafts, archive)
+ * @returns {Promise<Object[]>} Array of mailbox entries sorted by special-use flags and name
+ * @throws {Error} If the LIST command fails
+ */
 module.exports = async (connection, reference, mailbox, options) => {
     options = options || {};
 
+    // Special-use flags sorted by display priority (INBOX first, Trash last).
+    // Used in the final sort to group special-use mailboxes at the top of the list.
     const FLAG_SORT_ORDER = ['\\Inbox', '\\Flagged', '\\Sent', '\\Drafts', '\\All', '\\Archive', '\\Junk', '\\Trash'];
+    // Priority for how a special-use flag was determined: explicit user hint > server
+    // extension flag (SPECIAL-USE/XLIST) > name-based guess. When multiple mailboxes
+    // claim the same special-use type, the highest-priority source wins.
     const SOURCE_SORT_ORDER = ['user', 'extension', 'name'];
 
+    // Prefer XLIST (legacy Gmail extension) only if SPECIAL-USE (RFC 6154) is unavailable.
+    // Both provide special-use flags, but SPECIAL-USE is the standardized approach.
     let listCommand = connection.capabilities.has('XLIST') && !connection.capabilities.has('SPECIAL-USE') ? 'XLIST' : 'LIST';
 
     let response;
     try {
         let entries = [];
 
+        // statusMap caches STATUS responses received inline via LIST-STATUS extension,
+        // keyed by normalized mailbox path. This avoids separate STATUS commands per mailbox.
         let statusMap = new Map();
         let returnArgs = [];
         let statusQueryAttributes = [];
 
+        // Build the list of STATUS data items to request (MESSAGES, UIDNEXT, etc.)
         if (options.statusQuery) {
             Object.keys(options.statusQuery || {}).forEach(key => {
                 if (!options.statusQuery[key]) {
@@ -44,6 +66,9 @@ module.exports = async (connection, reference, mailbox, options) => {
             });
         }
 
+        // LIST-STATUS (RFC 5819): allows requesting STATUS data inline with LIST,
+        // avoiding a separate STATUS command for each mailbox. Adds RETURN (STATUS (...))
+        // and optionally SPECIAL-USE to the LIST command arguments.
         if (listCommand === 'LIST' && connection.capabilities.has('LIST-STATUS') && statusQueryAttributes.length) {
             returnArgs.push({ type: 'ATOM', value: 'STATUS' }, statusQueryAttributes);
             if (connection.capabilities.has('SPECIAL-USE')) {
@@ -51,6 +76,9 @@ module.exports = async (connection, reference, mailbox, options) => {
             }
         }
 
+        // Tracks all candidate mailboxes for each special-use type (e.g., \\Sent).
+        // Multiple mailboxes may claim the same type via different sources (user hint,
+        // server extension, name match). After listing, the best match wins.
         let specialUseMatches = {};
         let addSpecialUseMatch = (entry, type, source) => {
             if (!specialUseMatches[type]) {
@@ -59,6 +87,9 @@ module.exports = async (connection, reference, mailbox, options) => {
             specialUseMatches[type].push({ entry, source });
         };
 
+        // User-provided hints map mailbox paths to special-use types (e.g., {sent: "Sent Items"}).
+        // These override server-reported flags and name-based guesses. Converted to a
+        // path-keyed lookup: { "Sent Items" => "\\Sent" }
         let specialUseHints = {};
         if (options.specialUseHints && typeof options.specialUseHints === 'object') {
             for (let type of Object.keys(options.specialUseHints)) {
@@ -67,11 +98,15 @@ module.exports = async (connection, reference, mailbox, options) => {
                     options.specialUseHints[type] &&
                     typeof options.specialUseHints[type] === 'string'
                 ) {
+                    // Capitalize first letter: "sent" -> "\\Sent"
                     specialUseHints[normalizePath(connection, options.specialUseHints[type])] = `\\${type.replace(/^./, c => c.toUpperCase())}`;
                 }
             }
         }
 
+        // Executes a LIST (or XLIST) command and collects mailbox entries.
+        // Called once for the main listing and optionally again for INBOX if a
+        // namespace prefix was used (INBOX may live outside the namespace).
         let runList = async (reference, mailbox) => {
             const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
 
@@ -81,12 +116,15 @@ module.exports = async (connection, reference, mailbox, options) => {
 
             response = await connection.exec(listCommand, cmdArgs, {
                 untagged: {
+                    // Each untagged LIST response: * LIST (<flags>) "<delimiter>" "<mailbox name>"
+                    // attributes[0] = flags array, attributes[1] = delimiter, attributes[2] = mailbox name
                     [listCommand]: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;
                         }
 
                         let entry = {
+                            // Decode from modified UTF-7 wire format and normalize the path
                             path: normalizePath(connection, decodePath(connection, (untagged.attributes[2] && untagged.attributes[2].value) || '')),
                             pathAsListed: (untagged.attributes[2] && untagged.attributes[2].value) || '',
                             flags: new Set(untagged.attributes[0].map(entry => entry.value)),
@@ -94,31 +132,39 @@ module.exports = async (connection, reference, mailbox, options) => {
                             listed: true
                         };
 
+                        // Check user-provided hints first (highest priority)
                         if (specialUseHints[entry.path]) {
                             addSpecialUseMatch(entry, specialUseHints[entry.path], 'user');
                         }
 
+                        // XLIST marks INBOX with a \\Inbox flag. Remove it from flags
+                        // (it's not a standard flag) and register as special-use match.
+                        // XLIST may also use a localised name (e.g., "Posteingang" for German INBOX).
                         if (listCommand === 'XLIST' && entry.flags.has('\\Inbox')) {
-                            // XLIST specific flag, ignore
                             entry.flags.delete('\\Inbox');
                             if (entry.path !== 'INBOX') {
-                                // XLIST may use localised inbox name
                                 addSpecialUseMatch(entry, '\\Inbox', 'extension');
                             }
                         }
 
+                        // Name-based INBOX detection: any mailbox named "INBOX" (case-insensitive)
+                        // is the inbox per RFC 3501.
                         if (entry.path.toUpperCase() === 'INBOX') {
                             addSpecialUseMatch(entry, '\\Inbox', 'name');
                         }
 
+                        // Strip leading delimiter (some servers prepend it to paths)
                         if (entry.delimiter && entry.path.charAt(0) === entry.delimiter) {
                             entry.path = entry.path.slice(1);
                         }
 
+                        // Build parent path hierarchy for tree construction and sorting
                         entry.parentPath = entry.delimiter && entry.path ? entry.path.substr(0, entry.path.lastIndexOf(entry.delimiter)) : '';
                         entry.parent = entry.delimiter ? entry.path.split(entry.delimiter) : [entry.path];
                         entry.name = entry.parent.pop();
 
+                        // Try to detect special-use from server flags or well-known names
+                        // (e.g., "Sent", "Drafts", "Junk", "Trash")
                         let { flag: specialUseFlag, source: flagSource } = specialUse(
                             connection.capabilities.has('XLIST') || connection.capabilities.has('SPECIAL-USE'),
                             entry
@@ -131,6 +177,8 @@ module.exports = async (connection, reference, mailbox, options) => {
                         entries.push(entry);
                     },
 
+                    // Inline STATUS response from LIST-STATUS extension (RFC 5819).
+                    // Parses alternating key-value pairs (i % 2 pattern).
                     STATUS: async untagged => {
                         let statusPath = normalizePath(connection, decodePath(connection, (untagged.attributes[0] && untagged.attributes[0].value) || ''));
                         let statusList = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
@@ -138,8 +186,16 @@ module.exports = async (connection, reference, mailbox, options) => {
                             return;
                         }
 
-                        let key;
+                        const STATUS_FIELD_MAP = {
+                            MESSAGES: { key: 'messages', parser: Number },
+                            RECENT: { key: 'recent', parser: Number },
+                            UIDNEXT: { key: 'uidNext', parser: Number },
+                            UIDVALIDITY: { key: 'uidValidity', parser: BigInt },
+                            UNSEEN: { key: 'unseen', parser: Number },
+                            HIGHESTMODSEQ: { key: 'highestModseq', parser: BigInt }
+                        };
 
+                        let key;
                         let map = { path: statusPath };
 
                         statusList.forEach((entry, i) => {
@@ -150,43 +206,18 @@ module.exports = async (connection, reference, mailbox, options) => {
                             if (!key || !entry || typeof entry.value !== 'string') {
                                 return;
                             }
-                            let value = false;
-                            switch (key.toUpperCase()) {
-                                case 'MESSAGES':
-                                    key = 'messages';
-                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
-                                    break;
-
-                                case 'RECENT':
-                                    key = 'recent';
-                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
-                                    break;
-
-                                case 'UIDNEXT':
-                                    key = 'uidNext';
-                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
-                                    break;
-
-                                case 'UIDVALIDITY':
-                                    key = 'uidValidity';
-                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
-                                    break;
-
-                                case 'UNSEEN':
-                                    key = 'unseen';
-                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
-                                    break;
-
-                                case 'HIGHESTMODSEQ':
-                                    key = 'highestModseq';
-                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
-                                    break;
+
+                            const fieldConfig = STATUS_FIELD_MAP[key.toUpperCase()];
+                            if (!fieldConfig) {
+                                return;
                             }
+
+                            const value = !isNaN(entry.value) ? fieldConfig.parser(entry.value) : false;
                             if (value === false) {
                                 return;
                             }
 
-                            map[key] = value;
+                            map[fieldConfig.key] = value;
                         });
 
                         statusMap.set(statusPath, map);
@@ -203,18 +234,22 @@ module.exports = async (connection, reference, mailbox, options) => {
             return entries;
         }
 
+        // When listing with a namespace prefix (e.g., "INBOX."), INBOX itself may
+        // not appear in results. Run a separate LIST for INBOX to ensure it's included.
         if (normalizedReference && !specialUseMatches['\\Inbox']) {
-            // INBOX was most probably not included in the listing if namespace was used
             await runList('', 'INBOX');
         }
 
+        // Attach STATUS data to each selectable mailbox. If LIST-STATUS was used,
+        // data is already in statusMap; otherwise, fall back to individual STATUS commands.
         if (options.statusQuery) {
             for (let entry of entries) {
+                // \\Noselect and \\NonExistent mailboxes cannot hold messages
                 if (!entry.flags.has('\\Noselect') && !entry.flags.has('\\NonExistent')) {
                     if (statusMap.has(entry.path)) {
                         entry.status = statusMap.get(entry.path);
                     } else if (!statusMap.size) {
-                        // run STATUS command
+                        // Server didn't support LIST-STATUS; fall back to per-mailbox STATUS
                         try {
                             entry.status = await connection.run('STATUS', entry.path, options.statusQuery);
                         } catch (err) {
@@ -225,6 +260,10 @@ module.exports = async (connection, reference, mailbox, options) => {
             }
         }
 
+        // LSUB (RFC 3501 6.3.9): queries which mailboxes the user is subscribed to.
+        // We merge subscription info into the entries already collected from LIST.
+        // Subscribed-only mailboxes that weren't in LIST are intentionally ignored
+        // (they may be phantom entries from old subscriptions to deleted mailboxes).
         response = await connection.exec(
             'LSUB',
             [encodePath(connection, normalizePath(connection, reference || '')), encodePath(connection, normalizePath(connection, mailbox || '', true))],
@@ -255,26 +294,23 @@ module.exports = async (connection, reference, mailbox, options) => {
                         entry.parent = entry.delimiter ? entry.path.split(entry.delimiter) : [entry.path];
                         entry.name = entry.parent.pop();
 
+                        // Merge LSUB data into existing LIST entry if found
                         let existing = entries.find(existing => existing.path === entry.path);
                         if (existing) {
                             existing.subscribed = true;
+                            // Merge any additional flags from LSUB into the LIST entry
                             entry.flags.forEach(flag => existing.flags.add(flag));
-                        } else {
-                            // ignore non-listed folders
-                            /*
-                            let specialUseFlag = specialUse(connection.capabilities.has('XLIST') || connection.capabilities.has('SPECIAL-USE'), entry);
-                            if (specialUseFlag && !flagsSeen.has(specialUseFlag)) {
-                                entry.specialUse = specialUseFlag;
-                            }
-                            entries.push(entry);
-                            */
                         }
+                        // Non-listed subscribed folders are intentionally ignored
                     }
                 }
             }
         );
         response.next();
 
+        // Resolve special-use conflicts: for each type, pick the best candidate
+        // based on source priority (user > extension > name), then alphabetically.
+        // Only the winning entry gets the specialUse property set.
         for (let type of Object.keys(specialUseMatches)) {
             let sortedEntries = specialUseMatches[type].sort((a, b) => {
                 let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
@@ -291,12 +327,14 @@ module.exports = async (connection, reference, mailbox, options) => {
             }
         }
 
+        // INBOX should always appear as subscribed regardless of LSUB results
         let inboxEntry = entries.find(entry => entry.specialUse === '\\Inbox');
         if (inboxEntry && !inboxEntry.subscribed) {
-            // override server settings and make INBOX always as subscribed
             inboxEntry.subscribed = true;
         }
 
+        // Sort: special-use mailboxes first (in FLAG_SORT_ORDER), then alphabetically
+        // by path segments for a natural folder hierarchy ordering.
         return entries.sort((a, b) => {
             if (a.specialUse && !b.specialUse) {
                 return -1;

package/lib/commands/login.js

@@ -2,7 +2,15 @@
 
 const { getStatusCode, getErrorText } = require('../tools.js');
 
-// Authenticates user using LOGIN
+/**
+ * Authenticates user using the IMAP LOGIN command.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} username - The username to authenticate with
+ * @param {string} password - The password to authenticate with
+ * @returns {Promise<string|undefined>} The authenticated username, or undefined if already authenticated
+ * @throws {Error} If authentication fails, with authenticationFailed and serverResponseCode properties set
+ */
 module.exports = async (connection, username, password) => {
     if (connection.state !== connection.states.NOT_AUTHENTICATED) {
         // nothing to do here
@@ -12,10 +20,13 @@ module.exports = async (connection, username, password) => {
     try {
         let response = await connection.exec('LOGIN', [
             { type: 'STRING', value: username },
+            // sensitive: true prevents the password from appearing in debug logs
             { type: 'STRING', value: password, sensitive: true }
         ]);
         response.next();
 
+        // Record that LOGIN was the method used, so the connection knows which
+        // auth mechanism succeeded (used for reconnection and diagnostics).
         connection.authCapabilities.set('LOGIN', true);
 
         return username;

package/lib/commands/logout.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// Logs out user and closes connection
+/**
+ * Logs out the user and closes the connection.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<boolean>} True if logout command succeeded, false otherwise
+ */
 module.exports = async connection => {
     if (connection.state === connection.states.LOGOUT) {
         // nothing to do here
@@ -8,6 +13,7 @@ module.exports = async connection => {
     }
 
     if (connection.state === connection.states.NOT_AUTHENTICATED) {
+        // Not yet authenticated -- no LOGOUT command needed; just close the socket.
         connection.state = connection.states.LOGOUT;
         connection.close();
         return false;
@@ -18,13 +24,16 @@ module.exports = async connection => {
         response = await connection.exec('LOGOUT');
         return true;
     } catch (err) {
+        // If the connection is already gone, treat as successful logout
         if (err.code === 'NoConnection') {
             return true;
         }
         connection.log.warn({ err, cid: connection.id });
         return false;
     } finally {
-        // close even if command failed
+        // Set state to LOGOUT before closing to prevent any further commands from
+        // being queued. The socket is closed unconditionally in this finally block
+        // regardless of whether the LOGOUT command succeeded or failed.
         connection.state = connection.states.LOGOUT;
         if (response && typeof response.next === 'function') {
             response.next();

package/lib/commands/move.js

@@ -2,7 +2,16 @@
 
 const { normalizePath, encodePath, expandRange, enhanceCommandError } = require('../tools.js');
 
-// Moves messages from current mailbox to some other mailbox
+/**
+ * Moves messages from the current mailbox to another mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {string} destination - Destination mailbox path
+ * @param {Object} [options] - Move options
+ * @param {boolean} [options.uid] - If true, use UID MOVE instead of MOVE
+ * @returns {Promise<{path: string, destination: string, uidValidity?: BigInt, uidMap?: Map}|boolean|undefined>} Move result with UID mapping if available, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, range, destination, options) => {
     if (connection.state !== connection.states.SELECTED || !range || !destination) {
         // nothing to do here
@@ -19,12 +28,17 @@ module.exports = async (connection, range, destination, options) => {
 
     let map = { path: connection.mailbox.path, destination };
 
+    // Fallback for servers without the MOVE extension (RFC 6851):
+    // emulate MOVE using COPY + flag as \Deleted + EXPUNGE.
     if (!connection.capabilities.has('MOVE')) {
         let result = await connection.messageCopy(range, destination, options);
         await connection.messageDelete(range, Object.assign({ silent: true }, options));
         return result;
     }
 
+    // Extract COPYUID response code (UIDPLUS, RFC 4315) from either an untagged
+    // OK response or the final tagged OK. MOVE uses the same COPYUID format as COPY
+    // to report the source-to-destination UID mapping.
     let checkMoveInfo = response => {
         let section = response.attributes && response.attributes[0] && response.attributes[0].section;
         let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
@@ -48,6 +62,8 @@ module.exports = async (connection, range, destination, options) => {
 
     let response;
     try {
+        // Some servers send COPYUID in an untagged OK before the tagged response,
+        // others include it in the tagged OK. We check both to be safe.
         response = await connection.exec(options.uid ? 'UID MOVE' : 'MOVE', attributes, {
             untagged: {
                 OK: async untagged => {

package/lib/commands/namespace.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// Requests NAMESPACE info from server
+/**
+ * Requests NAMESPACE info from the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<{prefix: string, delimiter: string}|{error: boolean, status: string, text: string}>} The primary personal namespace, or an error object on failure
+ */
 module.exports = async connection => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
@@ -8,8 +13,12 @@ module.exports = async connection => {
     }
 
     if (!connection.capabilities.has('NAMESPACE')) {
-        // try to derive from listing
+        // Fallback: when the server does not support the NAMESPACE extension (RFC 2342),
+        // derive the prefix and delimiter from a LIST "" "" command, which returns
+        // the hierarchy delimiter and root name for the default mailbox hierarchy.
         let { prefix, delimiter } = await getListPrefix(connection);
+        // Ensure the prefix ends with the delimiter so that appending a mailbox name
+        // produces a valid path (e.g., "INBOX." + "Sent" = "INBOX.Sent").
         if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
             prefix += delimiter;
         }
@@ -28,6 +37,11 @@ module.exports = async connection => {
         let map = {};
         response = await connection.exec('NAMESPACE', false, {
             untagged: {
+                // The NAMESPACE response (RFC 2342) contains exactly three sections:
+                //   [0] = personal namespaces (user's own mailboxes)
+                //   [1] = other users' namespaces (shared by other users)
+                //   [2] = shared namespaces (public/organizational folders)
+                // Each section is either NIL or a list of (prefix, delimiter) pairs.
                 NAMESPACE: async untagged => {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
@@ -60,10 +74,18 @@ module.exports = async connection => {
     }
 };
 
+/**
+ * Derives namespace prefix and delimiter from a LIST command when NAMESPACE is not supported.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<{prefix?: string, delimiter?: string, flags?: Set}>} Object with prefix, delimiter, and flags, or empty object on failure
+ */
 async function getListPrefix(connection) {
     let response;
     try {
         let map = {};
+        // LIST "" "" is a special form that returns only the hierarchy delimiter
+        // and the root name, without listing any actual mailboxes.
         response = await connection.exec('LIST', ['', ''], {
             untagged: {
                 LIST: async untagged => {
@@ -88,6 +110,12 @@ async function getListPrefix(connection) {
     }
 }
 
+/**
+ * Parses namespace information from an IMAP NAMESPACE response attribute.
+ *
+ * @param {Array} attribute - Namespace attribute array from the server response
+ * @returns {Array<{prefix: string, delimiter: string}>|boolean} Array of namespace entries, or false if empty
+ */
 function getNamsepaceInfo(attribute) {
     if (!attribute || !attribute.length) {
         return false;
@@ -99,6 +127,8 @@ function getNamsepaceInfo(attribute) {
             let prefix = entry[0].value;
             let delimiter = entry[1].value;
 
+            // Append the delimiter to the prefix if it doesn't already end with one,
+            // so callers can construct full paths by simply concatenating prefix + name.
             if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
                 prefix += delimiter;
             }

package/lib/commands/noop.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// Sends a NO-OP command
+/**
+ * Sends a NOOP command to the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<boolean>} True on success, false on failure
+ */
 module.exports = async connection => {
     try {
         let response = await connection.exec('NOOP', false, { comment: 'Requested by command' });

package/lib/commands/quota.js

@@ -2,7 +2,13 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Requests quota information for a mailbox
+/**
+ * Requests quota information for a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to query quota for
+ * @returns {Promise<{path: string, quotaRoot?: string, storage?: {usage: number, limit: number, status: string}, message?: {usage: number, limit: number, status: string}}|boolean|undefined>} Quota information object, false if QUOTA not supported or on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !path) {
         // nothing to do here
@@ -17,6 +23,11 @@ module.exports = async (connection, path) => {
 
     let map = { path };
 
+    // Parse a QUOTA response. The resource list uses a repeating triplet pattern (i % 3):
+    //   position 0: resource name (e.g., "STORAGE", "MESSAGE")
+    //   position 1: current usage
+    //   position 2: limit
+    // Storage values are in KB on the wire; multiply by 1024 to report bytes.
     let processQuotaResponse = untagged => {
         let attributes = untagged.attributes && untagged.attributes[1];
         if (!attributes || !attributes.length) {
@@ -25,10 +36,13 @@ module.exports = async (connection, path) => {
 
         let key = false;
         attributes.forEach((attribute, i) => {
-            if (i % 3 === 0) {
+            const position = i % 3;
+
+            if (position === 0) {
                 key = attribute && typeof attribute.value === 'string' ? attribute.value.toLowerCase() : false;
                 return;
             }
+
             if (!key) {
                 return;
             }
@@ -38,21 +52,18 @@ module.exports = async (connection, path) => {
                 return;
             }
 
-            if (i % 3 === 1) {
-                // usage
-                if (!map[key]) {
-                    map[key] = {};
-                }
-                map[key].usage = value * (key === 'storage' ? 1024 : 1);
+            if (!map[key]) {
+                map[key] = {};
             }
 
-            if (i % 3 === 2) {
-                // limit
-                if (!map[key]) {
-                    map[key] = {};
-                }
-                map[key].limit = value * (key === 'storage' ? 1024 : 1);
+            // Storage quota is reported in KB by IMAP; convert to bytes for consistency
+            const multiplier = key === 'storage' ? 1024 : 1;
 
+            if (position === 1) {
+                map[key].usage = value * multiplier;
+            } else if (position === 2) {
+                map[key].limit = value * multiplier;
+                // Calculate usage percentage for convenient display
                 if (map[key].limit) {
                     map[key].status = Math.round(((map[key].usage || 0) / map[key].limit) * 100) + '%';
                 }
@@ -63,8 +74,13 @@ module.exports = async (connection, path) => {
     let quotaFound = false;
     let response;
     try {
+        // Two-step quota lookup: GETQUOTAROOT identifies the quota root for a mailbox,
+        // and the server usually sends the QUOTA response inline. Some servers only
+        // send the root name and require a separate GETQUOTA command.
         response = await connection.exec('GETQUOTAROOT', [{ type: 'ATOM', value: encodePath(connection, path) }], {
             untagged: {
+                // QUOTAROOT response tells us which quota root applies to this mailbox.
+                // A mailbox may have zero or one quota root.
                 QUOTAROOT: async untagged => {
                     let quotaRoot =
                         untagged.attributes && untagged.attributes[1] && typeof untagged.attributes[1].value === 'string'
@@ -74,6 +90,7 @@ module.exports = async (connection, path) => {
                         map.quotaRoot = quotaRoot;
                     }
                 },
+                // QUOTA response provides the actual resource usage and limits
                 QUOTA: async untagged => {
                     quotaFound = true;
                     processQuotaResponse(untagged);
@@ -83,6 +100,8 @@ module.exports = async (connection, path) => {
 
         response.next();
 
+        // Fallback: if we got a quota root but no QUOTA response inline,
+        // explicitly request quota for that root.
         if (map.quotaRoot && !quotaFound) {
             response = await connection.exec('GETQUOTA', [{ type: 'ATOM', value: map.quotaRoot }], {
                 untagged: {

package/lib/commands/rename.js

@@ -2,16 +2,28 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Renames existing mailbox
+/**
+ * Renames an existing mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Current mailbox path
+ * @param {string} newPath - New mailbox path
+ * @returns {Promise<{path: string, newPath: string}|undefined>} Object with old and new paths, or undefined if preconditions not met
+ * @throws {Error} If the RENAME command fails
+ */
 module.exports = async (connection, path, newPath) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
         return;
     }
 
+    // Normalize both paths (resolve special names, apply namespace prefix) and encode
+    // them for the IMAP wire format (modified UTF-7 for non-ASCII characters).
     path = normalizePath(connection, path);
     newPath = normalizePath(connection, newPath);
 
+    // Must close/deselect the mailbox before renaming if it's currently selected,
+    // as IMAP servers will not rename an active mailbox.
     if (connection.state === connection.states.SELECTED && connection.mailbox.path === path) {
         await connection.run('CLOSE');
     }