imapflow 1.2.8 → 1.2.10

package/lib/commands/id.js

@@ -2,7 +2,15 @@
 
 const { formatDateTime } = require('../tools.js');
 
-// Sends ID info to server and updates server info data based on response
+/**
+ * Sends ID info to the server and updates server info data based on the response.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {Object} clientInfo - Client identification key-value pairs to send to the server
+ * @returns {Promise<Object|boolean|undefined>} Server information map, false on failure, or undefined if ID not supported
+ */
+// RFC 2971: The ID command exchanges client/server implementation info
+// (name, version, vendor, etc.) for diagnostic and compatibility purposes.
 module.exports = async (connection, clientInfo) => {
     if (!connection.capabilities.has('ID')) {
         // nothing to do here
@@ -13,7 +21,8 @@ module.exports = async (connection, clientInfo) => {
     try {
         let map = {};
 
-        // convert object into an array of value tuples
+        // Convert the clientInfo object into a flat array of alternating key-value strings
+        // for the IMAP wire format: ("key1" "value1" "key2" "value2" ...)
         let formattedClientInfo = !clientInfo
             ? null
             : Object.keys(clientInfo)
@@ -28,6 +37,8 @@ module.exports = async (connection, clientInfo) => {
 
         response = await connection.exec('ID', [formattedClientInfo], {
             untagged: {
+                // Parse the server's ID response: a flat list of alternating key-value atoms.
+                // Even indices (i % 2 === 0) are keys, odd indices are the corresponding values.
                 ID: async untagged => {
                     let params = untagged.attributes && untagged.attributes[0];
                     let key;
@@ -50,10 +61,18 @@ module.exports = async (connection, clientInfo) => {
     }
 };
 
+/**
+ * Formats a client info value for the ID command.
+ *
+ * @param {string} key - The info key name
+ * @param {*} value - The value to format
+ * @returns {string} Formatted value string
+ */
 function formatValue(key, value) {
     switch (key.toLowerCase()) {
         case 'date':
-            // Date has to be in imap date-time format
+            // RFC 2971 requires the "date" field to use IMAP date-time format
+            // (e.g., "06-Feb-2026 12:00:00 +0000"), not ISO 8601 or other formats.
             return formatDateTime(value);
         default:
             // Other values are strings without newlines

package/lib/commands/idle.js

@@ -2,18 +2,31 @@
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
+/**
+ * Runs a single IDLE session on the connection.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<void|boolean>} Void on success, false on failure
+ */
 async function runIdle(connection) {
     let response;
 
+    // Queue of promises waiting for IDLE to break. When another command needs to run,
+    // it calls connection.preCheck() which queues a promise here and sends DONE to break IDLE.
     let preCheckWaitQueue = [];
     try {
         connection.idling = true;
 
-        //let idleSent = false;
+        // State flags for the IDLE lifecycle:
+        // - doneRequested: someone wants to break IDLE (e.g., to run another command)
+        // - doneSent: we've already sent the DONE command to server
+        // - canEnd: server has acknowledged IDLE with "+" continuation, so DONE can be sent
         let doneRequested = false;
         let doneSent = false;
         let canEnd = false;
 
+        // preCheck sends DONE to break out of IDLE. Called when another command
+        // needs to run on this connection (e.g., a FETCH or STORE from user code).
         let preCheck = async () => {
             doneRequested = true;
             if (canEnd && !doneSent) {
@@ -37,6 +50,8 @@ async function runIdle(connection) {
             }
         };
 
+        // Public interface for breaking IDLE. Returns a promise that resolves when
+        // IDLE is actually broken and the connection is free for other commands.
         let connectionPreCheck = () => {
             let handler = new Promise((resolve, reject) => {
                 preCheckWaitQueue.push({ resolve, reject });
@@ -57,9 +72,13 @@ async function runIdle(connection) {
             return handler;
         };
 
+        // Register preCheck on the connection so other code (e.g., getMailboxLock) can break IDLE
         connection.preCheck = connectionPreCheck;
 
         response = await connection.exec('IDLE', false, {
+            // Server responds with "+" continuation to acknowledge IDLE mode.
+            // After this, the server will push untagged responses for mailbox changes.
+            // We can now safely send DONE if a break was already requested.
             onPlusTag: async () => {
                 connection.log.debug({ msg: `Initiated IDLE, waiting for server input`, lockId: connection.currentLock?.lockId, doneRequested });
                 canEnd = true;
@@ -76,7 +95,8 @@ async function runIdle(connection) {
             }
         });
 
-        // unset before response.next() if preCheck function is not already cleared (usually is)
+        // Clean up: unset preCheck and resolve any remaining waiters before processing the response.
+        // Usually preCheck is already cleared by the DONE handler, but this handles edge cases.
         if (typeof connection.preCheck === 'function' && connection.preCheck === connectionPreCheck) {
             connection.log.trace({
                 msg: 'Clearing pre-check function',
@@ -109,16 +129,26 @@ async function runIdle(connection) {
     }
 }
 
-// Listens for changes in mailbox
+/**
+ * Listens for changes in the selected mailbox using IDLE or NOOP polling fallback.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {number} [maxIdleTime] - Maximum time in milliseconds to stay in IDLE before restarting
+ * @returns {Promise<void|boolean|undefined>} Void on success, false on failure, or undefined if not in SELECTED state
+ */
 module.exports = async (connection, maxIdleTime) => {
     if (connection.state !== connection.states.SELECTED) {
         // nothing to do here
         return;
     }
 
+    // If server supports IDLE (RFC 2177), use it for real-time push notifications.
+    // Otherwise, fall back to periodic polling with NOOP/STATUS/SELECT.
     if (connection.capabilities.has('IDLE')) {
         let idleTimer;
         let stillIdling = false;
+        // IDLE loop: runs IDLE, and if maxIdleTime is reached, breaks and restarts
+        // to keep the connection alive (some servers drop long-running IDLEs).
         let runIdleLoop = async () => {
             if (maxIdleTime) {
                 idleTimer = setTimeout(() => {
@@ -143,13 +173,15 @@ module.exports = async (connection, maxIdleTime) => {
         return runIdleLoop();
     }
 
+    // Fallback for servers without IDLE support: poll at regular intervals using
+    // NOOP (default), STATUS, or SELECT depending on missingIdleCommand config.
     let idleTimer;
     return new Promise(resolve => {
         if (!connection.currentSelectCommand) {
             return resolve();
         }
 
-        // no IDLE support, fallback to NOOP'ing
+        // Set up preCheck so other commands can break the polling loop
         connection.preCheck = async () => {
             connection.preCheck = false; // unset itself
             clearTimeout(idleTimer);
@@ -160,6 +192,9 @@ module.exports = async (connection, maxIdleTime) => {
 
         let selectCommand = connection.currentSelectCommand;
 
+        // Run one polling check. The method used depends on configuration:
+        // SELECT re-selects the mailbox (may detect changes), STATUS queries mailbox counters,
+        // NOOP is the simplest but relies on server pushing untagged responses.
         let idleCheck = async () => {
             let response;
             switch (connection.missingIdleCommand) {

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 => {