imapflow 1.7.8 → 2.0.0

package/{lib → dist/esm}/handler/parser-instance.js

@@ -1,24 +1,19 @@
 /* eslint new-cap: 0 */
-
-'use strict';
-
-const imapFormalSyntax = require('./imap-formal-syntax');
-
-const { TokenParser } = require('./token-parser');
-
+import imapFormalSyntax from './imap-formal-syntax.js';
+import { TokenParser } from './token-parser.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 ("+").
  */
-class ParserInstance {
+export 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.
+     * @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, options) {
         this.input = (input || '').toString();
@@ -26,29 +21,27 @@ class ParserInstance {
         this.remainder = this.input;
         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.
+     * @returns 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);
+            this.tag = await this.getElement(imapFormalSyntax.tag() + '*+');
         }
         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.
+     * @returns The parsed command string.
      * @throws {Error} If the command contains invalid characters or input ends unexpectedly.
      */
     async getCommand() {
@@ -56,14 +49,11 @@ class ParserInstance {
             // special case
             this.humanReadable = this.remainder.trim();
             this.remainder = '';
-
             return '';
         }
-
         if (!this.command) {
             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
@@ -85,10 +75,10 @@ class ParserInstance {
                         let end = -1;
                         for (let i = match[0].length; i < this.remainder.length; i++) {
                             let c = this.remainder[i];
-
                             if (c === '[') {
                                 nesting++;
-                            } else if (c === ']') {
+                            }
+                            else if (c === ']') {
                                 nesting--;
                             }
                             if (!nesting) {
@@ -96,7 +86,6 @@ class ParserInstance {
                                 break;
                             }
                         }
-
                         // Unbalanced '[' inside the code: the RFC 9051 free-text form
                         // (`atom [SP 1*<any TEXT-CHAR except "]">]`) permits '[' but not
                         // ']', so the code really does end at the first ']' here. Without
@@ -106,40 +95,36 @@ class ParserInstance {
                         if (end < 0) {
                             end = this.remainder.indexOf(']', match[0].length);
                         }
-
                         if (end >= 0) {
                             this.humanReadable = this.remainder.substring(end + 1).trim();
                             this.remainder = this.remainder.substring(0, end + 1);
                         }
-                    } else {
+                    }
+                    else {
                         this.humanReadable = this.remainder.trim();
                         this.remainder = '';
                     }
                 }
                 break;
         }
-
         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.
+     * @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.
      */
     async getElement(syntax) {
         let match, element, errPos;
-
         if (/^\s/.test(this.remainder)) {
             let error = new Error(`Unexpected whitespace at position ${this.pos} [E1]`);
             error.code = 'ParserError1';
             error.parserContext = { input: this.input, pos: this.pos };
             throw error;
         }
-
         if ((match = this.remainder.match(/^\s*[^\s]+(?=\s|$)/))) {
             element = match[0];
             if ((errPos = imapFormalSyntax.verify(element, syntax)) >= 0) {
@@ -162,30 +147,26 @@ class ParserInstance {
                     };
                     throw error;
                 }
-
                 let error = new Error(`Unexpected char at position ${this.pos + errPos} [E2: ${JSON.stringify(element.charAt(errPos))}]`);
                 error.code = 'ParserError2';
                 error.parserContext = { input: this.input, element, pos: this.pos };
                 throw error;
             }
-        } else {
+        }
+        else {
             let error = new Error(`Unexpected end of input at position ${this.pos} [E3]`);
             error.code = 'ParserError3';
             error.parserContext = { input: this.input, pos: this.pos };
             throw error;
         }
-
         this.pos += match[0].length;
         this.remainder = this.remainder.substr(match[0].length);
-
         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() {
@@ -194,30 +175,26 @@ class ParserInstance {
                 // special case, empty + response
                 return;
             }
-
             let error = new Error(`Unexpected end of input at position ${this.pos} [E4]`);
             error.code = 'ParserError4';
             error.parserContext = { input: this.input, pos: this.pos };
             throw error;
         }
-
         if (imapFormalSyntax.verify(this.remainder.charAt(0), imapFormalSyntax.SP()) >= 0) {
             let error = new Error(`Unexpected char at position ${this.pos} [E5: ${JSON.stringify(this.remainder.charAt(0))}]`);
             error.code = 'ParserError5';
             error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
             throw error;
         }
-
         this.pos++;
         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.
+     * @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.
      */
     async getAttributes() {
@@ -227,18 +204,13 @@ class ParserInstance {
             error.parserContext = { input: this.input, pos: this.pos };
             throw error;
         }
-
         if (/^\s/.test(this.remainder)) {
             let error = new Error(`Unexpected whitespace at position ${this.pos} [E7]`);
             error.code = 'ParserError7';
             error.parserContext = { input: this.input, element: this.remainder, pos: this.pos };
             throw error;
         }
-
         const tokenParser = new TokenParser(this, this.pos, this.remainder, this.options);
-
         return await tokenParser.getAttributes();
     }
 }
-
-module.exports.ParserInstance = ParserInstance;

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

@@ -0,0 +1,91 @@
+import type { ImapAttributeList, ParserOptions } from './types.js';
+import type { ParserInstance } from './parser-instance.js';
+/**
+ * A node of the parse tree built by TokenParser. `type` is false for a node that has not
+ * been classified yet, 'TREE' for the root, and otherwise the token or structure type
+ * (ATOM, string, LITERAL, SEQUENCE, LIST, SECTION, PARTIAL).
+ */
+export interface TokenNode {
+    childNodes: TokenNode[];
+    type: string | false;
+    value: string | Buffer;
+    isClosed: boolean;
+    parentNode?: TokenNode | undefined;
+    depth: number;
+    startPos?: number | undefined;
+    endPos?: number | undefined;
+    literalType?: string | undefined;
+    /** Digits accumulated as a string while the literal marker is read, converted to a number once the marker closes */
+    literalLength?: string | number | undefined;
+    literalPlus?: boolean | undefined;
+    started?: boolean | undefined;
+    chBuffer?: Buffer | undefined;
+    chPos?: number | undefined;
+}
+/**
+ * The parent object a TokenParser reads the parsed command from
+ */
+export interface TokenParserParent {
+    command?: string | undefined;
+}
+/**
+ * Tokenizes an IMAP attribute string into a tree of typed nodes.
+ * Handles all IMAP data types: atoms, quoted strings, literals (including literal8),
+ * sequences, lists (parenthesized groups), sections (bracketed groups), and partial ranges.
+ * Enforces a maximum nesting depth of {@link MAX_NODE_DEPTH} to prevent stack overflow
+ * from malicious input.
+ */
+export declare class TokenParser {
+    str: string;
+    options: ParserOptions;
+    parent: TokenParserParent | ParserInstance;
+    maxLiteralSize: number;
+    tree: TokenNode;
+    currentNode: TokenNode;
+    pos: number;
+    state: number;
+    expectedLiteralType?: string | false | undefined;
+    /**
+     * Creates a new TokenParser.
+     *
+     * @param parent - The parent ParserInstance that owns this token parser. Used to access the parsed command for context-sensitive parsing.
+     * @param startPos - The starting position offset in the original input, used for error reporting.
+     * @param str - The attribute string to tokenize.
+     * @param options - Parser options.
+     * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+     * @param options.literals - Pre-parsed literal values from the input stream.
+     * @param options.maxLiteralSize - Maximum size (in bytes) of a literal parsed inline
+     *   from the input, i.e. when no pre-parsed literal buffers were supplied. Defaults to 1GB.
+     */
+    constructor(parent: TokenParserParent | ParserInstance, startPos?: number | undefined, str?: string | null | undefined, options?: ParserOptions | undefined);
+    /**
+     * Processes the input string and returns the parsed attributes as a flat array of typed objects.
+     * Each attribute is an object with a `type` (e.g., "ATOM", "STRING", "LITERAL", "SEQUENCE")
+     * and a `value` property. Lists are represented as nested arrays. Sections and partials are
+     * attached as properties on the preceding attribute object.
+     *
+     * @returns A promise that resolves to an array of parsed attribute objects and nested arrays.
+     * @throws {Error} If the input contains syntax errors or unclosed nodes.
+     */
+    getAttributes(): Promise<ImapAttributeList>;
+    /**
+     * Creates a new node in the parse tree. Each node represents a token or structural
+     * element (e.g., atom, string, literal, list, section, partial). The node is automatically
+     * appended to the parent's childNodes array if a parent is provided.
+     *
+     * @param parentNode - The parent node to attach this node to. If omitted, creates a root node.
+     * @param startPos - The starting position of this node in the original input string.
+     * @returns The newly created node with childNodes, type, value, and isClosed properties.
+     * @throws {Error} If the nesting depth exceeds MAX_NODE_DEPTH.
+     */
+    createNode(parentNode?: TokenNode | undefined, startPos?: number | undefined): TokenNode;
+    /**
+     * Processes the entire input string character by character using a state machine.
+     * Transitions between states (NORMAL, ATOM, STRING, LITERAL, SEQUENCE, PARTIAL, TEXT)
+     * based on the current character and builds the parse tree. This is the main parsing
+     * loop that drives the tokenization.
+     *
+     * @throws {Error} If the input contains unexpected characters, unclosed structures, or other syntax errors.
+     */
+    processString(): Promise<void>;
+}