imapflow 2.0.8 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2.1.0](https://github.com/postalsys/imapflow/compare/v2.0.8...v2.1.0) (2026-09-27)
+
+
+### Features
+
+* export ImapFlowErrorCode with the error codes the library sets ([50c909c](https://github.com/postalsys/imapflow/commit/50c909c30a8cda4731c397f1a77c3bf3d2d17102))
+* support `await using` through Symbol.asyncDispose ([baadd4b](https://github.com/postalsys/imapflow/commit/baadd4bd73a8d9c46aab2966beb55698a42e71b2))
+
+
+### Bug Fixes
+
+* accept a number or string uidValidity for QRESYNC ([e87d0c2](https://github.com/postalsys/imapflow/commit/e87d0c216e48e2dda23d94a7c942682ec28258ca))
+* give a special-use type to its next candidate when the best is taken ([5b0d357](https://github.com/postalsys/imapflow/commit/5b0d357ec1f30cd7b43a7ad06e3a22a9ac244bad))
+* keep a bracketed IPv6 host in a REFERRAL URL ([1e90b70](https://github.com/postalsys/imapflow/commit/1e90b706f72c54e4d1397e11e0c0b2aabc2f2549))
+* keep auto-IDLE off a socket handed over by unbind() ([a47b3ae](https://github.com/postalsys/imapflow/commit/a47b3ae99e5e1e00fd8b804a8072aeccc34c6a5a))
+* parse a chunk of many literals in a loop instead of recursing ([db4c704](https://github.com/postalsys/imapflow/commit/db4c704291054cff5a9d87386a093d113ea69fc3))
+* process a chunk that arrives while the input loop is winding down ([c73f3ea](https://github.com/postalsys/imapflow/commit/c73f3ea18f5557abf91414a0faf98da7150e3f4f)), closes [#408](https://github.com/postalsys/imapflow/issues/408)
+* read the last extension field of a BODYSTRUCTURE part ([d5cf6c0](https://github.com/postalsys/imapflow/commit/d5cf6c0282cf35df2de7eb153fed24ecd09448d3))
+* reject connect() right away on a BYE greeting ([dc5d80e](https://github.com/postalsys/imapflow/commit/dc5d80e6f6efdebe92f461e23f41dc64bce6c4aa))
+
 ## [2.0.8](https://github.com/postalsys/imapflow/compare/v2.0.7...v2.0.8) (2026-09-27)
 
 

package/dist/cjs/commands/list.js

@@ -447,23 +447,27 @@ 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/cjs/commands/select.js

@@ -95,12 +95,16 @@ 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 ? (0, tools_js_1.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() }
                 ]
             ]);
@@ -205,7 +209,7 @@ 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/cjs/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/cjs/errors.js

@@ -1,6 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthenticationFailure = void 0;
+exports.AuthenticationFailure = exports.ImapFlowErrorCode = void 0;
+/**
+ * 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`, ...).
+ */
+exports.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/cjs/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/cjs/handler/imap-stream.js

@@ -223,12 +223,23 @@ class ImapStream extends node_stream_1.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: {
@@ -240,7 +251,7 @@ class ImapStream extends node_stream_1.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;
@@ -252,18 +263,18 @@ class ImapStream extends node_stream_1.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);
@@ -297,7 +308,7 @@ class ImapStream extends node_stream_1.Transform {
                                 });
                                 this.pendingPush = null;
                                 if (this.destroyed) {
-                                    return;
+                                    return null;
                                 }
                             }
                         }
@@ -313,7 +324,7 @@ class ImapStream extends node_stream_1.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);
@@ -331,33 +342,45 @@ class ImapStream extends node_stream_1.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,
@@ -397,9 +420,7 @@ class ImapStream extends node_stream_1.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/cjs/handler/token-parser.js

@@ -327,15 +327,21 @@ 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/cjs/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;

package/dist/cjs/imap-flow.js

@@ -39,7 +39,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ImapFlow = exports.AuthenticationFailure = void 0;
+exports.ImapFlow = exports.ImapFlowErrorCode = exports.AuthenticationFailure = void 0;
 const node_tls_1 = __importDefault(require("node:tls"));
 const node_net_1 = __importDefault(require("node:net"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
@@ -58,6 +58,7 @@ const imap_commands_js_1 = __importDefault(require("./imap-commands.js"));
 const tools_js_1 = require("./tools.js");
 var errors_js_2 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationFailure", { enumerable: true, get: function () { return errors_js_2.AuthenticationFailure; } });
+Object.defineProperty(exports, "ImapFlowErrorCode", { enumerable: true, get: function () { return errors_js_2.ImapFlowErrorCode; } });
 const GREETING_TIMEOUT = 16 * 1000;
 const UPGRADE_TIMEOUT = 10 * 1000;
 const SOCKET_TIMEOUT = 5 * 60 * 1000;
@@ -1601,6 +1602,7 @@ class ImapFlow extends node_events_1.EventEmitter {
     /** @internal */
     beginSession(onUnhandledError) {
         (0, tools_js_1.clearTimer)(this.greetingTimeout);
+        this.greetingReceived = true;
         this.untaggedHandlers.OK = null;
         this.untaggedHandlers.PREAUTH = null;
         if (this.isClosed) {
@@ -1660,6 +1662,12 @@ class ImapFlow extends node_events_1.EventEmitter {
         this.byeReason = reason || 'Server closed connection';
         this.untaggedHandlers.BYE = null;
         this.state = this.states.LOGOUT;
+        // A BYE greeting rejects the connection outright. Do not wait for the server to close
+        // the socket: one that keeps it open would leave connect() pending until the greeting
+        // timeout.
+        if (!this.greetingReceived) {
+            this.closeAfter();
+        }
     }
     // Drops every capability-derived field together - the counterpart of
     // updateCapabilitiesFromRaw() below, which sets them together. rawCapabilities is
@@ -1892,7 +1900,7 @@ class ImapFlow extends node_events_1.EventEmitter {
     /** @internal */
     autoidle() {
         (0, tools_js_1.clearTimer)(this.idleStartTimer);
-        if (this.options.disableAutoIdle || this.state !== this.states.SELECTED) {
+        if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
         }
         if (this.connectionBusy()) {
@@ -1904,7 +1912,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             // missed clearTimeout would inject IDLE between a caller's own commands. Declining
             // postpones rather than cancels: whatever made the connection busy calls autoidle()
             // again when it finishes.
-            if (this.state !== this.states.SELECTED || this.connectionBusy()) {
+            if (!this.usable || this.state !== this.states.SELECTED || this.connectionBusy()) {
                 return;
             }
             this.idle().catch(err => (0, tools_js_1.logConnectionError)(this, 'Auto-IDLE failed', err));
@@ -3389,7 +3397,8 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /**
      * 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)
@@ -3404,6 +3413,11 @@ class ImapFlow extends node_events_1.EventEmitter {
         // compression is active, the PassThrough writeSocket - so the connection
         // is fully released to the caller.
         this.clearSocketHandlers();
+        // The socket now belongs to the caller. Marking the client unusable keeps
+        // auto-IDLE (armed now, or re-armed by a lock release or a finished download)
+        // and a later dispose from writing IDLE or LOGOUT onto it.
+        this.usable = false;
+        (0, tools_js_1.clearTimer)(this.idleStartTimer);
         const readSocket = this._inflate || socket;
         const writeSocket = this.writeSocket || socket;
         // Defense-in-depth: when compression is active the raw socket is orphaned
@@ -3502,6 +3516,23 @@ exports.ImapFlow = ImapFlow;
  *     console.log(`${entry.cid} ${entry.msg}`);
  * });
  */
+// Installed outside the class body: a computed `[Symbol.asyncDispose]` key would turn into a
+// method named "undefined" on Node.js 20.0-20.3, which predate the symbol
+if (typeof Symbol.asyncDispose === 'symbol') {
+    ImapFlow.prototype[Symbol.asyncDispose] = async function () {
+        if (this.usable) {
+            try {
+                await this.logout();
+            }
+            catch (err) {
+                (0, tools_js_1.logConnectionError)(this, 'LOGOUT failed while disposing', err);
+            }
+        }
+        // logout() already closes the connection; close() is idempotent and covers a client
+        // that never connected or whose logout was skipped
+        this.close();
+    };
+}
 // Both `import { ImapFlow } from 'imapflow'` and `import imapflow from 'imapflow'` work, the
 // latter matching the shape `require('imapflow')` has always had
 const imapflow = { ImapFlow, AuthenticationFailure: errors_js_1.AuthenticationFailure };

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.0.8";
+export declare const version = "2.1.0";
 export declare const homepage = "https://imapflow.com/";