imapflow 2.3.0 → 2.4.0

package/dist/esm/handler/token-parser.js

@@ -1,6 +1,7 @@
 /* eslint new-cap: 0 */
 import imapFormalSyntax from './imap-formal-syntax.js';
 import { MAX_LITERAL_SIZE, ERROR_CONTEXT_LENGTH, boundedInput, normalizeLimit, createLiteralTooLargeError } from './limits.js';
+import { createImapError } from '../errors.js';
 const STATE_ATOM = 0x001;
 const STATE_LITERAL = 0x002;
 const STATE_NORMAL = 0x003;
@@ -42,6 +43,23 @@ export class TokenParser {
         this.currentNode.type = 'TREE';
         this.state = STATE_NORMAL;
     }
+    /**
+     * Builds a numbered parser error that carries a bounded copy of the input and the position
+     * (and character, when there is one) where parsing failed.
+     *
+     * @param message - The error message
+     * @param code - The numbered parser error code
+     * @param pos - Position of the failure in the original input
+     * @param chr - The offending character
+     * @returns The error to throw
+     */
+    parserError(message, code, pos, chr) {
+        const parserContext = { ...boundedInput(this.str), pos };
+        if (chr !== undefined) {
+            parserContext.chr = chr;
+        }
+        return createImapError(message, code, { parserContext });
+    }
     /**
      * 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")
@@ -65,10 +83,7 @@ export class TokenParser {
             }
             // If the node was never closed, throw it
             if (!node.isClosed) {
-                let error = new Error(`Unexpected end of input at position ${this.pos + this.str.length - 1} [E9]`);
-                error.code = 'ParserError9';
-                error.parserContext = { ...boundedInput(this.str), pos: this.pos + this.str.length - 1 };
-                throw error;
+                throw this.parserError(`Unexpected end of input at position ${this.pos + this.str.length - 1} [E9]`, 'ParserError9', this.pos + this.str.length - 1);
             }
             let type = (node.type || '').toString().toUpperCase();
             switch (type) {
@@ -139,11 +154,8 @@ export class TokenParser {
             node.depth = 0;
         }
         if (node.depth > MAX_NODE_DEPTH) {
-            let error = new Error('Too much nesting in IMAP string');
-            error.code = 'MAX_IMAP_NESTING_REACHED';
             // A bounded prefix only, the error travels whole into logs and rejections
-            error._imapStr = this.str.slice(0, ERROR_CONTEXT_LENGTH);
-            throw error;
+            throw createImapError('Too much nesting in IMAP string', 'MAX_IMAP_NESTING_REACHED', { _imapStr: this.str.slice(0, ERROR_CONTEXT_LENGTH) });
         }
         if (typeof startPos === 'number') {
             node.startPos = startPos;
@@ -219,10 +231,7 @@ export class TokenParser {
         // error instead of reading a missing buffer or shifting every later literal by one
         const takeLiteral = (literals) => {
             if (!literals.length) {
-                let error = new Error(`Literal without data at position ${this.pos + i} [E35]`);
-                error.code = 'ParserError35';
-                error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                throw error;
+                throw this.parserError(`Literal without data at position ${this.pos + i} [E35]`, 'ParserError35', this.pos + i, chr);
             }
             return literals.shift();
         };
@@ -234,10 +243,7 @@ export class TokenParser {
         // used to fall through into the default branch
         const startAtom = () => {
             if (!imapFormalSyntax['ATOM-CHAR']().includes(chr) && chr !== '\\' && chr !== '%' && chr.charCodeAt(0) < 0x80) {
-                let error = new Error(`Unexpected char at position ${this.pos + i} [E13: ${JSON.stringify(chr)}]`);
-                error.code = 'ParserError13';
-                error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                throw error;
+                throw this.parserError(`Unexpected char at position ${this.pos + i} [E13: ${JSON.stringify(chr)}]`, 'ParserError13', this.pos + i, chr);
             }
             this.currentNode = this.createNode(this.currentNode, this.pos + i);
             this.currentNode.type = 'ATOM';
@@ -265,10 +271,7 @@ export class TokenParser {
                         // ) closes a list
                         case ')':
                             if (this.currentNode.type !== 'LIST') {
-                                let error = new Error(`Unexpected list terminator ) at position ${this.pos + i} [E10]`);
-                                error.code = 'ParserError10';
-                                error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                                throw error;
+                                throw this.parserError(`Unexpected list terminator ) at position ${this.pos + i} [E10]`, 'ParserError10', this.pos + i, chr);
                             }
                             this.currentNode.isClosed = true;
                             this.currentNode.endPos = this.pos + i;
@@ -278,10 +281,7 @@ export class TokenParser {
                         // ] closes section group
                         case ']':
                             if (this.currentNode.type !== 'SECTION') {
-                                let error = new Error(`Unexpected section terminator ] at position ${this.pos + i} [E11]`);
-                                error.code = 'ParserError11';
-                                error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                                throw error;
+                                throw this.parserError(`Unexpected section terminator ] at position ${this.pos + i} [E11]`, 'ParserError11', this.pos + i, chr);
                             }
                             this.currentNode.isClosed = true;
                             this.currentNode.endPos = this.pos + i;
@@ -322,10 +322,7 @@ export class TokenParser {
                                     startAtom();
                                     break;
                                 }
-                                let error = new Error(`Unexpected literal8 marker at position ${this.pos + i} [E12]`);
-                                error.code = 'ParserError12';
-                                error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                                throw error;
+                                throw this.parserError(`Unexpected literal8 marker at position ${this.pos + i} [E12]`, 'ParserError12', this.pos + i, chr);
                             }
                             // Mark the next literal as literal8 type; consumed when '{' is encountered
                             this.expectedLiteralType = 'literal8';
@@ -485,16 +482,10 @@ export class TokenParser {
                         chr !== ']' &&
                         !(chr === '*' && this.currentNode.value === '\\') &&
                         (!this.parent || !this.parent.command || !['NO', 'BAD', 'OK'].includes(this.parent.command.toUpperCase()))) {
-                        let error = new Error(`Unexpected char at position ${this.pos + i} [E16: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError16';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected char at position ${this.pos + i} [E16: ${JSON.stringify(chr)}]`, 'ParserError16', this.pos + i, chr);
                     }
                     else if (this.currentNode.value === '\\*') {
-                        let error = new Error(`Unexpected char at position ${this.pos + i} [E17: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError17';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected char at position ${this.pos + i} [E17: ${JSON.stringify(chr)}]`, 'ParserError17', this.pos + i, chr);
                     }
                     appendToToken(chr);
                     break;
@@ -512,10 +503,7 @@ export class TokenParser {
                     if (chr === '\\') {
                         i++;
                         if (i >= len) {
-                            let error = new Error(`Unexpected end of input at position ${this.pos + i} [E18]`);
-                            error.code = 'ParserError18';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i };
-                            throw error;
+                            throw this.parserError(`Unexpected end of input at position ${this.pos + i} [E18]`, 'ParserError18', this.pos + i);
                         }
                         chr = this.str.charAt(i);
                     }
@@ -524,10 +512,7 @@ export class TokenParser {
                 case STATE_PARTIAL:
                     if (chr === '>') {
                         if (tokenLast === '.') {
-                            let error = new Error(`Unexpected end of partial at position ${this.pos + i} [E19]`);
-                            error.code = 'ParserError19';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected end of partial at position ${this.pos + i} [E19]`, 'ParserError19', this.pos + i, chr);
                         }
                         this.currentNode.endPos = this.pos + i;
                         this.currentNode.isClosed = true;
@@ -537,22 +522,13 @@ export class TokenParser {
                         break;
                     }
                     if (chr === '.' && (!tokenLength || tokenHasDot)) {
-                        let error = new Error(`Unexpected partial separator . at position ${this.pos + i} [E20]`);
-                        error.code = 'ParserError20';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected partial separator . at position ${this.pos + i} [E20]`, 'ParserError20', this.pos + i, chr);
                     }
                     if (!imapFormalSyntax.DIGIT().includes(chr) && chr !== '.') {
-                        let error = new Error(`Unexpected char at position ${this.pos + i} [E21: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError21';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected char at position ${this.pos + i} [E21: ${JSON.stringify(chr)}]`, 'ParserError21', this.pos + i, chr);
                     }
                     if (tokenLast === '0' && (tokenLength === 1 || tokenPrev === '.') && chr !== '.') {
-                        let error = new Error(`Invalid partial at position ${this.pos + i} [E22: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError22';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Invalid partial at position ${this.pos + i} [E22: ${JSON.stringify(chr)}]`, 'ParserError22', this.pos + i, chr);
                     }
                     appendToToken(chr);
                     break;
@@ -584,10 +560,7 @@ export class TokenParser {
                     }
                     if (chr === '}') {
                         if (!('literalLength' in this.currentNode)) {
-                            let error = new Error(`Unexpected literal prefix end char } at position ${this.pos + i} [E23]`);
-                            error.code = 'ParserError23';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected literal prefix end char } at position ${this.pos + i} [E23]`, 'ParserError23', this.pos + i, chr);
                         }
                         if (this.str.charAt(i + 1) === '\n') {
                             i++;
@@ -596,10 +569,7 @@ export class TokenParser {
                             i += 2;
                         }
                         else {
-                            let error = new Error(`Unexpected char at position ${this.pos + i} [E24: ${JSON.stringify(chr)}]`);
-                            error.code = 'ParserError24';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected char at position ${this.pos + i} [E24: ${JSON.stringify(chr)}]`, 'ParserError24', this.pos + i, chr);
                         }
                         this.currentNode.literalLength = Number(this.currentNode.literalLength);
                         if (!this.currentNode.literalLength) {
@@ -660,16 +630,10 @@ export class TokenParser {
                         break;
                     }
                     if (!imapFormalSyntax.DIGIT().includes(chr)) {
-                        let error = new Error(`Unexpected char at position ${this.pos + i} [E25: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError25';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected char at position ${this.pos + i} [E25: ${JSON.stringify(chr)}]`, 'ParserError25', this.pos + i, chr);
                     }
                     if (this.currentNode.literalLength === '0') {
-                        let error = new Error(`Invalid literal at position ${this.pos + i} [E26]`);
-                        error.code = 'ParserError26';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Invalid literal at position ${this.pos + i} [E26]`, 'ParserError26', this.pos + i, chr);
                     }
                     this.currentNode.literalLength = (this.currentNode.literalLength || '') + chr;
                     break;
@@ -684,16 +648,10 @@ export class TokenParser {
                                 continueAsAtom();
                                 break;
                             }
-                            let error = new Error(`Unexpected end of sequence at position ${this.pos + i} [E27: ${JSON.stringify(chr)}]`);
-                            error.code = 'ParserError27';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected end of sequence at position ${this.pos + i} [E27: ${JSON.stringify(chr)}]`, 'ParserError27', this.pos + i, chr);
                         }
                         if (this.currentNode.value !== '*' && tokenLast === '*' && tokenPrev !== ':') {
-                            let error = new Error(`Unexpected end of sequence at position ${this.pos + i} [E28: ${JSON.stringify(chr)}]`);
-                            error.code = 'ParserError28';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected end of sequence at position ${this.pos + i} [E28: ${JSON.stringify(chr)}]`, 'ParserError28', this.pos + i, chr);
                         }
                         this.currentNode.isClosed = true;
                         this.currentNode.endPos = this.pos + i - 1;
@@ -713,18 +671,12 @@ export class TokenParser {
                                 continueAsAtom();
                                 break;
                             }
-                            let error = new Error(`Unexpected range separator : at position ${this.pos + i} [E29]`);
-                            error.code = 'ParserError29';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected range separator : at position ${this.pos + i} [E29]`, 'ParserError29', this.pos + i, chr);
                         }
                     }
                     else if (chr === '*') {
                         if (![',', ':'].includes(tokenLast)) {
-                            let error = new Error(`Unexpected range wildcard at position ${this.pos + i} [E30]`);
-                            error.code = 'ParserError30';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected range wildcard at position ${this.pos + i} [E30]`, 'ParserError30', this.pos + i, chr);
                         }
                     }
                     else if (chr === ',') {
@@ -733,16 +685,10 @@ export class TokenParser {
                                 continueAsAtom();
                                 break;
                             }
-                            let error = new Error(`Unexpected sequence separator , at position ${this.pos + i} [E31]`);
-                            error.code = 'ParserError31';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected sequence separator , at position ${this.pos + i} [E31]`, 'ParserError31', this.pos + i, chr);
                         }
                         if (tokenLast === '*' && tokenPrev !== ':') {
-                            let error = new Error(`Unexpected sequence separator , at position ${this.pos + i} [E32]`);
-                            error.code = 'ParserError32';
-                            error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                            throw error;
+                            throw this.parserError(`Unexpected sequence separator , at position ${this.pos + i} [E32]`, 'ParserError32', this.pos + i, chr);
                         }
                     }
                     else if (!RE_SINGLE_DIGIT.test(chr)) {
@@ -750,16 +696,10 @@ export class TokenParser {
                             continueAsAtom();
                             break;
                         }
-                        let error = new Error(`Unexpected char at position ${this.pos + i} [E33: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError33';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected char at position ${this.pos + i} [E33: ${JSON.stringify(chr)}]`, 'ParserError33', this.pos + i, chr);
                     }
                     if (RE_SINGLE_DIGIT.test(chr) && tokenLast === '*') {
-                        let error = new Error(`Unexpected number at position ${this.pos + i} [E34: ${JSON.stringify(chr)}]`);
-                        error.code = 'ParserError34';
-                        error.parserContext = { ...boundedInput(this.str), pos: this.pos + i, chr };
-                        throw error;
+                        throw this.parserError(`Unexpected number at position ${this.pos + i} [E34: ${JSON.stringify(chr)}]`, 'ParserError34', this.pos + i, chr);
                     }
                     appendToToken(chr);
                     break;

package/dist/esm/imap-flow.d.ts

@@ -426,7 +426,7 @@ export declare class ImapFlow extends EventEmitter {
      * Appends a new message to a mailbox
      *
      * @param path Mailbox path to upload the message to (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
-     * @param content RFC822 formatted email message
+     * @param content RFC822 formatted email message, as a Buffer, Uint8Array or string
      * @param flags an array of flags to be set for the uploaded message
      * @param idate internal date to be set for the message
      * @returns info about uploaded message
@@ -434,7 +434,7 @@ export declare class ImapFlow extends EventEmitter {
      * @example
      * await client.append('INBOX', rawMessageBuffer, ['\\Seen'], new Date(2000, 1, 1));
      */
-    append(path: string | string[], content: string | Buffer, flags?: string[] | undefined, idate?: Date | string | undefined): Promise<AppendResponseObject | false>;
+    append(path: string | string[], content: string | Buffer | Uint8Array, flags?: string[] | undefined, idate?: Date | string | undefined): Promise<AppendResponseObject | false>;
     /**
      * Copies messages from current mailbox to destination mailbox
      *
@@ -562,7 +562,8 @@ export declare class ImapFlow extends EventEmitter {
      * // download body part nr '1.2' from latest message
      * let download = await client.download('*', '1.2');
      * if (download.content) {
-     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     *     // pipeline() rejects when the download fails, a plain .pipe() would not report it
+     *     await stream.promises.pipeline(download.content, fs.createWriteStream(download.meta.filename));
      * }
      */
     download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject | DownloadNotFound>;