imapflow 2.0.8 → 2.1.0

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.0.8";
+exports.version = "2.1.0";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/tools.d.ts

@@ -1,6 +1,6 @@
 import type { Transform } from 'node:stream';
 import type { ImapFlow } from './imap-flow.js';
-import type { ConnectionErrorSite, ImapFlowError } from './errors.js';
+import { type ConnectionErrorSite, type ImapFlowError } from './errors.js';
 import type { ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 import type { FetchMessageObject, ListResponse, ListTreeResponse, MailboxObject, MessageEnvelopeObject, MessageStructureObject, ImapFlowEvents, StatusQuery } from './types.js';
 export { AuthenticationFailure } from './errors.js';

package/dist/cjs/tools.js

@@ -58,11 +58,12 @@ const imap_handler_js_1 = require("./handler/imap-handler.js");
 const node_crypto_1 = require("node:crypto");
 const jp_decoder_js_1 = require("./jp-decoder.js");
 const iconv_lite_1 = __importDefault(require("iconv-lite"));
-var errors_js_1 = require("./errors.js");
-Object.defineProperty(exports, "AuthenticationFailure", { enumerable: true, get: function () { return errors_js_1.AuthenticationFailure; } });
+const errors_js_1 = require("./errors.js");
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "AuthenticationFailure", { enumerable: true, get: function () { return errors_js_2.AuthenticationFailure; } });
 const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
 // Error codes that only mean the connection is no longer usable. See logConnectionError().
-const CONNECTION_GONE_CODES = new Set(['NoConnection', 'EConnectionClosed', 'StateLogout']);
+const CONNECTION_GONE_CODES = new Set([errors_js_1.ImapFlowErrorCode.NoConnection, errors_js_1.ImapFlowErrorCode.EConnectionClosed, errors_js_1.ImapFlowErrorCode.StateLogout]);
 // Upper bound for expanding server-supplied sequence ranges (see expandRange). 2^24
 // entries in total is far beyond any legitimate mailbox while keeping the worst-case
 // expansion of a hostile range set bounded.
