imapflow 1.7.8 → 2.0.0

package/{lib → dist/esm}/handler/imap-stream.js

@@ -1,59 +1,26 @@
-'use strict';
-
-const Transform = require('stream').Transform;
-const logger = require('../logger');
-const { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError } = require('./limits');
-
+import { Transform } from 'node:stream';
+import logger from '../logger.js';
+import { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError } from './limits.js';
 const LINE = 0x01;
 const LITERAL = 0x02;
-
 const LF = 0x0a;
 const CR = 0x0d;
 const NUM_0 = 0x30;
 const NUM_9 = 0x39;
 const CURLY_OPEN = 0x7b;
 const CURLY_CLOSE = 0x7d;
-
 /**
  * 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 {
+export 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.
-     * @param {number} [options.maxLineLength] - Maximum allowed length (in bytes) of a single
-     *   line (a response without a literal). Defaults to MAX_LITERAL_SIZE (1GB). Guards against a
-     *   malicious or broken server that never sends a line terminator, which would otherwise grow
-     *   the internal line buffer without bound. The line terminator counts toward the limit, and a
-     *   line exactly at the limit is accepted. Exceeding it is terminal: the stream is destroyed
-     *   with a `LineTooLarge` error and no further input is parsed.
-     * @param {number} [options.maxLiteralSize] - Maximum allowed size (in bytes) of a single
-     *   literal block. Defaults to MAX_LITERAL_SIZE (1GB). Lower it to bound peak memory
-     *   allocation against a malicious or broken server announcing an oversized literal. A literal
-     *   exactly at the limit is accepted. Exceeding it is terminal: the stream is destroyed with a
-     *   `LiteralTooLarge` error, the marker line is not emitted, and no byte of the rejected
-     *   literal body is parsed as protocol.
-     * @param {number} [options.maxResponseSize] - Maximum allowed total size (in bytes) of a
-     *   single assembled response: every line segment and literal of one response combined.
-     *   Defaults to MAX_RESPONSE_SIZE (2GB), which leaves room above the literal cap for a
-     *   maximum-size literal plus its marker line. The per-line and per-literal caps alone
-     *   cannot stop a server that spreads attacker-controlled bytes across an unbounded
-     *   number of tokens of a single response. Declared literal sizes count when their
-     *   marker is parsed, so an oversized total is rejected before the literal bytes arrive,
-     *   and a line still being assembled counts against whatever budget is left.
-     *   Exceeding the limit is terminal: the stream is destroyed with a `ResponseTooLarge`
-     *   error and no further input is parsed.
+     * @param options - Stream options, see ImapStreamOptions.
      */
     constructor(options) {
         super({
@@ -61,30 +28,23 @@ class ImapStream extends Transform {
             readableObjectMode: true,
             writableObjectMode: false
         });
-
         this.options = options || {};
         this.cid = this.options.cid;
-
         this.log =
             this.options.logger && typeof this.options.logger === 'object'
                 ? this.options.logger
                 : logger.child({
-                      component: 'imap-connection',
-                      cid: this.cid
-                  });
-
+                    component: 'imap-connection',
+                    cid: this.cid
+                });
         this.readBytesCounter = 0;
-
         // Maximum length of a single line (response without a literal). Bounds the line buffer
         // so a server that never sends a line terminator cannot exhaust memory.
         this.maxLineLength = normalizeLimit(this.options.maxLineLength, MAX_LINE_SIZE);
-
         // Maximum size of a single literal block. Bounds peak memory allocation so a server
         // announcing an oversized literal cannot exhaust memory.
         this.maxLiteralSize = normalizeLimit(this.options.maxLiteralSize, MAX_LITERAL_SIZE);
-
         this.maxResponseSize = normalizeLimit(this.options.maxResponseSize, MAX_RESPONSE_SIZE);
-
         this.state = LINE;
         this.literalWaiting = 0;
         this.inputBuffer = []; // lines
@@ -93,19 +53,15 @@ class ImapStream extends Transform {
         this.literalBuffer = [];
         this.literals = [];
         this.responseBytes = 0; // bytes accumulated for the in-progress response (lines + declared literals)
-
         this.compress = false;
         this.secureConnection = this.options.secureConnection;
-
         this.processingInput = false;
         this.inputQueue = []; // unprocessed input chunks
         this.activeInput = null; // chunk currently being processed (already shifted off inputQueue)
-
         // Resolver of the in-flight push() backpressure promise, so destruction can settle it
         // instead of leaving processInput() awaiting a consumer that will never read again.
         this.pendingPush = null;
     }
