imapflow 1.2.8 → 1.2.10

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');
     }

package/lib/commands/search.js

@@ -3,7 +3,15 @@
 const { enhanceCommandError } = require('../tools.js');
 const { searchCompiler } = require('../search-compiler.js');
 
-// Updates flags for a message
+/**
+ * Searches for messages matching the specified criteria.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {Object|boolean} query - Search query object, or true/empty object to match all messages
+ * @param {Object} [options] - Search options
+ * @param {boolean} [options.uid] - If true, use UID SEARCH instead of SEARCH
+ * @returns {Promise<number[]|boolean>} Sorted array of matching sequence numbers or UIDs, or false on failure
+ */
 module.exports = async (connection, query, options) => {
     if (connection.state !== connection.states.SELECTED) {
         // nothing to do here
@@ -14,6 +22,10 @@ module.exports = async (connection, query, options) => {
 
     let attributes;
 
+    // Three query branches:
+    // 1. Empty/truthy/all-only query -> use IMAP "SEARCH ALL" to match every message
+    // 2. Non-empty object -> compile into IMAP SEARCH criteria via searchCompiler
+    // 3. Anything else (unexpected type) -> bail out with false
     if (!query || query === true || (typeof query === 'object' && (!Object.keys(query).length || (Object.keys(query).length === 1 && query.all)))) {
         // search for all messages
         attributes = [{ type: 'ATOM', value: 'ALL' }];
@@ -24,6 +36,8 @@ module.exports = async (connection, query, options) => {
         return false;
     }
 
+    // Use a Set to deduplicate sequence numbers/UIDs -- servers may return
+    // duplicates across multiple untagged SEARCH responses.
     let results = new Set();
     let response;
     try {
@@ -41,6 +55,7 @@ module.exports = async (connection, query, options) => {
             }
         });
         response.next();
+        // Sort numerically for consistent, predictable output order
         return Array.from(results).sort((a, b) => a - b);
     } catch (err) {
         await enhanceCommandError(err);

package/lib/commands/select.js

@@ -2,7 +2,18 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Selects a mailbox
+/**
+ * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to select
+ * @param {Object} [options] - Select options
+ * @param {boolean} [options.readOnly] - If true, use EXAMINE instead of SELECT (read-only access)
+ * @param {string} [options.changedSince] - QRESYNC modseq value to fetch changes since
+ * @param {BigInt} [options.uidValidity] - QRESYNC UID validity value
+ * @returns {Promise<Object|undefined>} Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
+ * @throws {Error} If the SELECT/EXAMINE command fails
+ */
 module.exports = async (connection, path, options) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
@@ -12,6 +23,8 @@ module.exports = async (connection, path, options) => {
 
     path = normalizePath(connection, path);
 
+    // Ensure we have folder metadata (delimiter, flags, specialUse) by running LIST if needed.
+    // This is cached in connection.folders to avoid repeated LIST calls.
     if (!connection.folders.has(path)) {
         let folders = await connection.run('LIST', '', path);
         if (!folders) {
@@ -35,6 +48,9 @@ module.exports = async (connection, path, options) => {
             });
         }
 
+        // QRESYNC (RFC 7162): allows efficient mailbox resynchronization by sending
+        // the last known UIDVALIDITY and HIGHESTMODSEQ. Server responds with only
+        // the changes (new flags, expunged UIDs) since that point.
         let extraArgs = [];
         if (connection.enabled.has('QRESYNC') && options.changedSince && options.uidValidity) {
             extraArgs.push([
@@ -49,6 +65,9 @@ module.exports = async (connection, path, options) => {
 
         let encodedPath = encodePath(connection, path);
 
+        // SELECT opens the mailbox read-write; EXAMINE opens it read-only.
+        // Path encoding: if the encoded path contains '&' (UTF-7 encoding marker),
+        // send as quoted STRING to avoid parser issues with the ampersand.
         let selectCommand = {
             command: !options.readOnly ? 'SELECT' : 'EXAMINE',
             arguments: [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || [])
@@ -56,15 +75,22 @@ module.exports = async (connection, path, options) => {
 
         response = await connection.exec(selectCommand.command, selectCommand.arguments, {
             untagged: {
+                // Untagged OK responses carry response codes in brackets, e.g.:
+                // * OK [UIDVALIDITY 1234] UIDs valid
+                // * OK [PERMANENTFLAGS (\Seen \Answered \*)] Flags permitted
+                // The section array holds the parsed bracket contents: section[0] is the
+                // key (e.g., "UIDVALIDITY"), section[1] is the value or list.
                 OK: async untagged => {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
                     }
                     let section = !untagged.attributes[0].value && untagged.attributes[0].section;
+                    // Handle response codes with a key-value pair (section has 2+ elements)
                     if (section && section.length > 1 && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
                         let key = section[0].value.toLowerCase();
                         let value;
 
+                        // Value can be a single string or a list of strings (e.g., PERMANENTFLAGS)
                         if (typeof section[1].value === 'string') {
                             value = section[1].value;
                         } else if (Array.isArray(section[1])) {
@@ -72,6 +98,10 @@ module.exports = async (connection, path, options) => {
                         }
 
                         switch (key) {
+                            // CONDSTORE (RFC 7162): highest mod-sequence value for the mailbox.
+                            // Used for incremental sync -- clients compare against their cached
+                            // value to detect changes. Stored as BigInt since modseq values
+                            // can exceed Number.MAX_SAFE_INTEGER.
                             case 'highestmodseq':
                                 key = 'highestModseq';
                                 if (/^[0-9]+$/.test(value)) {
@@ -79,6 +109,9 @@ module.exports = async (connection, path, options) => {
                                 }
                                 break;
 
+                            // OBJECTID (RFC 8474): server-assigned unique mailbox identifier.
+                            // Unlike path, this ID survives renames. Value comes as a
+                            // parenthesized list, so extract the first (only) element.
                             case 'mailboxid':
                                 key = 'mailboxId';
                                 if (Array.isArray(value) && value.length) {
@@ -86,16 +119,23 @@ module.exports = async (connection, path, options) => {
                                 }
                                 break;
 
+                            // Flags that the client can change permanently on messages in
+                            // this mailbox. Includes \* if the server allows custom flags.
                             case 'permanentflags':
                                 key = 'permanentFlags';
                                 value = new Set(value);
                                 break;
 
+                            // The next UID that will be assigned to a new message in this
+                            // mailbox. Useful for detecting new arrivals.
                             case 'uidnext':
                                 key = 'uidNext';
                                 value = Number(value);
                                 break;
 
+                            // Unique identifier validity value. If this changes between
+                            // sessions, all previously cached UIDs are invalid and the
+                            // client must re-sync from scratch.
                             case 'uidvalidity':
                                 key = 'uidValidity';
                                 if (/^[0-9]+$/.test(value)) {
@@ -107,9 +147,12 @@ module.exports = async (connection, path, options) => {
                         map[key] = value;
                     }
 
+                    // Handle response codes with only a keyword (no value), e.g., [NOMODSEQ]
                     if (section && section.length === 1 && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
                         let key = section[0].value.toLowerCase();
                         switch (key) {
+                            // NOMODSEQ means the mailbox does not support mod-sequences.
+                            // CONDSTORE/QRESYNC features are unavailable for this mailbox.
                             case 'nomodseq':
                                 key = 'noModseq';
                                 map[key] = true;
@@ -117,6 +160,9 @@ module.exports = async (connection, path, options) => {
                         }
                     }
                 },
+
+                // Untagged FLAGS response lists all flags defined for this mailbox
+                // (both system flags and custom flags). Example: * FLAGS (\Seen \Answered \Flagged)
                 FLAGS: async untagged => {
                     if (!untagged.attributes || (!untagged.attributes.length && Array.isArray(untagged.attributes[0]))) {
                         return;
@@ -124,6 +170,9 @@ module.exports = async (connection, path, options) => {
                     let flags = untagged.attributes[0].map(flag => (typeof flag.value === 'string' ? flag.value : false)).filter(flag => flag);
                     map.flags = new Set(flags);
                 },
+
+                // Untagged EXISTS response: "* <count> EXISTS" tells us the total number
+                // of messages in the mailbox. The count is in the command field (numeric prefix).
                 EXISTS: async untagged => {
                     let num = Number(untagged.command);
                     if (isNaN(num)) {
@@ -132,58 +181,51 @@ module.exports = async (connection, path, options) => {
 
                     map.exists = num;
                 },
+
+                // VANISHED responses (QRESYNC): server reports UIDs that have been expunged
+                // since the client's last known state. Only received when QRESYNC was requested.
+                // A dummy mailbox object is passed because the mailbox isn't officially open yet.
                 VANISHED: async untagged => {
-                    await connection.untaggedVanished(
-                        untagged,
-                        // mailbox is not yet open, so use a dummy mailbox object
-                        { path, uidNext: false, uidValidity: false }
-                    );
+                    await connection.untaggedVanished(untagged, { path, uidNext: false, uidValidity: false });
                 },
-                // we should only get an untagged FETCH for a SELECT/EXAMINE if QRESYNC was asked for
+
+                // Untagged FETCH during SELECT/EXAMINE: only occurs with QRESYNC, delivering
+                // updated flags for messages that changed since the client's last modseq.
                 FETCH: async untagged => {
-                    await connection.untaggedFetch(
-                        untagged,
-                        // mailbox is not yet open, so use a dummy mailbox object
-                        { path, uidNext: false, uidValidity: false }
-                    );
+                    await connection.untaggedFetch(untagged, { path, uidNext: false, uidValidity: false });
                 }
             }
         });
 
+        // The tagged OK response to SELECT/EXAMINE includes [READ-ONLY] or [READ-WRITE]
+        // in its response code, indicating the access mode the server granted.
         let section = !response.response.attributes[0].value && response.response.attributes[0].section;
         if (section && section.length && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
-            switch (section[0].value.toUpperCase()) {
-                case 'READ-ONLY':
-                    map.readOnly = true;
-                    break;
-                case 'READ-WRITE':
-                default:
-                    map.readOnly = false;
-                    break;
-            }
+            map.readOnly = section[0].value.toUpperCase() === 'READ-ONLY';
         }
 
-        if (
-            map.qresync &&
-            // UIDVALIDITY must be the same
-            (options.uidValidity !== map.uidValidity ||
-                // HIGHESTMODSEQ response must be present
-                !map.highestModseq ||
-                // NOMODSEQ is not allowed
-                map.noModseq)
-        ) {
-            // QRESYNC does not apply here, so unset it
+        // Validate QRESYNC preconditions (RFC 7162 Section 3.2.5):
+        // QRESYNC results are only valid if UIDVALIDITY matches, HIGHESTMODSEQ is
+        // present, and the mailbox supports mod-sequences. If any condition fails,
+        // the client cannot trust the incremental updates and must do a full resync.
+        if (map.qresync && (options.uidValidity !== map.uidValidity || !map.highestModseq || map.noModseq)) {
             map.qresync = false;
         }
 
+        // Transition mailbox state: save previous mailbox reference, temporarily
+        // clear it, then emit events and set the new mailbox.
         let currentMailbox = connection.mailbox;
         connection.mailbox = false;
 
+        // Emit mailboxClose if we're switching from a different mailbox.
+        // Re-selecting the same mailbox (e.g., for resync) does not trigger close/open.
         if (currentMailbox && currentMailbox.path !== path) {
             connection.emit('mailboxClose', currentMailbox);
         }
 
         connection.mailbox = map;
+        // Save the SELECT command for potential re-use (e.g., NOOP fallback polling
+        // re-issues the SELECT to detect changes on servers without IDLE support).
         connection.currentSelectCommand = selectCommand;
         connection.state = connection.states.SELECTED;
 
@@ -196,9 +238,10 @@ module.exports = async (connection, path, options) => {
     } catch (err) {
         await enhanceCommandError(err);
 
+        // If SELECT/EXAMINE fails while a mailbox was already selected, we must
+        // reset to AUTHENTICATED state since the server has implicitly deselected
+        // the previous mailbox on failure (RFC 3501 Section 6.3.1).
         if (connection.state === connection.states.SELECTED) {
-            // reset selected state
-
             let currentMailbox = connection.mailbox;
 
             connection.mailbox = false;

package/lib/commands/starttls.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// Requests STARTTLS info from server
+/**
+ * Initiates STARTTLS connection upgrade.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<boolean>} True if STARTTLS was initiated, false if not supported or already secure
+ */
 module.exports = async connection => {
     if (!connection.capabilities.has('STARTTLS') || connection.secureConnection) {
         // nothing to do here