imapflow 1.2.7 → 1.2.9

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

package/lib/commands/status.js

@@ -2,7 +2,15 @@
 
 const { encodePath, normalizePath } = require('../tools.js');
 
-// Requests info about a mailbox
+/**
+ * Requests status information about a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to query
+ * @param {Object} query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
+ * @returns {Promise<{path: string, messages?: number, recent?: number, uidNext?: number, uidValidity?: BigInt, unseen?: number, highestModseq?: BigInt}|boolean>} Status information object, or false if preconditions not met or on failure
+ * @throws {Error} If the mailbox does not exist
+ */
 module.exports = async (connection, path, query) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !path) {
         // nothing to do here
@@ -12,8 +20,12 @@ module.exports = async (connection, path, query) => {
     path = normalizePath(connection, path);
     let encodedPath = encodePath(connection, path);
 
+    // Use quoted STRING if the encoded path contains '&' (modified UTF-7 marker),
+    // otherwise use unquoted ATOM. Same approach as in SELECT.
     let attributes = [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }];
 
+    // Build the list of STATUS data items the caller wants.
+    // HIGHESTMODSEQ requires the CONDSTORE extension to be available.
     let queryAttributes = [];
     Object.keys(query || {}).forEach(key => {
         if (!query[key]) {
@@ -48,14 +60,50 @@ module.exports = async (connection, path, query) => {
         let map = { path };
         response = await connection.exec('STATUS', attributes, {
             untagged: {
+                // STATUS response: * STATUS <mailbox> (<key> <value> <key> <value> ...)
+                // Parsed as alternating key-value pairs (i % 2 pattern).
                 STATUS: async untagged => {
-                    // If STATUS is for current mailbox then update mailbox values
+                    // If querying the currently selected mailbox, also update the
+                    // connection's live mailbox state and emit events for changes.
                     let updateCurrent = connection.state === connection.states.SELECTED && path === connection.mailbox.path;
 
                     let list = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
                     if (!list) {
                         return;
                     }
+                    // Maps IMAP STATUS field names to their output key names, type parsers,
+                    // and optional callbacks to update the live mailbox state.
+                    const STATUS_FIELD_MAP = {
+                        MESSAGES: {
+                            key: 'messages',
+                            parser: Number,
+                            updateMailbox: (val, conn) => {
+                                let prevCount = conn.mailbox.exists;
+                                if (prevCount !== val) {
+                                    conn.mailbox.exists = val;
+                                    conn.emit('exists', { path, count: val, prevCount });
+                                }
+                            }
+                        },
+                        RECENT: { key: 'recent', parser: Number },
+                        UIDNEXT: {
+                            key: 'uidNext',
+                            parser: Number,
+                            updateMailbox: (val, conn) => {
+                                conn.mailbox.uidNext = val;
+                            }
+                        },
+                        UIDVALIDITY: { key: 'uidValidity', parser: BigInt },
+                        UNSEEN: { key: 'unseen', parser: Number },
+                        HIGHESTMODSEQ: {
+                            key: 'highestModseq',
+                            parser: BigInt,
+                            updateMailbox: (val, conn) => {
+                                conn.mailbox.highestModseq = val;
+                            }
+                        }
+                    };
+
                     let key;
                     list.forEach((entry, i) => {
                         if (i % 2 === 0) {
@@ -65,61 +113,22 @@ module.exports = async (connection, path, query) => {
                         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;
-                                if (updateCurrent) {
-                                    let prevCount = connection.mailbox.exists;
-                                    if (prevCount !== value) {
-                                        // somehow message count in current folder has changed?
-                                        connection.mailbox.exists = value;
-                                        connection.emit('exists', {
-                                            path,
-                                            count: value,
-                                            prevCount
-                                        });
-                                    }
-                                }
-                                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;
-                                if (updateCurrent) {
-                                    connection.mailbox.uidNext = value;
-                                }
-                                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;
-                                if (updateCurrent) {
-                                    connection.mailbox.highestModseq = value;
-                                }
-                                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;
+
+                        if (updateCurrent && fieldConfig.updateMailbox) {
+                            fieldConfig.updateMailbox(value, connection);
+                        }
                     });
                 }
             }
@@ -127,6 +136,9 @@ module.exports = async (connection, path, query) => {
         response.next();
         return map;
     } catch (err) {
+        // A NO response usually means the mailbox doesn't exist. Verify by
+        // running LIST -- if no results, throw a clear NotFound error instead
+        // of the generic IMAP error.
         if (err.responseStatus === 'NO') {
             let folders = await connection.run('LIST', '', path, { listOnly: true });
             if (folders && !folders.length) {

package/lib/commands/store.js

@@ -2,7 +2,20 @@
 
 const { formatFlag, canUseFlag, enhanceCommandError } = require('../tools.js');
 
-// Updates flags for a message
+/**
+ * Updates flags or labels for messages in the selected mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {string|string[]} flags - Flag(s) to set, add, or remove
+ * @param {Object} options - Store options
+ * @param {boolean} [options.uid] - If true, use UID STORE instead of STORE
+ * @param {boolean} [options.useLabels] - If true, operate on Gmail labels instead of flags
+ * @param {boolean} [options.silent] - If true, use .SILENT variant to suppress server response
+ * @param {string} [options.operation] - Operation type: 'set', 'add', or 'remove'
+ * @param {string} [options.unchangedSince] - Only update messages not changed since this modseq value
+ * @returns {Promise<boolean>} True on success, false on failure or if nothing to do
+ */
 module.exports = async (connection, range, flags, options) => {
     if (connection.state !== connection.states.SELECTED || !range || (options.useLabels && !connection.capabilities.has('X-GM-EXT-1'))) {
         // nothing to do here
@@ -10,19 +23,25 @@ module.exports = async (connection, range, flags, options) => {
     }
 
     options = options || {};
+
+    // Build the IMAP STORE operation name. The format is:
+    //   [+|-]FLAGS[.SILENT] or [+|-]X-GM-LABELS
+    // Where: no prefix = replace all, + = add, - = remove
+    // .SILENT suppresses the server from sending back updated flags (saves bandwidth).
     let operation;
 
     operation = 'FLAGS';
 
     if (options.useLabels) {
+        // Gmail labels (X-GM-EXT-1 extension): operates on labels instead of IMAP flags
         operation = 'X-GM-LABELS';
     } else if (options.silent) {
         operation = `${operation}.SILENT`;
     }
 
+    // Prefix determines the operation: none = set (replace), + = add, - = remove
     switch ((options.operation || '').toLowerCase()) {
         case 'set':
-            // do nothing, keep operation value as is
             break;
         case 'remove':
             operation = `-${operation}`;
@@ -33,12 +52,14 @@ module.exports = async (connection, range, flags, options) => {
             break;
     }
 
+    // Validate each flag: format it (normalize backslash prefix for system flags),
+    // then check if the mailbox's permanentFlags allow it. Removal is always allowed
+    // since it doesn't require the flag to be in permanentFlags.
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
             flag = formatFlag(flag);
 
             if (!canUseFlag(connection.mailbox, flag) && operation !== 'remove') {
-                // it does not seem that we can set this flag
                 return false;
             }
 
@@ -46,13 +67,15 @@ module.exports = async (connection, range, flags, options) => {
         })
         .filter(flag => flag);
 
+    // Allow empty flags only for 'set' operation (which clears all flags)
     if (!flags.length && options.operation !== 'set') {
-        // nothing to do here
         return false;
     }
 
     let attributes = [{ type: 'SEQUENCE', value: range }, { type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag }))];
 
+    // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
+    // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
     if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !connection.mailbox.noModseq) {
         attributes.push([
             {

package/lib/commands/subscribe.js

@@ -2,7 +2,13 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Subscribes to a mailbox
+/**
+ * Subscribes to a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to subscribe to
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here

package/lib/commands/unsubscribe.js

@@ -2,7 +2,13 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Unsubscribes from a mailbox
+/**
+ * Unsubscribes from a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to unsubscribe from
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here