imapflow 1.2.8 → 1.2.9

package/lib/commands/delete.js

@@ -2,7 +2,14 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Deletes an existing mailbox
+/**
+ * Deletes an existing mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to delete
+ * @returns {Promise<{path: string}|undefined>} Object with the deleted path, or undefined if preconditions not met
+ * @throws {Error} If the DELETE command fails
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
@@ -11,6 +18,8 @@ module.exports = async (connection, path) => {
 
     path = normalizePath(connection, path);
 
+    // If the mailbox to delete is currently selected, we must close/deselect it first.
+    // IMAP servers reject DELETE on the currently selected mailbox (RFC 3501 6.3.4).
     if (connection.state === connection.states.SELECTED && connection.mailbox.path === path) {
         await connection.run('CLOSE');
     }

package/lib/commands/enable.js

@@ -1,12 +1,20 @@
 'use strict';
 
-// Enables extensions
+/**
+ * Enables IMAP extensions on the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string[]} extensionList - List of extension names to enable
+ * @returns {Promise<Set|boolean|undefined>} Set of enabled extensions, false on failure, or undefined if not applicable
+ */
 module.exports = async (connection, extensionList) => {
     if (!connection.capabilities.has('ENABLE') || connection.state !== connection.states.AUTHENTICATED) {
         // nothing to do here
         return;
     }
 
+    // Pre-filter: only request extensions the server actually advertised in its
+    // CAPABILITY response. Requesting unsupported extensions would cause an error.
     extensionList = extensionList.filter(extension => connection.capabilities.has(extension.toUpperCase()));
     if (!extensionList.length) {
         return;
@@ -20,6 +28,9 @@ module.exports = async (connection, extensionList) => {
             extensionList.map(extension => ({ type: 'ATOM', value: extension.toUpperCase() })),
             {
                 untagged: {
+                    // The untagged ENABLED response is a flat list of extension names
+                    // (e.g., "* ENABLED CONDSTORE UTF8=ACCEPT"), NOT key-value pairs.
+                    // Each attribute is a single extension identifier.
                     ENABLED: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;

package/lib/commands/expunge.js

@@ -2,7 +2,15 @@
 
 const { enhanceCommandError } = require('../tools.js');
 
-// Deletes specified messages
+/**
+ * Deletes specified messages by flagging them as Deleted and expunging.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {Object} [options] - Expunge options
+ * @param {boolean} [options.uid] - If true, use UID EXPUNGE when UIDPLUS is available
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, range, options) => {
     if (connection.state !== connection.states.SELECTED || !range) {
         // nothing to do here
@@ -11,8 +19,14 @@ module.exports = async (connection, range, options) => {
 
     options = options || {};
 
+    // Two-step deletion process per IMAP protocol:
+    // Step 1: Mark the target messages with the \Deleted flag.
     await connection.messageFlagsAdd(range, ['\\Deleted'], options);
 
+    // Step 2: Issue EXPUNGE to permanently remove \Deleted messages.
+    // With UIDPLUS (RFC 4315): "UID EXPUNGE <uids>" removes only the specified UIDs,
+    // leaving other \Deleted messages untouched -- important for concurrent access.
+    // Without UIDPLUS: plain "EXPUNGE" removes ALL messages flagged \Deleted in the mailbox.
     let byUid = options.uid && connection.capabilities.has('UIDPLUS');
     let command = byUid ? 'UID EXPUNGE' : 'EXPUNGE';
     let attributes = byUid ? [{ type: 'SEQUENCE', value: range }] : false;
@@ -21,7 +35,9 @@ module.exports = async (connection, range, options) => {
     try {
         response = await connection.exec(command, attributes);
 
-        // A OK [HIGHESTMODSEQ 9122] Expunge completed (0.010 + 0.000 + 0.012 secs).
+        // CONDSTORE (RFC 7162): the server may return HIGHESTMODSEQ in the response code
+        // (e.g., "A OK [HIGHESTMODSEQ 9122] Expunge completed").
+        // Track this so the client can detect concurrent mailbox changes via mod-sequences.
         let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
         let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
         if (responseCode.toUpperCase() === 'HIGHESTMODSEQ') {

package/lib/commands/fetch.js

@@ -2,7 +2,19 @@
 
 const { formatMessageResponse } = require('../tools');
 
-// Fetches emails from server
+/**
+ * Fetches emails from the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {Object} query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
+ * @param {Object} [options] - Fetch options
+ * @param {boolean} [options.uid] - If true, use UID FETCH instead of FETCH
+ * @param {boolean} [options.binary] - If true, use BINARY fetch when available
+ * @param {string} [options.changedSince] - Only fetch messages changed since this modseq value
+ * @param {Function} [options.onUntaggedFetch] - Callback for processing each fetched message individually
+ * @returns {Promise<{count: number, list: Object[]}|undefined>} Object with message count and list, or undefined if not in SELECTED state
+ */
 module.exports = async (connection, range, query, options) => {
     if (connection.state !== connection.states.SELECTED || !range) {
         // nothing to do here
@@ -13,8 +25,10 @@ module.exports = async (connection, range, query, options) => {
 
     let mailbox = connection.mailbox;
 
+    // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY
     const commandKey = connection.capabilities.has('BINARY') && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
 
+    // Retry logic for ETHROTTLE errors (server rate limiting) with exponential backoff
     let retryCount = 0;
     const maxRetries = 4;
     const baseDelay = 1000; // Start with 1 second delay
@@ -31,6 +45,9 @@ module.exports = async (connection, range, query, options) => {
 
             let queryStructure = [];
 
+            // Helper to build BODY.PEEK[section]<partial> or BINARY.PEEK[section]<partial> atoms.
+            // PEEK avoids marking messages as \Seen. Section identifies what to fetch (HEADER, specific part, etc.)
+            // Partial is an optional byte range [start, maxLength].
             let setBodyPeek = (attributes, partial) => {
                 let bodyPeek = {
                     type: 'ATOM',
@@ -50,6 +67,7 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push(bodyPeek);
             };
 
+            // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
             ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
                 if (query[key]) {
                     queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
@@ -60,6 +78,7 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
 
+            // Fetch full message source, optionally with byte range (start/maxLength)
             if (query.source) {
                 let partial;
                 if (typeof query.source === 'object' && (query.source.start || query.source.maxLength)) {
@@ -71,13 +90,15 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: `${commandKey}.PEEK`, section: [], partial });
             }
 
-            // if possible, always request for unique email id
+            // Always request a unique email ID for message deduplication.
+            // Prefer OBJECTID (RFC 8474) over Gmail's X-GM-MSGID extension.
             if (connection.capabilities.has('OBJECTID')) {
                 queryStructure.push({ type: 'ATOM', value: 'EMAILID' });
             } else if (connection.capabilities.has('X-GM-EXT-1')) {
                 queryStructure.push({ type: 'ATOM', value: 'X-GM-MSGID' });
             }
 
+            // Thread ID: OBJECTID's THREADID or Gmail's X-GM-THRID
             if (query.threadId) {
                 if (connection.capabilities.has('OBJECTID')) {
                     queryStructure.push({ type: 'ATOM', value: 'THREADID' });
@@ -86,6 +107,7 @@ module.exports = async (connection, range, query, options) => {
                 }
             }
 
+            // Gmail labels are only available with X-GM-EXT-1 extension
             if (query.labels) {
                 if (connection.capabilities.has('X-GM-EXT-1')) {
                     queryStructure.push({ type: 'ATOM', value: 'X-GM-LABELS' });
@@ -97,11 +119,13 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: 'MODSEQ' });
             }
 
-            // always make sure to include UID in the request as well even though server might auto-add it itself
+            // Always include UID in the response even if not explicitly requested,
+            // since we use it internally for message identification and tracking
             if (!query.uid) {
                 queryStructure.push({ type: 'ATOM', value: 'UID' });
             }
 
+            // Headers: fetch all headers or only specific ones via HEADER.FIELDS
             if (query.headers) {
                 if (Array.isArray(query.headers)) {
                     setBodyPeek([{ type: 'ATOM', value: 'HEADER.FIELDS' }, query.headers.map(header => ({ type: 'ATOM', value: header }))]);
@@ -110,6 +134,8 @@ module.exports = async (connection, range, query, options) => {
                 }
             }
 
+            // Fetch specific body parts by MIME part number (e.g., "1", "1.2", "2.MIME")
+            // Each part can optionally include a byte range (start/maxLength)
             if (query.bodyParts && query.bodyParts.length) {
                 query.bodyParts.forEach(part => {
                     if (!part) {
@@ -138,12 +164,16 @@ module.exports = async (connection, range, query, options) => {
                 });
             }
 
+            // IMAP requires a single item to not be wrapped in parentheses, but
+            // multiple items must be in a list. If only one item, unwrap the array.
             if (queryStructure.length === 1) {
                 queryStructure = queryStructure.pop();
             }
 
             attributes.push(queryStructure);
 
+            // CONDSTORE extension: only fetch messages with modseq higher than the given value.
+            // QRESYNC adds VANISHED to also get expunged UIDs since last sync.
             if (options.changedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
                 let changedSinceArgs = [
                     {
@@ -168,6 +198,9 @@ module.exports = async (connection, range, query, options) => {
 
             response = await connection.exec(options.uid ? 'UID FETCH' : 'FETCH', attributes, {
                 untagged: {
+                    // Each matching message triggers an untagged FETCH response.
+                    // If onUntaggedFetch callback is provided, stream messages to it one by one
+                    // (useful for large result sets). Otherwise, collect all into messages.list.
                     FETCH: async untagged => {
                         messages.count++;
                         let formatted = await formatMessageResponse(untagged, mailbox);
@@ -192,7 +225,9 @@ module.exports = async (connection, range, query, options) => {
             return messages;
         } catch (err) {
             if (err.code === 'ETHROTTLE') {
-                // Calculate exponential backoff delay
+                // Server returned a throttle error (rate limiting). Retry with exponential backoff.
+                // Delay doubles each retry: 1s, 2s, 4s, 8s (capped at 30s).
+                // If server provides a throttleReset hint, use that if longer.
                 const backoffDelay = Math.min(baseDelay * Math.pow(2, retryCount), 30000); // Cap at 30 seconds
 
                 // Use throttle reset time if provided and longer than backoff

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