@@ -1147,7 +1148,7 @@ function parseBodystructure(entry) {
             curNode.type = 'multipart/' + ((node[i++] || {}).value || '').toString().toLowerCase();
             // extension data (not available for BODY requests)
             // body parameter parenthesized list
-            if (i < node.length - 1) {
+            if (i < node.length) {
                 if (node[i]) {
                     curNode.parameters = getStructuredParams(node[i]);
                 }
@@ -1229,7 +1230,7 @@ function parseBodystructure(entry) {
             }
             // extension data (not available for BODY requests)
             // md5
-            if (i < node.length - 1) {
+            if (i < node.length) {
                 if (node[i]) {
                     curNode.md5 = (node[i].value || '').toString().toLowerCase();
                 }
@@ -1239,7 +1240,7 @@ function parseBodystructure(entry) {
         // the following are shared extension values (for both multipart and non-multipart parts)
         // not available for BODY requests
         // body disposition
-        if (i < node.length - 1) {
+        if (i < node.length) {
             let disposition = node[i];
             if (Array.isArray(disposition) && disposition.length) {
                 curNode.disposition = ((disposition[0] && disposition[0].value) || '').toString().toLowerCase();
@@ -1250,7 +1251,7 @@ function parseBodystructure(entry) {
             i++;
         }
         // body language
-        if (i < node.length - 1) {
+        if (i < node.length) {
             if (node[i]) {
                 /* c8 ignore next */ // node[i] is truthy inside this guard, so the [] fallback is unreachable
                 curNode.language = [].concat(node[i] || []).map(val => ((val && val.value) || '').toString().toLowerCase());
@@ -1260,7 +1261,7 @@ function parseBodystructure(entry) {
         // body location
         // NB! defined as a "string list" in RFC3501 but replaced in errata document with "string"
         // Errata: http://www.rfc-editor.org/errata_search.php?rfc=3501
-        if (i < node.length - 1) {
+        if (i < node.length) {
             if (node[i]) {
                 curNode.location = (node[i].value || '').toString();
             }

package/dist/esm/commands/list.js

@@ -444,23 +444,27 @@ export default async function list(connection, reference, mailbox, options) {
                 connection.log.warn({ msg: 'Failed to request subscription info', err, cid: connection.id });
             }
         }
-        // Resolve special-use conflicts: for each type, pick the best candidate
-        // based on source priority (user > extension > name), then alphabetically.
-        // Only the winning entry gets the specialUse property set.
-        for (let type of Object.keys(specialUseMatches)) {
-            let sortedEntries = specialUseMatches[type].sort((a, b) => {
-                let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
-                let bSource = SOURCE_SORT_ORDER.indexOf(b.source);
-                if (aSource === bSource) {
-                    return a.entry.path.localeCompare(b.entry.path);
-                }
-                return aSource - bSource;
-            });
-            if (!sortedEntries[0].entry.specialUse) {
-                let source = sortedEntries[0].source;
-                sortedEntries[0].entry.specialUse = type;
-                sortedEntries[0].entry.specialUseSource = PUBLIC_SOURCE[source] || source;
+        // Resolve special-use conflicts. Each type goes to one mailbox and each mailbox gets
+        // at most one type. Candidates are taken in priority order across all types (user >
+        // extension > name, then alphabetically), so a mailbox claimed by a stronger match
+        // leaves its other type to that type's next candidate instead of to nobody.
+        let candidates = Object.entries(specialUseMatches).flatMap(([type, matches]) => matches.map(match => ({ type, ...match })));
+        candidates.sort((a, b) => {
+            let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
+            let bSource = SOURCE_SORT_ORDER.indexOf(b.source);
+            if (aSource === bSource) {
+                return a.entry.path.localeCompare(b.entry.path);
+            }
+            return aSource - bSource;
+        });
+        let assignedTypes = new Set();
+        for (let { type, entry, source } of candidates) {
+            if (assignedTypes.has(type) || entry.specialUse) {
+                continue;
             }
+            entry.specialUse = type;
+            entry.specialUseSource = PUBLIC_SOURCE[source] || source;
+            assignedTypes.add(type);
         }
         // No source answered, so "not subscribed" was never actually reported for any of
         // these folders - the state is unknown, not false. Reporting the whole listing as

package/dist/esm/commands/select.js

@@ -92,12 +92,16 @@ export default async function select(connection, pathInput, options) {
         // QRESYNC (RFC 7162): allows efficient mailbox resynchronization by sending
         // the last known UIDVALIDITY and HIGHESTMODSEQ. Server responds with only
         // the changes (new flags, expunged UIDs) since that point.
+        // The caller may pass UIDVALIDITY as a bigint, a number or a string. It is parsed once,
+        // so the value that is sent is also the one checked against the server's below, and a
+        // value that is not a plain decimal skips QRESYNC instead of reaching the server.
+        let uidValidity = options.uidValidity !== undefined ? parseBigIntValue(String(options.uidValidity)) : false;
         let extraArgs = [];
-        if (connection.enabled.has('QRESYNC') && options.changedSince && options.uidValidity) {
+        if (connection.enabled.has('QRESYNC') && options.changedSince && uidValidity) {
             extraArgs.push([
                 { type: 'ATOM', value: 'QRESYNC' },
                 [
-                    { type: 'ATOM', value: options.uidValidity?.toString() },
+                    { type: 'ATOM', value: uidValidity.toString() },
                     { type: 'ATOM', value: options.changedSince.toString() }
                 ]
             ]);
@@ -202,7 +206,7 @@ export default async function select(connection, pathInput, options) {
         // QRESYNC results are only valid if UIDVALIDITY matches, HIGHESTMODSEQ is
         // present, and the mailbox supports mod-sequences. If any condition fails,
         // the client cannot trust the incremental updates and must do a full resync.
-        if (map.qresync && (options.uidValidity !== map.uidValidity || !map.highestModseq || map.noModseq)) {
+        if (map.qresync && (uidValidity !== map.uidValidity || !map.highestModseq || map.noModseq)) {
             map.qresync = false;
         }
         // Transition mailbox state: save previous mailbox reference, temporarily

package/dist/esm/errors.d.ts

@@ -1,11 +1,58 @@
 import type { ImapResponse } from './handler/types.js';
+/**
+ * The `code` values ImapFlow sets on the errors it raises, so they can be matched without
+ * string literals: `if (err.code === ImapFlowErrorCode.NoConnection)`.
+ *
+ * Parser failures use `ParserError` followed by a number (`ParserError11`) and are not listed
+ * one by one, test them with `err.code?.startsWith('ParserError')`. Errors from the socket, TLS
+ * or DNS layer pass through with Node's own code (`ECONNREFUSED`, `ENOTFOUND`, ...).
+ */
+export declare const ImapFlowErrorCode: {
+    readonly NoConnection: "NoConnection";
+    readonly EConnectionClosed: "EConnectionClosed";
+    readonly StateLogout: "StateLogout";
+    readonly ClosedAfterConnectText: "ClosedAfterConnectText";
+    readonly ClosedAfterConnectTLS: "ClosedAfterConnectTLS";
+    readonly CONNECT_TIMEOUT: "CONNECT_TIMEOUT";
+    readonly GREETING_TIMEOUT: "GREETING_TIMEOUT";
+    readonly UPGRADE_TIMEOUT: "UPGRADE_TIMEOUT";
+    readonly ETIMEOUT: "ETIMEOUT";
+    readonly LockTimeout: "LockTimeout";
+    readonly ETHROTTLE: "ETHROTTLE";
+    readonly UnexpectedTag: "UnexpectedTag";
+    readonly InvalidResponse: "InvalidResponse";
+    readonly ResponseProcessingFailed: "ResponseProcessingFailed";
+    readonly STARTTLS_INJECTION: "STARTTLS_INJECTION";
+    readonly COMPRESS_TRAILING_DATA: "COMPRESS_TRAILING_DATA";
+    readonly PollFailed: "PollFailed";
+    readonly NotFound: "NotFound";
+    readonly MissingServerExtension: "MissingServerExtension";
+    readonly ParserError: "ParserError";
+    readonly ParserErrorExchange: "ParserErrorExchange";
+    readonly MAX_IMAP_NESTING_REACHED: "MAX_IMAP_NESTING_REACHED";
+    readonly LineTooLarge: "LineTooLarge";
+    readonly LiteralTooLarge: "LiteralTooLarge";
+    readonly ResponseTooLarge: "ResponseTooLarge";
+    readonly InvalidStringValue: "InvalidStringValue";
+    readonly InvalidTokenValue: "InvalidTokenValue";
+    readonly InvalidTextValue: "InvalidTextValue";
+    readonly InvalidSequenceSet: "InvalidSequenceSet";
+    readonly DownloadOverflow: "DownloadOverflow";
+    readonly DownloadIncomplete: "DownloadIncomplete";
+    readonly ProxyError: "ProxyError";
+    readonly EPROXY: "EPROXY";
+    readonly UnsupportedProxyAddress: "UnsupportedProxyAddress";
+    readonly ERR_INVALID_URL: "ERR_INVALID_URL";
+};
+/** One of the {@link ImapFlowErrorCode} values */
+export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];
 /**
  * An Error raised by ImapFlow, with the extra properties the library attaches to describe
  * the failure. Every property is optional: which ones are present depends on where the
  * error came from.
  */
 export interface ImapFlowError extends Error {
-    /** Error code, e.g. 'NoConnection', 'ETIMEOUT', 'LockTimeout' or a parser error code */
+    /** Error code, one of {@link ImapFlowErrorCode}, a parser error code or a code from Node */
     code?: string | undefined;
     /** Connection id the error belongs to */
     cid?: string | undefined;

package/dist/esm/errors.js

@@ -1,3 +1,55 @@
+/**
+ * The `code` values ImapFlow sets on the errors it raises, so they can be matched without
+ * string literals: `if (err.code === ImapFlowErrorCode.NoConnection)`.
+ *
+ * Parser failures use `ParserError` followed by a number (`ParserError11`) and are not listed
+ * one by one, test them with `err.code?.startsWith('ParserError')`. Errors from the socket, TLS
+ * or DNS layer pass through with Node's own code (`ECONNREFUSED`, `ENOTFOUND`, ...).
+ */
+export const ImapFlowErrorCode = {
+    // the connection is gone, the command was not (or can no longer be) completed
+    NoConnection: 'NoConnection',
+    EConnectionClosed: 'EConnectionClosed',
+    StateLogout: 'StateLogout',
+    ClosedAfterConnectText: 'ClosedAfterConnectText',
+    ClosedAfterConnectTLS: 'ClosedAfterConnectTLS',
+    // timeouts
+    CONNECT_TIMEOUT: 'CONNECT_TIMEOUT',
+    GREETING_TIMEOUT: 'GREETING_TIMEOUT',
+    UPGRADE_TIMEOUT: 'UPGRADE_TIMEOUT',
+    ETIMEOUT: 'ETIMEOUT',
+    LockTimeout: 'LockTimeout',
+    // the server
+    ETHROTTLE: 'ETHROTTLE',
+    UnexpectedTag: 'UnexpectedTag',
+    InvalidResponse: 'InvalidResponse',
+    ResponseProcessingFailed: 'ResponseProcessingFailed',
+    STARTTLS_INJECTION: 'STARTTLS_INJECTION',
+    COMPRESS_TRAILING_DATA: 'COMPRESS_TRAILING_DATA',
+    PollFailed: 'PollFailed',
+    NotFound: 'NotFound',
+    MissingServerExtension: 'MissingServerExtension',
+    // response parsing and size limits
+    ParserError: 'ParserError',
+    ParserErrorExchange: 'ParserErrorExchange',
+    MAX_IMAP_NESTING_REACHED: 'MAX_IMAP_NESTING_REACHED',
+    LineTooLarge: 'LineTooLarge',
+    LiteralTooLarge: 'LiteralTooLarge',
+    ResponseTooLarge: 'ResponseTooLarge',
+    // invalid values in a command
+    InvalidStringValue: 'InvalidStringValue',
+    InvalidTokenValue: 'InvalidTokenValue',
+    InvalidTextValue: 'InvalidTextValue',
+    InvalidSequenceSet: 'InvalidSequenceSet',
+    // download()
+    DownloadOverflow: 'DownloadOverflow',
+    DownloadIncomplete: 'DownloadIncomplete',
+    // proxy connections
+    ProxyError: 'ProxyError',
+    EPROXY: 'EPROXY',
+    UnsupportedProxyAddress: 'UnsupportedProxyAddress',
+    ERR_INVALID_URL: 'ERR_INVALID_URL'
+};
 /**
  * Error subclass thrown when IMAP authentication fails.
  */

package/dist/esm/handler/imap-stream.d.ts

@@ -145,13 +145,24 @@ export declare class ImapStream extends Transform {
      * pushed downstream as a readable object.
      *
      * @param chunk - The raw data chunk to process.
-     * @param startPos - The byte offset within the chunk to start processing from.
      */
-    processInputChunk(chunk: Buffer, startPos?: number | undefined): Promise<void>;
+    processInputChunk(chunk: Buffer): Promise<void>;
+    /**
+     * Processes the chunk from `startPos` until the parser state changes or the chunk ends.
+     *
+     * @returns The offset to continue from after a state switch, or `null` when done with the chunk.
+     */
+    processChunkSegment(chunk: Buffer, startPos: number): Promise<number | null>;
     /**
      * 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.
+     *
+     * The `processingInput` guard is cleared in the same synchronous step that finds the queue
+     * empty. Clearing it later (in a promise handler) leaves a gap of a few microtasks where a
+     * chunk delivered by the writable side is queued but no loop is started for it, so its
+     * transform callback is never called and the socket is never read again. Workers deliver
+     * the next chunk inside that gap.
      */
     processInput(): Promise<void>;
     /**

package/dist/esm/handler/imap-stream.js

@@ -217,12 +217,23 @@ export class ImapStream extends Transform {
      * pushed downstream as a readable object.
      *
      * @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;
+    async processInputChunk(chunk) {
+        // Every state switch hands back the offset to resume from instead of recursing, so a
+        // chunk packed with thousands of small literals can not exhaust the call stack
+        let nextPos = 0;
+        while (nextPos !== null) {
+            nextPos = await this.processChunkSegment(chunk, nextPos);
+        }
+    }
+    /**
+     * Processes the chunk from `startPos` until the parser state changes or the chunk ends.
+     *
+     * @returns The offset to continue from after a state switch, or `null` when done with the chunk.
+     */
+    async processChunkSegment(chunk, startPos) {
         if (this.destroyed || startPos >= chunk.length) {
-            return;
+            return null;
         }
         switch (this.state) {
             case LINE: {
@@ -234,7 +245,7 @@ export class ImapStream extends Transform {
                         // TCP chunk boundaries happen to fall.
                         let segment = chunk.subarray(lineStart, i + 1);
                         if (!this.checkLineLength(this.lineBytes + segment.length)) {
-                            return;
+                            return null;
                         }
                         this.lineBuffer.push(segment);
                         lineStart = i + 1;
@@ -246,18 +257,18 @@ export class ImapStream extends Transform {
                         // would otherwise be emitted as part of the rejected command.
                         let isLiteralMarker = this.checkLiteralMarker(line);
                         if (this.destroyed) {
-                            return;
+                            return null;
                         }
                         // 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;
+                            return null;
                         }
                         this.inputBuffer.push(line);
                         if (isLiteralMarker) {
                             // switch into literal mode and start over
-                            return await this.processInputChunk(chunk, lineStart);
+                            return lineStart;
                         }
                         // reached end of command input, emit it
                         let payload = this.inputBuffer.length === 1 ? this.inputBuffer[0] : Buffer.concat(this.inputBuffer);
@@ -291,7 +302,7 @@ export class ImapStream extends Transform {
                                 });
                                 this.pendingPush = null;
                                 if (this.destroyed) {
-                                    return;
+                                    return null;
                                 }
                             }
                         }
@@ -307,7 +318,7 @@ export class ImapStream extends Transform {
                     // while a server streams a line that never terminates - only the much
                     // larger line cap would hold it back.
                     if (!this.checkLineLength(this.lineBytes + tail.length) || !this.checkResponseSize(this.lineBytes + tail.length, true)) {
-                        return;
+                        return null;
                     }
                     this.lineBytes += tail.length;
                     this.lineBuffer.push(tail);
@@ -325,33 +336,45 @@ export class ImapStream extends Transform {
                     this.literalBuffer = [];
                     this.state = LINE;
                     if (remainingInChunk > bytesToRead) {
-                        return await this.processInputChunk(chunk, startPos + bytesToRead);
+                        return startPos + bytesToRead;
                     }
                 }
                 break;
             }
         }
+        return null;
     }
     /**
      * 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.
+     *
+     * The `processingInput` guard is cleared in the same synchronous step that finds the queue
+     * empty. Clearing it later (in a promise handler) leaves a gap of a few microtasks where a
+     * chunk delivered by the writable side is queued but no loop is started for it, so its
+     * transform callback is never called and the socket is never read again. Workers deliver
+     * the next chunk inside that gap.
      */
     async processInput() {
-        let data;
-        let processedCount = 0;
-        while (!this.destroyed && (data = this.inputQueue.shift())) {
-            this.activeInput = data;
-            await this.processInputChunk(data.chunk);
-            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) {
-                await new Promise(resolve => setImmediate(resolve));
+        try {
+            let data;
+            let processedCount = 0;
+            while (!this.destroyed && (data = this.inputQueue.shift())) {
+                this.activeInput = data;
+                await this.processInputChunk(data.chunk);
+                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) {
+                    await new Promise(resolve => setImmediate(resolve));
+                }
             }
         }
+        finally {
+            this.processingInput = false;
+        }
     }
     /**
      * Transform stream implementation. Receives raw data chunks from the writable side,
@@ -391,9 +414,7 @@ export class ImapStream extends Transform {
         this.inputQueue.push({ chunk, next });
         if (!this.processingInput) {
             this.processingInput = true;
-            this.processInput()
-                .catch(err => this.failStream(err))
-                .finally(() => (this.processingInput = false));
+            this.processInput().catch(err => this.failStream(err));
         }
     }
     /**

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

@@ -321,15 +321,21 @@ export class TokenParser {
                                     this.currentNode = this.createNode(this.currentNode, this.pos + i + 10);
                                     // just call this an ATOM, even though IMAPURL might be more correct
                                     this.currentNode.type = 'ATOM';
-                                    // jump i to the ']'
-                                    i = this.str.indexOf(']', i + 10);
-                                    if (i < 0) {
-                                        // Malformed REFERRAL with no closing ']'. Consume the rest
-                                        // of the string (there is no ']' to exclude) instead of
-                                        // computing a negative-index substring, which would yield
-                                        // garbage.
-                                        i = this.str.length;
+                                    // jump i to the ']' that closes the section. The URL itself can
+                                    // hold a bracketed IPv6 host (imap://[::1]/INBOX), so brackets
+                                    // opened inside the URL are matched before the closing one.
+                                    let depth = 0;
+                                    for (i = i + 10; i < this.str.length; i++) {
+                                        let urlChr = this.str.charAt(i);
+                                        if (urlChr === '[') {
+                                            depth++;
+                                        }
+                                        else if (urlChr === ']' && depth-- === 0) {
+                                            break;
+                                        }
                                     }
+                                    // A malformed REFERRAL with no closing ']' leaves i at the end of
+                                    // the string, so the URL takes the rest of it.
                                     this.currentNode.endPos = this.pos + i - 1;
                                     this.currentNode.value = this.str.substring(this.currentNode.startPos - this.pos, this.currentNode.endPos - this.pos + 1);
                                     this.currentNode = this.currentNode.parentNode;

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

@@ -9,7 +9,7 @@ import { AuthenticationFailure } from './errors.js';
 import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadNotFound, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
-export { AuthenticationFailure } from './errors.js';
+export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
 export type { ImapAttribute, ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 declare const stateValues: {
     readonly NOT_AUTHENTICATED: 1;
@@ -61,6 +61,17 @@ export interface ImapFlow {
     prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
     emit<K extends keyof ImapFlowEvents>(event: K, ...args: ImapFlowEvents[K]): boolean;
     emit(event: string | symbol, ...args: any[]): boolean;
+    /**
+     * Logs out and closes the connection when the scope of an `await using` declaration ends.
+     * Never throws, the connection is closed whether LOGOUT succeeds or not. Only present on
+     * runtimes that define `Symbol.asyncDispose` (Node.js 20.4 and newer).
+     *
+     * @example
+     * await using client = new ImapFlow({...});
+     * await client.connect();
+     * // client.logout() runs automatically when the scope exits, even on a throw
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * IMAP client class for accessing IMAP mailboxes
@@ -592,7 +603,8 @@ export declare class ImapFlow extends EventEmitter {
     getMailboxLock(path: string | string[], options?: MailboxLockOptions | undefined): Promise<MailboxLockObject>;
     /**
      * Detaches sockets from the IMAP pipeline. Useful for upgrading the connection
-     * (e.g., STARTTLS) or transferring socket ownership.
+     * (e.g., STARTTLS) or transferring socket ownership. Call it while the connection is not
+     * idling: an IDLE in progress is not broken first, so the server still expects `DONE`.
      *
      * @returns Socket objects: `readSocket` is the read socket (inflated socket if compression is enabled, raw socket otherwise),
      *   `writeSocket` the write socket and `socket` the raw underlying socket (same as readSocket/writeSocket when compression is disabled)
@@ -603,81 +615,6 @@ export declare class ImapFlow extends EventEmitter {
         socket: ImapSocket;
     };
 }
-/**
- * Connection close event. **NB!** ImapFlow does not handle reconnects automatically.
- * So whenever a 'close' event occurs you must create a new connection yourself.
- *
- * @event ImapFlow#close
- */
-/**
- * Error event. In most cases getting an error event also means that connection is closed
- * and pending operations should return with a failure.
- *
- * @event ImapFlow#error
- * @example
- * client.on('error', err=>{
- *     console.log(`Error occurred: ${err.message}`);
- * });
- */
-/**
- * Message count in currently opened mailbox changed
- *
- * @event ImapFlow#exists
- * @example
- * client.on('exists', data=>{
- *     console.log(`Message count in "${data.path}" is ${data.count}`);
- * });
- */
-/**
- * Deleted message sequence number in currently opened mailbox. One event is fired for every deleted email.
- *
- * @event ImapFlow#expunge
- * @example
- * client.on('expunge', data=>{
- *     console.log(`Message #${data.seq} was deleted from "${data.path}"`);
- * });
- */
-/**
- * Flags were updated for a message. Not all servers fire this event.
- *
- * @event ImapFlow#flags
- * @example
- * client.on('flags', data=>{
- *     console.log(`Flag set for #${data.seq} is now "${Array.from(data.flags).join(', ')}"`);
- * });
- */
-/**
- * Mailbox was opened
- *
- * @event ImapFlow#mailboxOpen
- * @example
- * client.on('mailboxOpen', mailbox => {
- *     console.log(`Mailbox ${mailbox.path} was opened`);
- * });
- */
-/**
- * Mailbox was closed
- *
- * Emitted both when a selected mailbox is closed explicitly, by `mailboxClose()` or by
- * selecting a different mailbox, and when the connection itself goes away while a mailbox
- * was still selected, whether through a clean logout or a lost transport. The transition is
- * reported once per selected mailbox, before the `close` event.
- *
- * @event ImapFlow#mailboxClose
- * @example
- * client.on('mailboxClose', mailbox => {
- *     console.log(`Mailbox ${mailbox.path} was closed`);
- * });
- */
-/**
- * Log event if `emitLogs=true`
- *
- * @event ImapFlow#log
- * @example
- * client.on('log', entry => {
- *     console.log(`${entry.cid} ${entry.msg}`);
- * });
- */
 declare const imapflow: {
     ImapFlow: typeof ImapFlow;
     AuthenticationFailure: typeof AuthenticationFailure;