imapflow 1.2.7 → 1.2.9

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()));

package/lib/handler/imap-stream.js

@@ -16,7 +16,25 @@ const CURLY_CLOSE = 0x7d;
 // Maximum allowed literal size: 1GB (1073741824 bytes)
 const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 
+/**
+ * A Transform stream that parses raw IMAP protocol data from a socket into structured
+ * command/response objects. Reads binary input, splits it into lines delimited by LF,
+ * extracts literal data blocks based on IMAP literal size markers (e.g., "{123}\r\n"),
+ * and emits each complete command as a readable object containing the payload Buffer
+ * and any associated literal Buffers. Enforces a maximum literal size of 1GB.
+ *
+ * @extends Transform
+ */
 class ImapStream extends Transform {
+    /**
+     * Creates a new ImapStream instance.
+     *
+     * @param {Object} [options] - Stream options.
+     * @param {string} [options.cid] - Connection identifier used for logging.
+     * @param {Object} [options.logger] - A pino-compatible logger instance. If not provided, a default child logger is created.
+     * @param {boolean} [options.logRaw] - If true, logs raw socket data at trace level.
+     * @param {boolean} [options.secureConnection] - Whether the connection uses TLS.
+     */
     constructor(options) {
         super({
             //writableHighWaterMark: 3,
@@ -51,6 +69,15 @@ class ImapStream extends Transform {
         this.inputQueue = []; // unprocessed input chunks
     }
 
+    /**
+     * Checks whether the given line buffer ends with an IMAP literal size marker
+     * (e.g., "{123}\r\n"). If a valid marker is found and the literal size is within
+     * the allowed maximum, switches the stream state to LITERAL mode and records
+     * the expected number of literal bytes.
+     *
+     * @param {Buffer} line - The line buffer to check for a trailing literal marker.
+     * @returns {boolean} True if a valid literal marker was found and literal state was activated, false otherwise.
+     */
     checkLiteralMarker(line) {
         if (!line || !line.length) {
             return false;
@@ -58,23 +85,22 @@ class ImapStream extends Transform {
 
         let pos = line.length - 1;
 
-        if (line[pos] === LF) {
-            pos--;
-        } else {
+        if (line[pos] !== LF) {
             return false;
         }
+        pos--;
+
         if (pos >= 0 && line[pos] === CR) {
             pos--;
         }
-        if (pos < 0) {
-            return false;
-        }
 
-        if (!pos || line[pos] !== CURLY_CLOSE) {
+        if (pos < 0 || !pos || line[pos] !== CURLY_CLOSE) {
             return false;
         }
         pos--;
 
+        // Scan backwards through the line to find an IMAP literal marker: {size}\r\n
+        // The format is: '{' followed by one or more ASCII digits followed by '}'
         let numBytes = [];
         for (; pos > 0; pos--) {
             let c = line[pos];
@@ -103,6 +129,16 @@ class ImapStream extends Transform {
         return false;
     }
 
+    /**
+     * Processes a single input chunk of raw data. In LINE state, scans for LF-terminated
+     * lines and checks for literal markers. In LITERAL state, collects the expected number
+     * of literal bytes. When a complete command (with all its literals) is assembled, it is
+     * pushed downstream as a readable object.
+     *
+     * @param {Buffer} chunk - The raw data chunk to process.
+     * @param {number} [startPos=0] - The byte offset within the chunk to start processing from.
+     * @returns {Promise<void>}
+     */
     async processInputChunk(chunk, startPos) {
         startPos = startPos || 0;
         if (startPos >= chunk.length) {
@@ -164,41 +200,34 @@ class ImapStream extends Transform {
             }
 
             case LITERAL: {
-                // exactly until end of chunk
-                if (chunk.length === startPos + this.literalWaiting) {
-                    if (!startPos) {
-                        this.literalBuffer.push(chunk);
-                    } else {
-                        this.literalBuffer.push(chunk.slice(startPos));
-                    }
+                const remainingInChunk = chunk.length - startPos;
+                const bytesToRead = Math.min(remainingInChunk, this.literalWaiting);
+                const partial = startPos === 0 && bytesToRead === chunk.length ? chunk : chunk.slice(startPos, startPos + bytesToRead);
 
-                    this.literalWaiting -= chunk.length;
-                    this.literals.push(Buffer.concat(this.literalBuffer));
-                    this.literalBuffer = [];
-                    this.state = LINE;
+                this.literalBuffer.push(partial);
+                this.literalWaiting -= bytesToRead;
 
-                    return;
-                } else if (chunk.length > startPos + this.literalWaiting) {
-                    let partial = chunk.slice(startPos, startPos + this.literalWaiting);
-                    this.literalBuffer.push(partial);
-                    startPos += partial.length;
-                    this.literalWaiting -= partial.length;
+                if (this.literalWaiting === 0) {
                     this.literals.push(Buffer.concat(this.literalBuffer));
                     this.literalBuffer = [];
                     this.state = LINE;
 
-                    return await this.processInputChunk(chunk, startPos);
-                } else {
-                    let partial = chunk.slice(startPos);
-                    this.literalBuffer.push(partial);
-                    startPos += partial.length;
-                    this.literalWaiting -= partial.length;
-                    return;
+                    if (remainingInChunk > bytesToRead) {
+                        return await this.processInputChunk(chunk, startPos + bytesToRead);
+                    }
                 }
+                break;
             }
         }
     }
 
+    /**
+     * Drains the input queue by processing each queued chunk sequentially.
+     * Yields to the event loop every 10 chunks to prevent CPU blocking on
+     * large bursts of incoming data.
+     *
+     * @returns {Promise<void>}
+     */
     async processInput() {
         let data;
         let processedCount = 0;
@@ -215,6 +244,15 @@ class ImapStream extends Transform {
         }
     }
 
+    /**
+     * Transform stream implementation. Receives raw data chunks from the writable side,
+     * converts strings to Buffers, tracks total bytes read, optionally logs raw data,
+     * and queues the chunk for asynchronous processing.
+     *
+     * @param {Buffer|string} chunk - The incoming data chunk.
+     * @param {string} encoding - The encoding if chunk is a string.
+     * @param {Function} next - Callback to signal that this chunk has been consumed.
+     */
     _transform(chunk, encoding, next) {
         if (typeof chunk === 'string') {
             chunk = Buffer.from(chunk, encoding);
@@ -237,6 +275,9 @@ class ImapStream extends Transform {
             });
         }
 
+        // Queue the chunk for async processing. The 'next' callback serves as
+        // backpressure: it is called only after this chunk is fully processed,
+        // which signals the writable side that more data can be accepted.
         if (chunk && chunk.length) {
             this.inputQueue.push({ chunk, next });
         }
@@ -249,10 +290,22 @@ class ImapStream extends Transform {
         }
     }
 
+    /**
+     * Flush implementation called when the writable side ends. Signals completion immediately.
+     *
+     * @param {Function} next - Callback to signal flush completion.
+     */
     _flush(next) {
         next();
     }
 
+    /**
+     * Destroy implementation for cleanup. Clears all internal buffers, drains the input queue
+     * by invoking pending callbacks, and forwards the error (if any) to the callback.
+     *
+     * @param {Error|null} err - The error that caused destruction, or null.
+     * @param {Function} callback - Callback to signal destruction completion.
+     */
     _destroy(err, callback) {
         this.inputBuffer = [];
         this.lineBuffer = [];

package/lib/handler/parser-instance.js

@@ -6,7 +6,20 @@ const imapFormalSyntax = require('./imap-formal-syntax');
 
 const { TokenParser } = require('./token-parser');
 
+/**
+ * Parses a single IMAP response line into its structural components: tag, command,
+ * and attributes. Handles status responses (OK, NO, BAD, PREAUTH, BYE) with their
+ * human-readable text and response codes, as well as continuation responses ("+").
+ */
 class ParserInstance {
+    /**
+     * Creates a new ParserInstance for parsing an IMAP response line.
+     *
+     * @param {Buffer|string} input - The raw IMAP response line to parse.
+     * @param {Object} [options] - Parser options passed through to the TokenParser for attribute parsing.
+     * @param {boolean} [options.literalPlus] - Whether the LITERAL+ extension is in use.
+     * @param {Array<Buffer>} [options.literals] - Pre-parsed literal values from the stream.
+     */
     constructor(input, options) {
         this.input = (input || '').toString();
         this.options = options || {};
@@ -14,6 +27,14 @@ class ParserInstance {
         this.pos = 0;
     }
 
+    /**
+     * Extracts and returns the IMAP tag from the beginning of the response.
+     * The tag is typically "*" for untagged responses, "+" for continuation requests,
+     * or a client-assigned command tag like "A1".
+     *
+     * @returns {Promise<string>} The parsed tag string.
+     * @throws {Error} If the tag contains invalid characters.
+     */
     async getTag() {
         if (!this.tag) {
             this.tag = await this.getElement(imapFormalSyntax.tag() + '*+', true);
@@ -21,6 +42,15 @@ class ParserInstance {
         return this.tag;
     }
 
+    /**
+     * Extracts and returns the IMAP command or response name from the input.
+     * For continuation responses (tag "+"), returns an empty string and stores
+     * the remainder as human-readable text. For status responses (OK, NO, BAD,
+     * PREAUTH, BYE), separates the optional response code from the human-readable text.
+     *
+     * @returns {Promise<string>} The parsed command string.
+     * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
+     */
     async getCommand() {
         if (this.tag === '+') {
             // special case
@@ -34,6 +64,10 @@ class ParserInstance {
             this.command = await this.getElement(imapFormalSyntax.command());
         }
 
+        // Status responses have the format: TAG OK/NO/BAD [response-code] human-readable text
+        // Example: * OK [CAPABILITY IMAP4rev1] Server ready
+        // Example: A1 NO [AUTHENTICATIONFAILED] Invalid credentials
+        // We need to separate the optional [response-code] from the human-readable text.
         switch ((this.command || '').toString().toUpperCase()) {
             case 'OK':
             case 'NO':
@@ -69,6 +103,14 @@ class ParserInstance {
         return this.command;
     }
 
+    /**
+     * Extracts the next whitespace-delimited element from the input and validates it
+     * against the given syntax character set. Advances the parser position past the element.
+     *
+     * @param {string} syntax - A string of allowed characters for the element (as returned by imap-formal-syntax methods).
+     * @returns {Promise<string>} The extracted element string.
+     * @throws {Error} If the element contains characters not in the syntax set, or if input ends unexpectedly.
+     */
     async getElement(syntax) {
         let match, element, errPos;
 
@@ -83,7 +125,10 @@ class ParserInstance {
             element = match[0];
             if ((errPos = imapFormalSyntax.verify(element, syntax)) >= 0) {
                 if (this.tag === 'Server' && element === 'Unavailable.') {
-                    // Exchange error
+                    // Microsoft Exchange sometimes sends a non-standard response
+                    // "Server Unavailable." instead of a proper IMAP tagged/untagged response.
+                    // We detect this specific pattern and convert it into a synthetic BAD response
+                    // so the rest of the parser can handle it gracefully.
                     let error = new Error(`Server returned an error: ${this.input}`);
                     error.code = 'ParserErrorExchange';
                     error.parserContext = {
@@ -117,6 +162,13 @@ class ParserInstance {
         return element;
     }
 
+    /**
+     * Consumes a single space character from the current position in the input.
+     * Advances the parser position by one.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the current character is not a space, or if input has ended unexpectedly.
+     */
     async getSpace() {
         if (!this.remainder.length) {
             if (this.tag === '+' && this.pos === 1) {
@@ -141,6 +193,14 @@ class ParserInstance {
         this.remainder = this.remainder.substr(1);
     }
 
+    /**
+     * Parses the remaining input as IMAP attributes using the TokenParser.
+     * This handles complex structures including nested lists, literals, strings,
+     * atoms, sections, sequences, and partial ranges.
+     *
+     * @returns {Promise<Array>} A promise that resolves to an array of parsed attribute objects.
+     * @throws {Error} If the input contains unexpected whitespace, invalid characters, or ends unexpectedly.
+     */
     async getAttributes() {
         if (!this.remainder.length) {
             let error = new Error(`Unexpected end of input at position ${this.pos} [E6]`);