-
     /**
      * Terminally fails the stream. Used for response limit violations and for any other
      * error raised while parsing.
@@ -119,8 +75,8 @@ class ImapStream extends Transform {
      * `destroyed` (set synchronously by destroy()) is the single liveness flag every other path
      * checks, so a second failure attempt is a no-op and nothing is parsed after the first.
      *
-     * @param {Error} err - The error to destroy the stream with.
-     * @returns {boolean} Always false, so callers can `return this.failStream(err)`.
+     * @param err - The error to destroy the stream with.
+     * @returns Always false, so callers can `return this.failStream(err)`.
      */
     failStream(err) {
         if (this.destroyed) {
@@ -129,13 +85,12 @@ class ImapStream extends Transform {
         this.destroy(err);
         return false;
     }
-
     /**
      * Releases a queued input chunk's transform callback exactly once, signalling the writable
      * side that the chunk was consumed. The mirror image of ImapFlow's releaseStreamData(), which
      * releases the readable items this stream pushes downstream.
      *
-     * @param {Object} item - Queue entry holding the chunk and its transform callback.
+     * @param item - Queue entry holding the chunk and its transform callback.
      */
     releaseInput(item) {
         if (!item || item.released) {
@@ -146,37 +101,31 @@ class ImapStream extends Transform {
             item.next();
         }
     }
-
     /**
      * 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.
+     * @param line - The line buffer to check for a trailing literal marker.
+     * @returns True if a valid literal marker was found and literal state was activated, false otherwise.
      */
     checkLiteralMarker(line) {
         if (!line || !line.length) {
             return false;
         }
-
         let pos = line.length - 1;
-
         if (line[pos] !== LF) {
             return false;
         }
         pos--;
-
         if (pos >= 0 && line[pos] === CR) {
             pos--;
         }
-
         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 '}'.
         // Only the digit run's bounds are tracked - a single linear pass, unlike
@@ -200,19 +149,15 @@ class ImapStream extends Transform {
                 while (digitsStart < digitsEnd && line[digitsStart] === NUM_0) {
                     digitsStart++;
                 }
-
                 // More significant digits than any number64 has cannot fit any
                 // permissible maxLiteralSize; fail closed without materializing them
                 if (digitsEnd + 1 - digitsStart > 19) {
                     return this.failStream(createLiteralTooLargeError(Infinity, this.maxLiteralSize, 'the widest permissible literal size (19 digits)'));
                 }
-
                 const literalSize = Number(line.toString('latin1', digitsStart, digitsEnd + 1));
-
                 if (literalSize > this.maxLiteralSize) {
                     return this.failStream(createLiteralTooLargeError(literalSize, this.maxLiteralSize));
                 }
-
                 this.state = LITERAL;
                 this.literalWaiting = literalSize;
                 return true;
@@ -221,14 +166,13 @@ class ImapStream extends Transform {
         }
         return false;
     }
-
     /**
      * Enforces the configured line-length cap for a projected line length. The projected length
      * covers every byte of the line, the line terminator included, whether or not the line was
      * split across input chunks. A line exactly at the limit is accepted.
      *
-     * @param {number} lineLength - Total length the current line would reach.
-     * @returns {boolean} True if the line is within the limit, false if the stream was failed.
+     * @param lineLength - Total length the current line would reach.
+     * @returns True if the line is within the limit, false if the stream was failed.
      */
     checkLineLength(lineLength) {
         if (lineLength <= this.maxLineLength) {
@@ -240,18 +184,17 @@ class ImapStream extends Transform {
         err.maxSize = this.maxLineLength;
         return this.failStream(err);
     }
-
     /**
      * Enforces the configured per-response size cap: the cumulative bytes of every line
      * segment and declared literal of the response currently being assembled. Counting
      * declared literal sizes at marker time means an oversized total is rejected before
      * the literal bytes even arrive. The counter is reset when a response is emitted.
      *
-     * @param {number} additionalBytes - Bytes the next token would add to the response.
-     * @param {boolean} [peek] - Measure only, without committing the bytes to the counter.
+     * @param additionalBytes - Bytes the next token would add to the response.
+     * @param peek - Measure only, without committing the bytes to the counter.
      *   Used for a line that is still being assembled: its bytes are committed once, when the
      *   line completes.
-     * @returns {boolean} True if within the limit, false if the stream was failed.
+     * @returns True if within the limit, false if the stream was failed.
      */
     checkResponseSize(additionalBytes, peek) {
         let total = this.responseBytes + additionalBytes;
@@ -267,23 +210,20 @@ class ImapStream extends Transform {
         err.maxSize = this.maxResponseSize;
         return this.failStream(err);
     }
-
     /**
      * 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>}
+     * @param chunk - The raw data chunk to process.
+     * @param startPos - The byte offset within the chunk to start processing from.
      */
     async processInputChunk(chunk, startPos) {
         startPos = startPos || 0;
         if (this.destroyed || startPos >= chunk.length) {
             return;
         }
-
         switch (this.state) {
             case LINE: {
                 let lineStart = startPos;
@@ -296,15 +236,11 @@ class ImapStream extends Transform {
                         if (!this.checkLineLength(this.lineBytes + segment.length)) {
                             return;
                         }
-
                         this.lineBuffer.push(segment);
                         lineStart = i + 1;
-
                         let line = this.lineBuffer.length === 1 ? this.lineBuffer[0] : Buffer.concat(this.lineBuffer);
-
                         this.lineBuffer = [];
                         this.lineBytes = 0;
-
                         // try to detect if this is a literal start. An oversized literal fails the
                         // stream, so the marker line must not be buffered before the check - it
                         // would otherwise be emitted as part of the rejected command.
@@ -312,28 +248,23 @@ class ImapStream extends Transform {
                         if (this.destroyed) {
                             return;
                         }
-
                         // Count the line itself and, for a literal marker, the declared
                         // literal bytes against the cumulative per-response budget, so a
                         // response assembled from many tokens stays bounded as a whole
                         if (!this.checkResponseSize(line.length + (isLiteralMarker ? this.literalWaiting : 0))) {
                             return;
                         }
-
                         this.inputBuffer.push(line);
-
                         if (isLiteralMarker) {
                             // switch into literal mode and start over
                             return await this.processInputChunk(chunk, lineStart);
                         }
-
                         // reached end of command input, emit it
                         let payload = this.inputBuffer.length === 1 ? this.inputBuffer[0] : Buffer.concat(this.inputBuffer);
                         let literals = this.literals;
                         this.inputBuffer = [];
                         this.literals = [];
                         this.responseBytes = 0;
-
                         if (payload.length) {
                             // remove final line terminator (\n or \r\n)
                             if (payload[payload.length - 1] === LF) {
@@ -343,10 +274,9 @@ class ImapStream extends Transform {
                                 }
                                 payload = payload.slice(0, end);
                             }
-
                             if (payload.length) {
                                 // Whether more buffered input already followed this command on the
-                                // wire — more bytes in this chunk or another queued chunk. Captured
+                                // wire - more bytes in this chunk or another queued chunk. Captured
                                 // per emitted command (immutable on the pushed object) so a later
                                 // command cannot overwrite it; consumers that care about pipelining
                                 // boundaries can read it from the pushed object.
@@ -356,10 +286,10 @@ class ImapStream extends Transform {
                                     // this loop (and the chunk's transform callback) pending forever
                                     // when the consumer stops reading.
                                     this.pendingPush = resolve;
-                                    this.push({ payload, literals, next: resolve, trailingAfterLine });
+                                    const item = { payload, literals, next: resolve, trailingAfterLine };
+                                    this.push(item);
                                 });
                                 this.pendingPush = null;
-
                                 if (this.destroyed) {
                                     return;
                                 }
@@ -384,20 +314,16 @@ class ImapStream extends Transform {
                 }
                 break;
             }
-
             case LITERAL: {
                 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.literalBuffer.push(partial);
                 this.literalWaiting -= bytesToRead;
-
                 if (this.literalWaiting === 0) {
                     this.literals.push(Buffer.concat(this.literalBuffer));
                     this.literalBuffer = [];
                     this.state = LINE;
-
                     if (remainingInChunk > bytesToRead) {
                         return await this.processInputChunk(chunk, startPos + bytesToRead);
                     }
@@ -406,13 +332,10 @@ class ImapStream extends Transform {
             }
         }
     }
-
     /**
      * 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;
@@ -423,7 +346,6 @@ class ImapStream extends Transform {
             this.activeInput = null;
             // mark chunk as processed
             this.releaseInput(data);
-
             // Yield to event loop every 10 chunks to prevent CPU blocking
             processedCount++;
             if (processedCount % 10 === 0) {
@@ -431,27 +353,23 @@ 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.
+     * @param chunk - The incoming data chunk.
+     * @param encoding - The encoding if chunk is a string.
+     * @param next - Callback to signal that this chunk has been consumed.
      */
     _transform(chunk, encoding, next) {
         if (typeof chunk === 'string') {
             chunk = Buffer.from(chunk, encoding);
         }
-
         if (!chunk || !chunk.length) {
             return next();
         }
-
         this.readBytesCounter += chunk.length;
-
         if (this.options.logRaw) {
             this.log.trace({
                 src: 's',
@@ -462,18 +380,15 @@ class ImapStream extends Transform {
                 cid: this.cid
             });
         }
-
         // A terminal parser failure must not accept any more protocol input, even if the
         // transport delivers a chunk that was already in flight.
         if (this.destroyed) {
             return next();
         }
-
         // 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.
         this.inputQueue.push({ chunk, next });
-
         if (!this.processingInput) {
             this.processingInput = true;
             this.processInput()
@@ -481,22 +396,20 @@ class ImapStream extends Transform {
                 .finally(() => (this.processingInput = false));
         }
     }
-
     /**
      * Flush implementation called when the writable side ends. Signals completion immediately.
      *
-     * @param {Function} next - Callback to signal flush completion.
+     * @param 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.
+     * @param err - The error that caused destruction, or null.
+     * @param callback - Callback to signal destruction completion.
      */
     _destroy(err, callback) {
         // Destruction is the single release point for parser-owned callbacks, so a terminal
@@ -507,14 +420,12 @@ class ImapStream extends Transform {
         this.literalBuffer = [];
         this.literals = [];
         this.responseBytes = 0;
-
         // Settle an in-flight push() wait so processInput() can unwind
         if (typeof this.pendingPush === 'function') {
             const resolve = this.pendingPush;
             this.pendingPush = null;
             resolve();
         }
-
         // Release the chunk currently being processed, then everything still queued.
         // releaseInput() is idempotent, so the processing loop releasing the same chunk
         // afterwards is a no-op.
@@ -523,9 +434,6 @@ class ImapStream extends Transform {
         while (this.inputQueue.length) {
             this.releaseInput(this.inputQueue.shift());
         }
-
         callback(err);
     }
 }
-
-module.exports.ImapStream = ImapStream;

package/dist/esm/handler/limits.d.ts

@@ -0,0 +1,25 @@
+import type { ImapFlowError } from '../errors.js';
+export declare const MAX_LITERAL_SIZE: number;
+export declare const MAX_LINE_SIZE: number;
+export declare const MAX_RESPONSE_SIZE: number;
+/**
+ * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
+ * means "reject anything non-empty"), and `Infinity` disables the limit; anything else falls back
+ * to the default, so an explicit 0 is not silently swallowed the way `value || DEFAULT` would
+ * swallow it.
+ *
+ * @param value - The configured value.
+ * @param defaultValue - Fallback when the value is not a usable limit.
+ * @returns The normalized limit.
+ */
+export declare const normalizeLimit: (value: unknown, defaultValue: number) => number;
+/**
+ * Builds the `LiteralTooLarge` error. One shape for every place a literal is refused, so callers
+ * can rely on `code`, `literalSize` and `maxSize` regardless of which parser rejected it.
+ *
+ * @param literalSize - The declared literal size.
+ * @param maxSize - The bound that was exceeded.
+ * @param reason - What the bound was, when it is not the configured maximum.
+ * @returns The error to emit or throw.
+ */
+export declare const createLiteralTooLargeError: (literalSize: number, maxSize: number, reason?: string | null | undefined) => ImapFlowError;

package/{lib → dist/esm}/handler/limits.js

@@ -1,17 +1,12 @@
-'use strict';
-
 // Shared response-size limits for the IMAP parser. Kept in one place so the streaming parser
 // (ImapStream) and the standalone token parser cannot drift apart, and so the documented
-// defaults in imap-flow.d.ts describe both paths.
-
+// defaults in the ImapFlowOptions type describe both paths.
 // Maximum allowed literal size: 1GB (1073741824 bytes)
-const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
-
+export const MAX_LITERAL_SIZE = 1024 * 1024 * 1024;
 // Default maximum length of a single line (a response without a literal). Matches the literal cap:
 // large literal-free responses (e.g. big SEARCH/LIST results) are legitimate, so this bound exists
 // only to stop a server that never sends a line terminator, not to constrain normal traffic.
-const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
-
+export const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
 // Default maximum total size of a single assembled response: every line segment and literal of
 // one response combined. The per-line and per-literal caps alone cannot stop a server that
 // spreads attacker-controlled bytes across an unbounded number of tokens of a single response
@@ -21,35 +16,31 @@ const MAX_LINE_SIZE = MAX_LITERAL_SIZE;
 // and the rest of the response framing, so a cap equal to MAX_LITERAL_SIZE would make a literal
 // of exactly the maximum permitted size impossible to receive. Configuring both limits calls for
 // the same headroom - set maxResponseSize above maxLiteralSize, not equal to it.
-const MAX_RESPONSE_SIZE = 2 * MAX_LITERAL_SIZE;
-
+export const MAX_RESPONSE_SIZE = 2 * MAX_LITERAL_SIZE;
 /**
  * Normalizes a configured size limit. A non-negative integer is honored as-is (including 0, which
  * means "reject anything non-empty"), and `Infinity` disables the limit; anything else falls back
  * to the default, so an explicit 0 is not silently swallowed the way `value || DEFAULT` would
  * swallow it.
  *
- * @param {*} value - The configured value.
- * @param {number} defaultValue - Fallback when the value is not a usable limit.
- * @returns {number} The normalized limit.
+ * @param value - The configured value.
+ * @param defaultValue - Fallback when the value is not a usable limit.
+ * @returns The normalized limit.
  */
-const normalizeLimit = (value, defaultValue) => ((Number.isInteger(value) || value === Infinity) && value >= 0 ? value : defaultValue);
-
+export const normalizeLimit = (value, defaultValue) => (Number.isInteger(value) || value === Infinity) && value >= 0 ? value : defaultValue;
 /**
  * Builds the `LiteralTooLarge` error. One shape for every place a literal is refused, so callers
  * can rely on `code`, `literalSize` and `maxSize` regardless of which parser rejected it.
  *
- * @param {number} literalSize - The declared literal size.
- * @param {number} maxSize - The bound that was exceeded.
- * @param {string} [reason] - What the bound was, when it is not the configured maximum.
- * @returns {Error} The error to emit or throw.
+ * @param literalSize - The declared literal size.
+ * @param maxSize - The bound that was exceeded.
+ * @param reason - What the bound was, when it is not the configured maximum.
+ * @returns The error to emit or throw.
  */
-const createLiteralTooLargeError = (literalSize, maxSize, reason) => {
+export const createLiteralTooLargeError = (literalSize, maxSize, reason) => {
     const err = new Error(`Literal size ${literalSize} exceeds ${reason || `maximum allowed size of ${maxSize} bytes`}`);
     err.code = 'LiteralTooLarge';
     err.literalSize = literalSize;
     err.maxSize = maxSize;
     return err;
 };
-
-module.exports = { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError };

package/dist/esm/handler/parser-instance.d.ts

@@ -0,0 +1,68 @@
+import type { ImapAttributeList, ParserOptions } from './types.js';
+/**
+ * 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 ("+").
+ */
+export declare class ParserInstance {
+    input: string;
+    options: ParserOptions;
+    remainder: string;
+    pos: number;
+    tag?: string | undefined;
+    command?: string | undefined;
+    humanReadable?: string | undefined;
+    /**
+     * Creates a new ParserInstance for parsing an IMAP response line.
+     *
+     * @param input - The raw IMAP response line to parse.
+     * @param options - Parser options passed through to the TokenParser for attribute parsing.
+     * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+     * @param options.literals - Pre-parsed literal values from the stream.
+     */
+    constructor(input?: Buffer | string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * 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 The parsed tag string.
+     * @throws {Error} If the tag contains invalid characters.
+     */
+    getTag(): Promise<string>;
+    /**
+     * 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 The parsed command string.
+     * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
+     */
+    getCommand(): Promise<string>;
+    /**
+     * 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 syntax - A string of allowed characters for the element (as returned by imap-formal-syntax methods).
+     * @returns The extracted element string.
+     * @throws {Error} If the element contains characters not in the syntax set, or if input ends unexpectedly.
+     */
+    getElement(syntax: string): Promise<string>;
+    /**
+     * Consumes a single space character from the current position in the input.
+     * Advances the parser position by one.
+     *
+     * @throws {Error} If the current character is not a space, or if input has ended unexpectedly.
+     */
+    getSpace(): Promise<void>;
+    /**
+     * 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 A promise that resolves to an array of parsed attribute objects.
+     * @throws {Error} If the input contains unexpected whitespace, invalid characters, or ends unexpectedly.
+     */
+    getAttributes(): Promise<ImapAttributeList>;
+}