imapflow 1.2.8 → 1.2.10

package/lib/imap-flow.js

@@ -65,7 +65,7 @@ const states = {
  * @property {Set<string>} permanentFlags A Set of flags available to use in this mailbox. If it is not set or includes special flag "\\\*" then any flag can be used.
  * @property {String} [mailboxId] unique mailbox ID if server has `OBJECTID` extension enabled
  * @property {BigInt} [highestModseq] latest known modseq value if server has CONDSTORE or XYMHIGHESTMODSEQ enabled
- * @property {String} [noModseq] if true then the server doesn't support the persistent storage of mod-sequences for the mailbox
+ * @property {Boolean} [noModseq] if true then the server doesn't support the persistent storage of mod-sequences for the mailbox
  * @property {BigInt} uidValidity Mailbox `UIDVALIDITY` value
  * @property {Number} uidNext Next predicted UID
  * @property {Number} exists Messages in this folder
@@ -308,7 +308,7 @@ class ImapFlow extends EventEmitter {
         this.commandParts = [];
 
         /**
-         * Active IMAP capabilities. Value is either `true` for togglabe capabilities (eg. `UIDPLUS`)
+         * Active IMAP capabilities. Value is either `true` for toggleable capabilities (eg. `UIDPLUS`)
          * or a number for capabilities with a value (eg. `APPENDLIMIT`)
          * @type {Map<string, boolean|number>}
          */
@@ -372,10 +372,12 @@ class ImapFlow extends EventEmitter {
 
         this.disableBinary = !!this.options.disableBinary;
 
-        // Named error handler for proper cleanup
+        // Named error handler for proper cleanup. Certain error codes represent
+        // expected socket/network issues (buffer exhaustion, connection reset, broken pipe,
+        // timeout, unreachable host) that just need a silent connection close rather
+        // than emitting an error event to the caller.
         this._streamerErrorHandler = err => {
             if (['Z_BUF_ERROR', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'EHOSTUNREACH'].includes(err.code)) {
-                // just close the connection, usually nothing but noise
                 this.closeAfter();
                 return;
             }
@@ -430,6 +432,9 @@ class ImapFlow extends EventEmitter {
             return;
         }
 
+        // Append CRLF only to the final part of a command. When sending literals,
+        // commandParts holds the remaining parts (literal data, continuation); the CRLF
+        // delimiter is only added when no more parts remain (the command is complete).
         let addLineBreak = !this.commandParts.length;
         if (typeof chunk === 'string') {
             if (addLineBreak) {
@@ -460,6 +465,14 @@ class ImapFlow extends EventEmitter {
         this.writeSocket.write(chunk);
     }
 
+    /**
+     * Returns byte counters for the current connection.
+     *
+     * @param {Boolean} [reset] If `true` then resets the byte counters after returning the current values
+     * @returns {Object} Byte counters
+     * @returns {Number} return.sent Bytes sent to server
+     * @returns {Number} return.received Bytes received from server
+     */
     stats(reset) {
         let result = {
             sent: this.writeBytesCounter || 0,
@@ -476,6 +489,11 @@ class ImapFlow extends EventEmitter {
         return result;
     }
 
+    // Compiles and sends an IMAP command to the server. The command is compiled
+    // twice: once as an array (for sending, with literal data split into parts)
+    // and once as a string (for logging, with sensitive data masked).
+    // When LITERAL- or LITERAL+ extensions are available, the compiler can use
+    // non-synchronizing literals to avoid waiting for server "+" continuation.
     async send(data) {
         if (this.state === this.states.LOGOUT) {
             // already logged out
@@ -491,12 +509,17 @@ class ImapFlow extends EventEmitter {
             return;
         }
 
+        // Compile with asArray=true: splits output into parts for literal handling.
+        // First part is the command text up to the first literal, remaining parts
+        // are stored in this.commandParts and sent after server "+" continuations.
         let compiled = await compiler(data, {
             asArray: true,
             literalMinus: this.capabilities.has('LITERAL-') || this.capabilities.has('LITERAL+')
         });
         this.commandParts = compiled;
 
+        // Compile again for logging with isLogging=true: masks sensitive values
+        // like passwords while producing a human-readable command string
         let logCompiled = await compiler(data, {
             isLogging: true
         });
@@ -505,6 +528,9 @@ class ImapFlow extends EventEmitter {
 
         this.log.debug({ src: 'c', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
 
+        // Send the first part (command text). If there are literal parts,
+        // the server will respond with "+" continuations and reader() will
+        // send each remaining part from this.commandParts.
         this.write(this.commandParts.shift());
 
         if (typeof options.onSend === 'function') {
@@ -553,20 +579,29 @@ class ImapFlow extends EventEmitter {
         });
     }
 
+    // Resolves the handler for an untagged server response. IMAP untagged responses
+    // come in two forms:
+    //   * CAPABILITY ...       (keyword as command)
+    //   * 42 FETCH (...)       (numeric prefix + keyword)
+    // For numeric-prefixed responses, we extract the keyword (FETCH, EXISTS, EXPUNGE, etc.)
+    // and look up the handler by that keyword instead.
+    // Handler priority: command-specific handlers (registered per exec() call) take
+    // precedence over global handlers (registered on the connection).
     getUntaggedHandler(command, attributes) {
         if (/^[0-9]+$/.test(command)) {
             let type = attributes && attributes.length && typeof attributes[0].value === 'string' ? attributes[0].value.toUpperCase() : false;
             if (type) {
-                // EXISTS, EXPUNGE, RECENT, FETCH etc
                 command = type;
             }
         }
 
         command = command.toUpperCase().trim();
+        // Check command-specific handler first (registered in exec() options.untagged)
         if (this.currentRequest && this.currentRequest.options && this.currentRequest.options.untagged && this.currentRequest.options.untagged[command]) {
             return this.currentRequest.options.untagged[command];
         }
 
+        // Fall back to global handler (e.g., for CAPABILITY, BYE, etc.)
         if (this.untaggedHandlers[command]) {
             return this.untaggedHandlers[command];
         }
@@ -618,12 +653,16 @@ class ImapFlow extends EventEmitter {
                 this.log.debug({ src: 's', msg: logCompiled.toString(), cid: this.id, nullBytesRemoved: parsed.nullBytesRemoved });
             }
 
+            // IMAP "+" (continuation request) handling. The server sends "+" in two cases:
+            // 1. During IDLE or AUTHENTICATE, where a custom handler (onPlusTag) processes it
+            // 2. During literal data transfer, where we send the next queued literal chunk
             if (parsed.tag === '+' && this.currentRequest && this.currentRequest.options && typeof this.currentRequest.options.onPlusTag === 'function') {
                 await this.currentRequest.options.onPlusTag(parsed);
                 data.next();
                 continue;
             }
 
+            // Server acknowledged our literal size with "+", send the actual literal data
             if (parsed.tag === '+' && this.commandParts.length) {
                 let content = this.commandParts.shift();
                 this.write(content);
@@ -706,8 +745,9 @@ class ImapFlow extends EventEmitter {
 
                             let throttleDelay = false;
 
-                            // MS365 throttling
-                            // tag BAD Request is throttled. Suggested Backoff Time: 92415 milliseconds
+                            // MS365 throttling detection: Office 365 returns BAD with a human-readable
+                            // backoff time when rate limits are hit. Parse the delay from the response text.
+                            // Example: "tag BAD Request is throttled. Suggested Backoff Time: 92415 milliseconds"
                             if (/Request is throttled/i.test(txt) && /Backoff Time/i.test(txt)) {
                                 let throttlingMatch = txt.match(/Backoff Time[:=\s]+(\d+)/i);
                                 if (throttlingMatch && throttlingMatch[1] && !isNaN(throttlingMatch[1])) {
@@ -722,7 +762,8 @@ class ImapFlow extends EventEmitter {
 
                                 let delayResponse = throttleDelay;
                                 if (delayResponse > 5 * 60 * 1000) {
-                                    // max delay cap
+                                    // Cap wait at 5 minutes to avoid hanging connections indefinitely.
+                                    // The server-suggested delay can be very large.
                                     delayResponse = 5 * 60 * 1000;
                                 }
 
@@ -756,6 +797,10 @@ class ImapFlow extends EventEmitter {
     }
 
     setEventHandlers() {
+        // Bind the 'readable' event to kick off the reader loop.
+        // The `this.reading` flag acts as a concurrency guard: if reader()
+        // is already running, new 'readable' events are ignored. The reader
+        // loop will keep draining data until the stream returns null.
         this.socketReadable = () => {
             if (!this.reading) {
                 this.reading = true;
@@ -912,7 +957,12 @@ class ImapFlow extends EventEmitter {
             return; // was not able to negotiate compression
         }
 
-        // create deflate/inflate streams with rate limiting options
+        // Set up DEFLATE compression (RFC 4978). After COMPRESS is negotiated,
+        // all data in both directions is wrapped in a zlib DEFLATE stream.
+        // The incoming pipeline becomes: socket -> inflate -> streamer (parser).
+        // The outgoing pipeline uses a manual pump (see readNext below) instead
+        // of a normal pipe, because we need to flush after every IMAP command
+        // to ensure the server receives complete commands promptly.
         this._deflate = zlib.createDeflateRaw({
             windowBits: 15,
             level: zlib.constants.Z_DEFAULT_COMPRESSION, // Use default compression level (6)
@@ -924,7 +974,8 @@ class ImapFlow extends EventEmitter {
             chunkSize: 16 * 1024 // Process in 16KB chunks to prevent CPU blocking
         });
 
-        // route incoming socket via inflate stream
+        // Reroute incoming data through inflate: socket -> inflate -> streamer.
+        // The streamer's compress flag tells it to expect deflated framing.
         this.socket.unpipe(this.streamer);
         this.streamer.compress = true;
         this.socket.pipe(this._inflate).pipe(this.streamer);
@@ -932,7 +983,10 @@ class ImapFlow extends EventEmitter {
             this.streamer.emit('error', err);
         });
 
-        // route outgoing socket via deflate stream with rate limiting
+        // For outgoing data, replace the writeSocket with a PassThrough buffer.
+        // We can't pipe writeSocket -> deflate -> socket directly because we need
+        // to call deflate.flush() after each IMAP command to push all pending
+        // compressed bytes to the server immediately (IMAP is request-response).
         this.writeSocket = new PassThrough({
             highWaterMark: 64 * 1024 // 64KB buffer limit to prevent excessive memory usage
         });
@@ -953,8 +1007,9 @@ class ImapFlow extends EventEmitter {
             get: () => !this.socket || this.socket.destroyed
         });
 
-        // we need to force flush deflated data to socket so we can't
-        // use normal pipes for this.writeSocket -> this._deflate -> this.socket
+        // Manual pump loop: reads chunks from writeSocket, pushes them into
+        // deflate, and flushes when the buffer is drained. This ensures each
+        // IMAP command is fully compressed and flushed to the socket immediately.
         let reading = false;
         let processedChunks = 0;
         let readNext = async () => {
@@ -963,7 +1018,7 @@ class ImapFlow extends EventEmitter {
                 processedChunks = 0;
 
                 let chunk;
-                while ((chunk = this.writeSocket.read()) !== null) {
+                while (this.writeSocket && (chunk = this.writeSocket.read()) !== null) {
                     if (this._deflate && this._deflate.write(chunk) === false) {
                         return this._deflate.once('drain', readNext);
                     }
@@ -972,6 +1027,9 @@ class ImapFlow extends EventEmitter {
                     processedChunks++;
                     if (processedChunks % 100 === 0) {
                         await new Promise(resolve => setImmediate(resolve));
+                        if (!this.writeSocket) {
+                            break;
+                        }
                     }
                 }
 
@@ -987,17 +1045,21 @@ class ImapFlow extends EventEmitter {
         };
 
         this.writeSocket.on('readable', () => {
-            if (!reading) {
+            if (!reading && this.writeSocket) {
                 readNext();
             }
         });
         this.writeSocket.on('error', err => {
-            this.socket.emit('error', err);
+            if (this.socket) {
+                this.socket.emit('error', err);
+            }
         });
 
         this._deflate.pipe(this.socket);
         this._deflate.on('error', err => {
-            this.socket.emit('error', err);
+            if (this.socket) {
+                this.socket.emit('error', err);
+            }
         });
     }
 
@@ -1044,6 +1106,9 @@ class ImapFlow extends EventEmitter {
             return this._failSTARTTLS();
         }
 
+        // STARTTLS upgrade sequence: detach the plain socket from the parser,
+        // wrap it in a TLS socket, then reconnect the new TLS socket to the
+        // parser. The plain socket becomes the underlying transport for TLS.
         this.socket.unpipe(this.streamer);
         let upgraded = await new Promise((resolve, reject) => {
             let socketPlain = this.socket;
@@ -1092,6 +1157,8 @@ class ImapFlow extends EventEmitter {
                         return this.close();
                     }
 
+                    // TLS handshake complete. Reconnect the now-encrypted socket
+                    // to the IMAP parser stream and record the cipher details.
                     this.secureConnection = true;
                     this.upgrading = false;
                     this.streamer.secureConnection = true;
@@ -1432,12 +1499,16 @@ class ImapFlow extends EventEmitter {
         return true;
     }
 
+    // Normalizes a message range from various input formats into an IMAP-compatible
+    // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
+    // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
     async resolveRange(range, options) {
         if (typeof range === 'number' || typeof range === 'bigint') {
             range = range.toString();
         }
 
-        // special case, some servers allow this, some do not, so replace it with the last known EXISTS value
+        // Replace "*" with the actual message count. Some servers reject bare "*"
+        // in certain commands, and this also forces a sequence query (not UID).
         if (range === '*') {
             if (!this.mailbox.exists) {
                 return false;
@@ -1453,7 +1524,8 @@ class ImapFlow extends EventEmitter {
                 range = range.uid;
                 options.uid = true;
             } else {
-                // resolve range by searching
+                // Arbitrary search query object: run SEARCH to resolve it into
+                // a set of UIDs, then pack into a compact range string.
                 options.uid = true; // force UIDs instead of sequence numbers
                 range = await this.run('SEARCH', range, options);
                 if (range && range.length) {
@@ -1688,7 +1760,8 @@ class ImapFlow extends EventEmitter {
                 this.initialReject = false;
                 let err = new Error('Unexpected close');
                 err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
-                // still has to go through the logic below
+                // Reject via setImmediate so the rest of close() cleanup runs first.
+                // The caller's connect() promise will reject after sockets are torn down.
                 setImmediate(() => reject(err));
             }
 
@@ -1731,8 +1804,9 @@ class ImapFlow extends EventEmitter {
                 return error;
             };
 
-            // Reject pending requests via setImmediate to ensure caller's promise chain
-            // is fully set up before rejection (prevents unhandled promise rejections)
+            // Reject pending requests via setImmediate so this synchronous close()
+            // method finishes first. This prevents unhandled promise rejections that
+            // would occur if we rejected inline before callers set up .catch() handlers.
             if (pendingRequests.length) {
                 let byeReason = this.byeReason;
                 setImmediate(() => {
@@ -1809,6 +1883,11 @@ class ImapFlow extends EventEmitter {
                 return;
             }
 
+            // Socket teardown order matters when compression is active:
+            // writeSocket may be a PassThrough (compression) or the raw socket (no compression).
+            // Destroy the underlying socket first, then writeSocket (if different).
+            // The second socket.destroy() block handles the case where writeSocket.destroy()
+            // did not also destroy the underlying socket.
             if (this.socket && !this.socket.destroyed && this.writeSocket !== this.socket) {
                 try {
                     this.socket.destroy();
@@ -1834,7 +1913,8 @@ class ImapFlow extends EventEmitter {
                 }
             }
 
-            // Explicit nullification to help garbage collection
+            // Null out all socket and handler references so the GC can collect
+            // them even if the ImapFlow instance itself is still referenced.
             this.socket = null;
             this.writeSocket = null;
             this._inflate = null;
@@ -1870,11 +1950,11 @@ class ImapFlow extends EventEmitter {
      * Returns current quota
      *
      * @param {String} [path] Optional mailbox path if you want to check quota for specific folder
-     * @returns {Promise<QuotaResponse|Boolean>} Quota information or `false` if QUTOA extension is not supported or requested path does not exist
+     * @returns {Promise<QuotaResponse|Boolean>} Quota information or `false` if QUOTA extension is not supported or requested path does not exist
      *
      * @example
      * let quota = await client.getQuota();
-     * console.log(quota.storage.used, quota.storage.available)
+     * console.log(quota.storage.used, quota.storage.limit)
      */
     async getQuota(path) {
         path = path || 'INBOX';
@@ -1938,7 +2018,7 @@ class ImapFlow extends EventEmitter {
      * @property {String} path mailbox path
      * @property {String} name mailbox name (last part of path after delimiter)
      * @property {String} delimiter mailbox path delimiter, usually "." or "/"
-     * @property {String[]} flags list of flags for this mailbox
+     * @property {Set<string>} flags list of flags for this mailbox
      * @property {String} specialUse one of special-use flags (if applicable): "\All", "\Archive", "\Drafts", "\Flagged", "\Junk", "\Sent", "\Trash". Additionally INBOX has non-standard "\Inbox" flag set
      * @property {Boolean} listed `true` if mailbox was found from the output of LIST command
      * @property {Boolean} subscribed `true` if mailbox was found from the output of LSUB command
@@ -2206,7 +2286,7 @@ class ImapFlow extends EventEmitter {
      * Sets flags for a message or message range
      *
      * @param {SequenceString | Number[] | SearchObject} range Range to filter the messages
-     * @param {string[]} Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param {string[]} flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @param {BigInt} [options.unchangedSince] If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
@@ -2240,7 +2320,7 @@ class ImapFlow extends EventEmitter {
      * Adds flags for a message or message range
      *
      * @param {SequenceString | Number[] | SearchObject} range Range to filter the messages
-     * @param {string[]} Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param {string[]} flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @param {BigInt} [options.unchangedSince] If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
@@ -2274,7 +2354,7 @@ class ImapFlow extends EventEmitter {
      * Remove specific flags from a message or message range
      *
      * @param {SequenceString | Number[] | SearchObject} range Range to filter the messages
-     * @param {string[]} Array of flags to remove. Only flags that are permitted to set are used, other flags are ignored
+     * @param {string[]} flags Array of flags to remove. Only flags that are permitted to set are used, other flags are ignored
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @param {BigInt} [options.unchangedSince] If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
@@ -2308,7 +2388,7 @@ class ImapFlow extends EventEmitter {
      * Sets a colored flag for an email. Only supported by mail clients like Apple Mail
      *
      * @param {SequenceString | Number[] | SearchObject} range Range to filter the messages
-     * @param {string} The color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey'
+     * @param {string} color The color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey'
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @param {BigInt} [options.unchangedSince] If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
@@ -2525,10 +2605,13 @@ class ImapFlow extends EventEmitter {
      * @property {boolean | Object} [source] if `true` then include full message in the response
      * @property {Number} [source.start] include full message in the response starting from *start* byte
      * @property {Number} [source.maxLength] include full message in the response, up to *maxLength* bytes
-     * @property {String} [threadId] if `true` then include thread ID in the response (only if server supports either `OBJECTID` or `X-GM-EXT-1` extensions)
+     * @property {Boolean} [threadId] if `true` then include thread ID in the response (only if server supports either `OBJECTID` or `X-GM-EXT-1` extensions)
      * @property {Boolean} [labels] if `true` then include GMail labels in the response (only if server supports `X-GM-EXT-1` extension)
      * @property {boolean | string[]} [headers] if `true` then includes full headers of the message in the response. If the value is an array of header keys then includes only headers listed in the array
      * @property {string[]} [bodyParts] An array of BODYPART identifiers to include in the response
+     * @property {Boolean} [fast] IMAP macro equivalent to `flags`, `internalDate`, `size`
+     * @property {Boolean} [all] IMAP macro equivalent to `flags`, `internalDate`, `size`, `envelope`
+     * @property {Boolean} [full] IMAP macro equivalent to `flags`, `internalDate`, `size`, `envelope`, `bodyStructure`
      */
 
     /**
@@ -2584,7 +2667,7 @@ class ImapFlow extends EventEmitter {
      * @property {Buffer} [source] message source for the requested byte range
      * @property {BigInt} [modseq] message Modseq number. Always included if the server supports CONDSTORE extension
      * @property {String} [emailId] unique email ID. Always included if server supports `OBJECTID` or `X-GM-EXT-1` extensions
-     * @property {String} [threadid] unique thread ID. Only present if server supports `OBJECTID` or `X-GM-EXT-1` extension
+     * @property {String} [threadId] unique thread ID. Only present if server supports `OBJECTID` or `X-GM-EXT-1` extension
      * @property {Set<string>} [labels] a Set of labels. Only present if server supports `X-GM-EXT-1` extension
      * @property {Number} [size] message size
      * @property {Set<string>} [flags] a set of message flags
@@ -2629,6 +2712,11 @@ class ImapFlow extends EventEmitter {
             return false;
         }
 
+        // Push/pull coordination for the async generator pattern:
+        // The FETCH command handler pushes results into rowQueue via onUntaggedFetch.
+        // The generator consumer pulls via getNext(). The `push` callback bridges the
+        // two: when the consumer is waiting and the queue is empty, `push` is set to
+        // a function that wakes up the consumer when new data arrives.
         let finished = false;
         let push = false;
         let rowQueue = [];
@@ -2649,7 +2737,7 @@ class ImapFlow extends EventEmitter {
                         return resolve(null);
                     }
 
-                    // wait until data is pushed to queue and try again
+                    // No data available yet; register a wakeup callback
                     push = () => {
                         push = false;
                         check();
@@ -2658,6 +2746,10 @@ class ImapFlow extends EventEmitter {
                 check();
             });
 
+        // Fire-and-forget the FETCH command. It runs in the background while
+        // the generator yields results. Each untagged FETCH response is paired
+        // with a `next` callback that acts as backpressure: the FETCH handler
+        // won't process the next response until the consumer calls next().
         this.run('FETCH', range, query, {
             uid: !!options.uid,
             binary: options.binary,
@@ -2697,6 +2789,7 @@ class ImapFlow extends EventEmitter {
 
             if (res !== null) {
                 yield res.response;
+                // Signal the FETCH handler to process the next untagged response
                 res.next();
             }
         }
@@ -2833,8 +2926,9 @@ class ImapFlow extends EventEmitter {
         let uid = false;
 
         if (part === '1') {
-            // First part has special conditions for single node emails as
-            // the mime parts for root node are not 1 and 1.MIME but TEXT and HEADERS
+            // Special handling for part "1": in single-node emails (no childNodes),
+            // the body is accessed via "TEXT" rather than "1", and headers via
+            // "HEADER" instead of "1.MIME". Check bodyStructure to detect this.
             let response = await this.fetchOne(range, { uid: true, bodyStructure: true }, options);
 
             if (!response) {
@@ -2994,6 +3088,13 @@ class ImapFlow extends EventEmitter {
         let output;
         let fetchAborted = false;
 
+        // Build a decoder pipeline that progressively transforms the raw FETCH data:
+        //   1. Transfer-encoding decoder (base64 or quoted-printable -> binary)
+        //   2. Format decoder (format=flowed -> plain text, if applicable)
+        //   3. Charset decoder (non-UTF-8 -> UTF-8, for text parts only)
+        //   4. Byte limiter (enforces maxBytes cap)
+        // `stream` is the head of the pipeline (where raw chunks are written),
+        // `output` is the tail (what the caller reads from).
         switch (meta.encoding) {
             case 'base64':
                 output = stream = new libbase64.Decoder();
@@ -3007,7 +3108,7 @@ class ImapFlow extends EventEmitter {
 
         let isTextNode = ['text/html', 'text/plain', 'text/x-amp-html'].includes(meta.contentType) || (part === '1' && !meta.contentType);
         if ((!meta.disposition || meta.disposition === 'inline') && isTextNode) {
-            // flowed text
+            // RFC 3676 format=flowed text: unwrap soft line breaks
             if (meta.flowed) {
                 let flowDecoder = new FlowedDecoder({
                     delSp: meta.delSp
@@ -3018,7 +3119,8 @@ class ImapFlow extends EventEmitter {
                 output = output.pipe(flowDecoder);
             }
 
-            // not utf-8 text
+            // Convert non-UTF-8 charsets to UTF-8 via a streaming decoder.
+            // ASCII and UTF-8 need no conversion. Unknown charsets are left as-is.
             if (meta.charset && !['ascii', 'usascii', 'utf8'].includes(meta.charset.toLowerCase().replace(/[^a-z0-9]+/g, ''))) {
                 try {
                     let decoder = getDecoder(meta.charset);
@@ -3059,6 +3161,9 @@ class ImapFlow extends EventEmitter {
             return stream.write(chunk);
         };
 
+        // Fetch remaining chunks in a loop, writing each to the decoder stream.
+        // Stops when the server returns a short chunk (< chunkSize), the byte
+        // limiter is satisfied, or the consumer destroys the output stream.
         let fetchAllParts = async () => {
             while (hasMore && !limiter.limited && !fetchAborted) {
                 let { chunk } = await getNextPart();
@@ -3108,6 +3213,11 @@ class ImapFlow extends EventEmitter {
             }
         };
 
+        // Kick off the download pipeline asynchronously. The first chunk was
+        // already fetched above (to get metadata); write it to the decoder
+        // stream and then fetch remaining chunks via fetchAllParts().
+        // setImmediate ensures the caller gets the {meta, content} return
+        // value before streaming begins.
         setImmediate(() => {
             let writeResult;
             try {
@@ -3180,7 +3290,7 @@ class ImapFlow extends EventEmitter {
      * Fetch multiple attachments as Buffer values
      *
      * @param {SequenceString} range UID or sequence number for the message to fetch
-     * @param {String} parts A list of bodystructure parts
+     * @param {String[]} parts A list of bodystructure parts
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID number instead of sequence number for `range`
      * @returns {Promise<Object>} Download data object
@@ -3337,11 +3447,14 @@ class ImapFlow extends EventEmitter {
         return result;
     }
 
+    // Mailbox lock queue processor. Implements a mutex pattern: only one lock
+    // is active at a time. When the active lock is released, the next queued
+    // lock is processed. The `processingLock` flag prevents concurrent runs
+    // of this method (which could happen via setImmediate re-entry from release()).
     async processLocks() {
-        // Atomic test-and-set to prevent race condition
         const wasProcessing = this.processingLock;
         if (wasProcessing) {
-            // Another processor is already running, just exit
+            // Another processor is already running; it will pick up new locks
             this.log.trace({
                 msg: 'Mailbox locking queued',
                 path: this.mailbox && this.mailbox.path,
@@ -3405,7 +3518,7 @@ class ImapFlow extends EventEmitter {
                 }
 
                 if (this.mailbox && this.mailbox.path === path && !!this.mailbox.readOnly === !!options.readOnly) {
-                    // nothing to do here, already selected
+                    // Fast path: mailbox is already selected with the right access mode
                     this.log.trace({
                         msg: 'Mailbox lock acquired [existing]',
                         path,
@@ -3415,10 +3528,10 @@ class ImapFlow extends EventEmitter {
                     });
                     this.currentLock = lock;
                     resolve({ path, release });
-                    break; // Wait for this lock to be released
+                    break; // Stop processing; next lock waits for release()
                 } else {
                     try {
-                        // Try to open. Throws if mailbox does not exists or can't open
+                        // Need to SELECT/EXAMINE a different mailbox
                         await this.mailboxOpen(path, options);
                         this.log.trace({
                             msg: 'Mailbox lock acquired [selected]',
@@ -3432,6 +3545,9 @@ class ImapFlow extends EventEmitter {
                         break; // Wait for this lock to be released
                     } catch (err) {
                         if (err.responseStatus === 'NO') {
+                            // SELECT failed with NO -- verify whether the mailbox exists
+                            // at all by running LIST. This sets mailboxMissing on the error
+                            // so the caller can distinguish "doesn't exist" from other failures.
                             try {
                                 let folders = await this.run('LIST', '', path, { listOnly: true });
                                 if (!folders || !folders.length) {
@@ -3458,9 +3574,10 @@ class ImapFlow extends EventEmitter {
         } finally {
             this.processingLock = false;
 
-            // Check if new locks were added while we were processing
+            // New locks may have been queued while we were processing (e.g.,
+            // a lock that failed immediately and the next getMailboxLock call
+            // arrived before we finished). Schedule another run if needed.
             if (this.locks.length && !this.currentLock) {
-                // Process any remaining locks
                 setImmediate(() => {
                     this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
                 });
@@ -3561,6 +3678,14 @@ class ImapFlow extends EventEmitter {
         return synteticLogger;
     }
 
+    /**
+     * Detaches sockets from the IMAP pipeline. Useful for upgrading the connection
+     * (e.g., STARTTLS) or transferring socket ownership.
+     *
+     * @returns {Object} Socket objects
+     * @returns {Object} return.readSocket The read socket (inflated socket if compression is enabled, raw socket otherwise)
+     * @returns {Object} return.writeSocket The write socket
+     */
     unbind() {
         this.socket.unpipe(this.streamer);
         if (this._inflate) {
@@ -3620,6 +3745,9 @@ class ImapFlow extends EventEmitter {
  * @type {Object}
  * @property {String} path mailbox path this event applies to
  * @property {Number} seq sequence number of deleted message
+ * @property {Boolean} vanished `true` if message was expunged via VANISHED response
+ * @property {Number} [uid] UID of expunged message (when `vanished` is `true`)
+ * @property {Boolean} [earlier] `true` for VANISHED EARLIER responses
  * @example
  * client.on('expunge', data=>{
  *     console.log(`Message #${data.seq} was deleted from "${data.path}"`);
@@ -3636,6 +3764,7 @@ class ImapFlow extends EventEmitter {
  * @property {Number} [uid] UID number of updated message (if server provided this value)
  * @property {BigInt} [modseq] Updated modseq number for the mailbox (if server provided this value)
  * @property {Set<string>} flags A set of all flags for the updated message
+ * @property {String} [flagColor] flag color like "red", or "yellow". Derived from the `flags` Set using Apple Mail color rules
  * @example
  * client.on('flags', data=>{
  *     console.log(`Flag set for #${data.seq} is now "${Array.from(data.flags).join(', ')}"`);
@@ -3671,7 +3800,7 @@ class ImapFlow extends EventEmitter {
  * @type {Object}
  * @example
  * client.on('log', entry => {
- *     console.log(`${log.cid} ${log.msg}`);
+ *     console.log(`${entry.cid} ${entry.msg}`);
  * });
  */