imapflow 1.2.8 → 1.2.10

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

package/lib/handler/imap-compiler.js

@@ -4,6 +4,13 @@
 
 const imapFormalSyntax = require('./imap-formal-syntax');
 
+/**
+ * Formats a response entry into a Buffer.
+ *
+ * @param {string|number|Buffer} entry - The value to convert to a Buffer.
+ * @param {boolean} [returnEmpty] - If true, returns null instead of an empty Buffer when the entry is not a recognized type.
+ * @returns {Buffer|null} The entry as a Buffer, or null if returnEmpty is true and the entry is not a recognized type.
+ */
 const formatRespEntry = (entry, returnEmpty) => {
     if (typeof entry === 'string') {
         return Buffer.from(entry);
@@ -25,7 +32,19 @@ const formatRespEntry = (entry, returnEmpty) => {
 };
 
 /**
- * Compiles an input object into
+ * Compiles an input object into a sequence of Buffers representing an IMAP protocol response string.
+ * Handles various node types including literals, strings, atoms, sections, sequences, and nested lists.
+ *
+ * @param {Object} response - The response object to compile.
+ * @param {string} [response.tag] - The IMAP command tag (e.g., "*" or a sequence number).
+ * @param {string} [response.command] - The IMAP command name.
+ * @param {Array|Object} [response.attributes] - The response attributes to compile into IMAP format.
+ * @param {Object} [options] - Compilation options.
+ * @param {boolean} [options.asArray] - If true, returns an array of Buffers (one per literal segment); otherwise returns a single concatenated Buffer.
+ * @param {boolean} [options.isLogging] - If true, redacts sensitive values and truncates long strings/literals for logging purposes.
+ * @param {boolean} [options.literalPlus] - If true, uses the LITERAL+ extension (appends "+" to literal length markers).
+ * @param {boolean} [options.literalMinus] - If true, uses the LITERAL- extension for literals up to 4096 bytes.
+ * @returns {Promise<Buffer[]|Buffer>} A promise that resolves to an array of Buffers (if asArray is true) or a single concatenated Buffer.
  */
 module.exports = async (response, options) => {
     let { asArray, isLogging, literalPlus, literalMinus } = options || {};
@@ -38,15 +57,22 @@ module.exports = async (response, options) => {
     let walk = async (node, options) => {
         options = options || {};
 
+        // Determine whether a space separator is needed before this node.
+        // Inspect the last byte written to decide context.
         let lastRespEntry = resp.length && resp[resp.length - 1];
         let lastRespByte = (lastRespEntry && lastRespEntry.length && lastRespEntry[lastRespEntry.length - 1]) || '';
         if (typeof lastRespByte === 'number') {
             lastRespByte = String.fromCharCode(lastRespByte);
         }
 
+        // Add a space separator unless:
+        // - The previous token was a LITERAL (literal data is self-delimiting after CRLF)
+        // - The last byte was '(', '<', or '[' (opening delimiters suppress the space)
+        // - This is the first token (resp is empty)
+        // - This is a sub-array element in a consecutive-list context (no space between adjacent lists)
         if (lastType === 'LITERAL' || (!['(', '<', '['].includes(lastRespByte) && resp.length)) {
             if (options.subArray) {
-                // ignore separator
+                // ignore separator between consecutive sub-arrays in a list
             } else {
                 resp.push(formatRespEntry(' '));
             }
@@ -108,16 +134,26 @@ module.exports = async (response, options) => {
                 } else {
                     let literalLength = !node.value ? 0 : Math.max(node.value.length, 0);
 
+                    // canAppend: whether the literal data can be sent in the same buffer segment.
+                    // With LITERAL+ (RFC 7888) the client does not wait for a continuation response.
+                    // With LITERAL- (RFC 7888) the client can skip the wait only for literals <= 4096 bytes.
+                    // When asArray is false we always append inline (single-buffer mode).
                     let canAppend = !asArray || literalPlus || (literalMinus && literalLength <= 4096);
+                    // Append '+' to the size marker when using LITERAL+ or LITERAL- (non-synchronizing)
                     let usePlus = canAppend && (literalMinus || literalPlus);
 
+                    // Emit the literal header: optional '~' prefix for literal8, then {size[+]}\r\n
                     resp.push(formatRespEntry(`${node.isLiteral8 ? '~' : ''}{${literalLength}${usePlus ? '+' : ''}}\r\n`));
 
                     if (canAppend) {
+                        // Literal data follows immediately in the same buffer segment
                         if (node.value && node.value.length) {
                             resp.push(formatRespEntry(node.value));
                         }
                     } else {
+                        // For synchronizing literals in asArray mode, split output into separate
+                        // parts. The caller must send each part and wait for a continuation
+                        // response from the server before sending the next.
                         respParts.push(resp);
                         resp = [].concat(formatRespEntry(node.value, true) || []);
                     }
@@ -148,6 +184,9 @@ module.exports = async (response, options) => {
                 val = (node.value || '').toString();
 
                 if (!node.section || val) {
+                    // Verify the value contains only valid ATOM-CHAR characters.
+                    // Strip a leading backslash before checking (system flags like \Seen start with '\').
+                    // If any character fails verification, quote-escape the entire value with JSON.stringify.
                     if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
                         val = JSON.stringify(val);
                     }
@@ -155,6 +194,8 @@ module.exports = async (response, options) => {
                     resp.push(formatRespEntry(val));
                 }
 
+                // Section bracket handling: emit [section-contents] after the ATOM value
+                // e.g., BODY[HEADER.FIELDS (Subject)] or BODY[1.MIME]
                 if (node.section) {
                     resp.push(formatRespEntry('['));
 
@@ -164,6 +205,7 @@ module.exports = async (response, options) => {
 
                     resp.push(formatRespEntry(']'));
                 }
+                // Partial range: emit <origin.length> after the section brackets
                 if (node.partial) {
                     resp.push(formatRespEntry(`<${node.partial.join('.')}>`));
                 }

package/lib/handler/imap-formal-syntax.js

@@ -2,9 +2,27 @@
 
 'use strict';
 
-// IMAP Formal Syntax
-// http://tools.ietf.org/html/rfc3501#section-9
-
+/**
+ * @module imap-formal-syntax
+ *
+ * Defines the IMAP formal syntax character classes and validation rules as specified
+ * in RFC 3501 Section 9 (http://tools.ietf.org/html/rfc3501#section-9).
+ *
+ * Each exported method returns a string of allowed characters for a given IMAP grammar
+ * production rule (e.g., ATOM-CHAR, ASTRING-CHAR, TEXT-CHAR). Results are memoized after
+ * the first call by replacing the method with a function that returns the cached value.
+ *
+ * Also exports a {@link module:imap-formal-syntax.verify|verify} function for validating
+ * strings against a set of allowed characters.
+ */
+
+/**
+ * Generates a string containing all characters in the given Unicode code point range (inclusive).
+ *
+ * @param {number} start - The starting character code point.
+ * @param {number} end - The ending character code point.
+ * @returns {string} A string containing all characters from start to end.
+ */
 function expandRange(start, end) {
     let chars = [];
     for (let i = start; i <= end; i++) {
@@ -13,6 +31,13 @@ function expandRange(start, end) {
     return String.fromCharCode(...chars);
 }
 
+/**
+ * Returns a new string with all characters from the exclude string removed from the source string.
+ *
+ * @param {string} source - The source string to filter.
+ * @param {string} exclude - A string of characters to exclude from the source.
+ * @returns {string} The source string with excluded characters removed.
+ */
 function excludeChars(source, exclude) {
     let sourceArr = Array.prototype.slice.call(source);
     for (let i = sourceArr.length - 1; i >= 0; i--) {
@@ -24,6 +49,7 @@ function excludeChars(source, exclude) {
 }
 
 module.exports = {
+    /** @returns {string} All 7-bit US-ASCII characters excluding NUL (0x01-0x7F). */
     CHAR() {
         let value = expandRange(0x01, 0x7f);
         this.CHAR = function () {
@@ -32,6 +58,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} All 8-bit characters excluding NUL (0x01-0xFF). */
     CHAR8() {
         let value = expandRange(0x01, 0xff);
         this.CHAR8 = function () {
@@ -40,10 +67,12 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} The space character (0x20). */
     SP() {
         return ' ';
     },
 
+    /** @returns {string} All control characters (0x00-0x1F and 0x7F). */
     CTL() {
         let value = expandRange(0x00, 0x1f) + '\x7F';
         this.CTL = function () {
@@ -52,10 +81,12 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} The double-quote character. */
     DQUOTE() {
         return '"';
     },
 
+    /** @returns {string} All uppercase and lowercase ASCII alphabetic characters (A-Z, a-z). */
     ALPHA() {
         let value = expandRange(0x41, 0x5a) + expandRange(0x61, 0x7a);
         this.ALPHA = function () {
@@ -64,6 +95,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} All ASCII digit characters (0-9). */
     DIGIT() {
         let value = expandRange(0x30, 0x39);
         this.DIGIT = function () {
@@ -72,6 +104,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} Characters allowed in an IMAP ATOM (CHAR minus atom-specials). */
     'ATOM-CHAR'() {
         let value = excludeChars(this.CHAR(), this['atom-specials']());
         this['ATOM-CHAR'] = function () {
@@ -80,6 +113,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} Characters allowed in an IMAP ASTRING (ATOM-CHAR plus resp-specials). */
     'ASTRING-CHAR'() {
         let value = this['ATOM-CHAR']() + this['resp-specials']();
         this['ASTRING-CHAR'] = function () {
@@ -88,6 +122,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} Characters allowed in IMAP text (CHAR minus CR and LF). */
     'TEXT-CHAR'() {
         let value = excludeChars(this.CHAR(), '\r\n');
         this['TEXT-CHAR'] = function () {
@@ -96,6 +131,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} Characters that are special in ATOMs and must be excluded: "(", ")", "{", SP, CTL, list-wildcards, quoted-specials, resp-specials. */
     'atom-specials'() {
         let value = '(' + ')' + '{' + this.SP() + this.CTL() + this['list-wildcards']() + this['quoted-specials']() + this['resp-specials']();
         this['atom-specials'] = function () {
@@ -104,10 +140,12 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} The LIST wildcard characters ("%" and "*"). */
     'list-wildcards'() {
         return '%' + '*';
     },
 
+    /** @returns {string} Characters that are special inside quoted strings (DQUOTE and backslash). */
     'quoted-specials'() {
         let value = this.DQUOTE() + '\\';
         this['quoted-specials'] = function () {
@@ -116,10 +154,12 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} The response-special character ("]"). */
     'resp-specials'() {
         return ']';
     },
 
+    /** @returns {string} Characters allowed in an IMAP tag (ASTRING-CHAR minus "+"). */
     tag() {
         let value = excludeChars(this['ASTRING-CHAR'](), '+');
         this.tag = function () {
@@ -128,6 +168,7 @@ module.exports = {
         return value;
     },
 
+    /** @returns {string} Characters allowed in an IMAP command name (ALPHA, DIGIT, and hyphen). */
     command() {
         let value = this.ALPHA() + this.DIGIT() + '-';
         this.command = function () {
@@ -136,6 +177,13 @@ module.exports = {
         return value;
     },
 
+    /**
+     * Verifies that every character in the given string is within the set of allowed characters.
+     *
+     * @param {string} str - The string to validate.
+     * @param {string} allowedChars - A string containing all allowed characters.
+     * @returns {number} The index of the first disallowed character, or -1 if all characters are valid.
+     */
     verify(str, allowedChars) {
         for (let i = 0, len = str.length; i < len; i++) {
             if (allowedChars.indexOf(str.charAt(i)) < 0) {

package/lib/handler/imap-handler.js

@@ -3,6 +3,14 @@
 const parser = require('./imap-parser');
 const compiler = require('./imap-compiler');
 
+/**
+ * Re-exports the IMAP protocol parser and compiler as a single module.
+ *
+ * @property {Function} parser - Parses raw IMAP command/response buffers into structured objects.
+ *   See {@link module:imap-parser} for details.
+ * @property {Function} compiler - Compiles structured response objects into IMAP protocol Buffers.
+ *   See {@link module:imap-compiler} for details.
+ */
 module.exports = {
     parser,
     compiler

package/lib/handler/imap-parser.js

@@ -3,12 +3,29 @@
 const imapFormalSyntax = require('./imap-formal-syntax');
 const { ParserInstance } = require('./parser-instance');
 
+/**
+ * Parses a raw IMAP command or response buffer into a structured object.
+ * Handles edge cases such as null-byte-padded responses from buggy servers and
+ * multi-word commands like UID and AUTHENTICATE.
+ *
+ * @param {Buffer|string} command - The raw IMAP command or response data to parse.
+ * @param {Object} [options] - Parser options passed through to the underlying ParserInstance and TokenParser.
+ * @param {boolean} [options.literalPlus] - Whether the LITERAL+ extension is in use.
+ * @param {Array<Buffer>} [options.literals] - Pre-parsed literal values extracted from the input stream.
+ * @returns {Promise<Object>} A promise that resolves to a parsed response object.
+ * @returns {string} return.tag - The IMAP tag (e.g., "*", "+", or a command tag like "A1").
+ * @returns {string} return.command - The IMAP command or response name (e.g., "OK", "FETCH").
+ * @returns {Array} [return.attributes] - Parsed attributes of the response.
+ * @returns {number} [return.nullBytesRemoved] - Number of leading null bytes removed, if any.
+ */
 module.exports = async (command, options) => {
     options = options || {};
 
     let nullBytesRemoved = 0;
 
-    // special case with a buggy IMAP server where responses are padded with zero bytes
+    // Workaround for buggy IMAP servers that pad responses with leading NUL (\x00) bytes.
+    // Some servers (observed in the wild) prepend null bytes to their output, which would
+    // cause parsing to fail. We strip them and note how many were removed for diagnostics.
     if (command[0] === 0) {
         // find the first non null byte and trim
         let firstNonNull = -1;
@@ -19,7 +36,7 @@ module.exports = async (command, options) => {
             }
         }
         if (firstNonNull === -1) {
-            // All bytes are null
+            // All bytes are null -- treat as a BAD response
             return { tag: '*', command: 'BAD', attributes: [] };
         }
         command = command.slice(firstNonNull);
@@ -40,6 +57,10 @@ module.exports = async (command, options) => {
             response.nullBytesRemoved = nullBytesRemoved;
         }
 
+        // Some IMAP commands are multi-word: "UID FETCH", "UID STORE", "UID COPY",
+        // "UID MOVE", "UID SEARCH", "UID EXPUNGE", and "AUTHENTICATE PLAIN", etc.
+        // For these, the first word is consumed as the command, then we read the
+        // subcommand and concatenate them (e.g., "UID" + " " + "FETCH" -> "UID FETCH").
         if (['UID', 'AUTHENTICATE'].indexOf((response.command || '').toUpperCase()) >= 0) {
             await parser.getSpace();
             response.command += ' ' + (await parser.getElement(imapFormalSyntax.command()));