imapflow 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.9.0](https://github.com/postalsys/imapflow/compare/v2.8.0...v2.9.0) (2026-10-22)
+
+
+### Features
+
+* closedByClient tells a close the application asked for from one the server made, and auto-IDLE never waits longer than maxIdleTime ([5339c12](https://github.com/postalsys/imapflow/commit/5339c12895a759621b2e30bbb07521dba7b39929))
+
+
+### Bug Fixes
+
+* logout() marks the close as the application's before the LOGOUT exchange, and closeAfter() is tested ([03602d2](https://github.com/postalsys/imapflow/commit/03602d2afa2dc8e243735ad6ede8403b733ed4b0))
+
+## [2.8.0](https://github.com/postalsys/imapflow/compare/v2.7.0...v2.8.0) (2026-10-21)
+
+
+### Features
+
+* idle({ whenFree: true }) waits for the connection to be free before starting IDLE ([791c24c](https://github.com/postalsys/imapflow/commit/791c24ca607b60585ef619269abb0aa1f400f525))
+
 ## [2.7.0](https://github.com/postalsys/imapflow/compare/v2.6.0...v2.7.0) (2026-10-21)
 
 

package/dist/cjs/commands/compress.js

@@ -45,7 +45,7 @@ async function compress(connection) {
         // STARTTLS guard does (starttls.ts records a flag, upgradeToSTARTTLS decides):
         // only the command module holds the response before its backpressure release,
         // so only it can order teardown ahead of that release.
-        connection.closeAfter();
+        connection.closeConnectionAfter();
         response.next();
         throw error;
     }

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

@@ -4,7 +4,7 @@
 import { EventEmitter } from 'node:events';
 import { PassThrough, type Readable } from 'node:stream';
 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, ImapTransportSocket } from './types.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, IdleOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo, ImapTransportSocket } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
 export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
@@ -157,8 +157,17 @@ export declare class ImapFlow extends EventEmitter {
      * what tells a server dropping an idle session from one dropping a session mid-command
      */
     idlingAtClose: boolean;
+    /**
+     * Whether the application ended the connection (`close()`, `closeAfter()`, `logout()`, disposing
+     * the client), `false` while it is open and when the server, the network or an error ended it.
+     * Tells a session the server dropped from one the application closed, also for an application
+     * that closes a connection only to open a new one
+     */
+    closedByClient: boolean;
     /** Whether log entries are also emitted as 'log' events, see the `emitLogs` option */
     emitLogs: boolean;
+    /** How often IDLE is restarted, in milliseconds (the `maxIdleTime` option), `false` for never */
+    maxIdleTime: number | false;
     /** Hash algorithm for the fallback message id, see `ImapFlowOptions.idHashAlgorithm` */
     idHashAlgorithm: string;
     /** The personal namespace, from the NAMESPACE command */
@@ -378,8 +387,10 @@ export declare class ImapFlow extends EventEmitter {
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
      * Unlike auto-IDLE, a direct call does not wait for the connection to be free: a mailbox lock
-     * holder may idle inside its own lock, and idle() can not tell it from another caller.
+     * holder may idle inside its own lock, and idle() can not tell it from another caller. Code that
+     * holds no lock passes `{ whenFree: true }` to wait for the connection to be free first.
      *
+     * @param options IDLE options
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -387,7 +398,7 @@ export declare class ImapFlow extends EventEmitter {
      *
      * await client.idle();
      */
-    idle(): Promise<boolean | undefined>;
+    idle(options?: IdleOptions | undefined): Promise<boolean | undefined>;
     /**
      * Sets flags for a message or message range
      *

package/dist/cjs/imap-flow.js

@@ -302,7 +302,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         this.context = this.options.context;
         this.connectedAt = null;
         this.lastClientWrite = null;
+        this._idleWaiters = [];
         this.idlingAtClose = false;
+        this.closedByClient = false;
+        this._closePending = false;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
         this.untaggedHandlers = {};
@@ -314,6 +317,11 @@ class ImapFlow extends node_events_1.EventEmitter {
         this.idRequested = false;
         this.maxIdleTime = this.options.maxIdleTime || false;
         this.autoIdleDelay = normalizeAutoIdleDelay(this.options.autoIdleDelay, this.socketTimeout, this.log, this.id);
+        // A server that needs IDLE restarted this often can cut the silence before the first IDLE just
+        // as well: the connection is never left quiet for longer than maxIdleTime
+        if (this.maxIdleTime && this.autoIdleDelay > this.maxIdleTime) {
+            this.autoIdleDelay = this.maxIdleTime;
+        }
         this._lastPollAt = 0;
         this._openDownloads = 0;
         this._recoveryPending = false;
@@ -333,7 +341,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // than emitting an error event to the caller.
         this._streamerErrorHandler = (err) => {
             if (['Z_BUF_ERROR', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'EHOSTUNREACH'].includes(err.code)) {
-                this.closeAfter();
+                this.closeConnectionAfter();
                 return;
             }
             this.log.error({ err, cid: this.id });
@@ -354,7 +362,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // only awaited connect(), as an unhandled 'error' that throws.
         if (this._errorReported) {
             this.log.debug({ msg: 'Suppressed error after the connection already reported one', err, cid: this.id });
-            this.closeAfter();
+            this.closeConnectionAfter();
             return;
         }
         // During a STARTTLS handshake the upgrade owns the single error path (its settle()
@@ -372,7 +380,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 return;
             }
             this.upgrading = false;
-            this.closeAfter();
+            this.closeConnectionAfter();
             return;
         }
         // While the initial connect promise is still pending it owns error reporting:
@@ -383,12 +391,12 @@ class ImapFlow extends node_events_1.EventEmitter {
             this.initialResolve = false;
             this.initialReject = false;
             this._errorReported = true;
-            this.closeAfter();
+            this.closeConnectionAfter();
             reject(err);
             return;
         }
         this._errorReported = true;
-        this.closeAfter();
+        this.closeConnectionAfter();
         this.emit('error', err);
     }
     /** @internal */
@@ -414,7 +422,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         }
         if (this.writeSocket.destroyed) {
             this.log.error({ msg: 'Write socket destroyed', cid: this.id });
-            this.close();
+            this.closeConnection();
             return;
         }
         // Append CRLF only to the final part of a command. When sending literals,
@@ -1264,8 +1272,8 @@ class ImapFlow extends node_events_1.EventEmitter {
                     this.log.error({ err, cid: this.id });
                     this.emitError(err);
                 });
-        this._socketClose = this._socketClose || (() => this.close());
-        this._socketEnd = this._socketEnd || (() => this.close());
+        this._socketClose = this._socketClose || (() => this.closeConnection());
+        this._socketEnd = this._socketEnd || (() => this.closeConnection());
         /**
          * Socket timeout event handler.
          *
@@ -1319,7 +1327,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                             .catch(err => {
                             this.log.warn({ msg: 'Connection recovery failed after timeout', err, cid: this.id });
                             if (!this.isClosed) {
-                                this.close();
+                                this.closeConnection();
                             }
                         })
                             .finally(() => {
@@ -1630,7 +1638,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // is rejected there instead (with a generic TLS error rather than STARTTLS_INJECTION).
         const failSTARTTLSInjection = () => {
             let err = (0, errors_js_1.createImapError)('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack', 'STARTTLS_INJECTION', { tlsFailed: true });
-            this.closeAfter();
+            this.closeConnectionAfter();
             return err;
         };
         // Check 1: the parser saw more input already buffered right after the tagged OK
@@ -1698,7 +1706,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                     // Preserve the original error, marked as a TLS failure so callers can tell
                     // an upgrade failure from an ordinary command failure.
                     err.tlsFailed = true;
-                    this.closeAfter();
+                    this.closeConnectionAfter();
                     return reject(err);
                 }
                 resolve(result);
@@ -1888,7 +1896,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             .catch(err => {
             // The transport goes with the failed attempt: the instance can not be reused, and
             // an open socket would only trip the inactivity watchdog later
-            this.closeAfter();
+            this.closeConnectionAfter();
             if (typeof this.initialReject === 'function') {
                 this.log.error({ err, cid: this.id });
                 (0, tools_js_1.clearTimer)(this.greetingTimeout);
@@ -1938,7 +1946,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // that answers a LOGOUT is the exception: its tagged completion closes the connection.
         const answersLogout = !!this.currentRequest && this.currentRequest.command.toUpperCase() === 'LOGOUT';
         if (!this.greetingReceived || !answersLogout) {
-            this.closeAfter();
+            this.closeConnectionAfter();
         }
     }
     // Drops every capability-derived field together - the counterpart of
@@ -2187,6 +2195,19 @@ class ImapFlow extends node_events_1.EventEmitter {
     connectionBusy() {
         return !!(this.currentLock || this.locks.length || this.currentRequest || this.requestQueue.length || this._openDownloads);
     }
+    // Settles every idle({ whenFree: true }) call waiting for the connection: resolved to re-check
+    // it, or rejected when the connection is gone
+    /** @internal */
+    settleIdleWaiters(err) {
+        for (let { resolve, reject } of this._idleWaiters.splice(0)) {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        }
+    }
     // Timer process-liveness policy: connection establishment and greeting deadlines keep the
     // process alive, because a caller is waiting on connect() to settle. Background timers
     // (auto-IDLE, IDLE restart, fallback polling, throttle back-off, the held-lock diagnostic) are
@@ -2194,6 +2215,9 @@ class ImapFlow extends node_events_1.EventEmitter {
     // explicitly on close().
     /** @internal */
     autoidle() {
+        // every place the connection may have become free calls this, so it is where waiting
+        // idle({ whenFree: true }) calls re-check it, also with auto-IDLE turned off
+        this.settleIdleWaiters();
         (0, tools_js_1.clearTimer)(this.idleStartTimer);
         if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
@@ -2301,7 +2325,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
                 this.log.error({ err, cid: this.id });
-                this.closeAfter();
+                this.closeConnectionAfter();
                 reject(err);
             }, deadline.remaining());
             let onConnect = () => {
@@ -2328,7 +2352,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                             }
                         });
                         this.log.error({ err, cid: this.id });
-                        this.closeAfter();
+                        this.closeConnectionAfter();
                         reject(err);
                     }, this.options.greetingTimeout || GREETING_TIMEOUT);
                     const connected = this.socket;
@@ -2382,7 +2406,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 catch (err) {
                     // refused up front: the connection deadline must not stay armed
                     (0, tools_js_1.clearTimer)(this.connectTimeout);
-                    this.closeAfter();
+                    this.closeConnectionAfter();
                     this.log.error({ err, cid: this.id });
                     reject(err);
                     return;
@@ -2396,7 +2420,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             this._connectErrorHandler = (err) => {
                 (0, tools_js_1.clearTimer)(this.connectTimeout);
                 (0, tools_js_1.clearTimer)(this.greetingTimeout);
-                this.closeAfter();
+                this.closeConnectionAfter();
                 this.log.error({ err, cid: this.id });
                 reject(err);
             };
@@ -2414,6 +2438,9 @@ class ImapFlow extends node_events_1.EventEmitter {
      * await client.logout();
      */
     async logout() {
+        // marked before the exchange: a server may answer with BYE and drop the socket before the
+        // tagged OK, which closes the connection from the socket's side first
+        this.markClosedByClient();
         return await this.run('LOGOUT');
     }
     /**
@@ -2422,7 +2449,21 @@ class ImapFlow extends node_events_1.EventEmitter {
      * caller function to proceed, and run `close()` function afterwards.
      */
     closeAfter() {
-        setImmediate(() => this.close());
+        this.markClosedByClient();
+        this.closeConnectionAfter();
+    }
+    // The deferred close ImapFlow itself starts (a server BYE, an error), which closedByClient leaves alone
+    /** @internal */
+    closeConnectionAfter() {
+        this._closePending = true;
+        setImmediate(() => this.closeConnection());
+    }
+    // The application asked for the close, unless the connection is already closed or closing
+    /** @internal */
+    markClosedByClient() {
+        if (!this.isClosed && !this._closePending) {
+            this.closedByClient = true;
+        }
     }
     // Connection-scoped wrapper around the shared stamping helper; see buildConnectionError().
     /** @internal */
@@ -2458,6 +2499,13 @@ class ImapFlow extends node_events_1.EventEmitter {
      * client.close();
      */
     close() {
+        this.markClosedByClient();
+        this.closeConnection();
+    }
+    // The close itself, for the application's close() and for the closes ImapFlow starts on its own
+    // (the socket ending, a write to a destroyed socket, a failed timeout recovery)
+    /** @internal */
+    closeConnection() {
         try {
             this.closeTimers();
             this.usable = false;
@@ -2501,6 +2549,9 @@ class ImapFlow extends node_events_1.EventEmitter {
             }
             this.closeRequests();
             this.closeLocks();
+            if (this._idleWaiters.length) {
+                this.settleIdleWaiters(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'idleWait', command: 'IDLE' }));
+            }
             this.closeStreams();
             // clear socket handlers
             this.clearSocketHandlers();
@@ -2941,8 +2992,10 @@ class ImapFlow extends node_events_1.EventEmitter {
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
      * Unlike auto-IDLE, a direct call does not wait for the connection to be free: a mailbox lock
-     * holder may idle inside its own lock, and idle() can not tell it from another caller.
+     * holder may idle inside its own lock, and idle() can not tell it from another caller. Code that
+     * holds no lock passes `{ whenFree: true }` to wait for the connection to be free first.
      *
+     * @param options IDLE options
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -2950,7 +3003,13 @@ class ImapFlow extends node_events_1.EventEmitter {
      *
      * await client.idle();
      */
-    async idle() {
+    async idle(options) {
+        // Re-checked on every wake, as another IDLE may have started meanwhile
+        while (options?.whenFree && !this.idling && this.usable && this.connectionBusy()) {
+            await new Promise((resolve, reject) => {
+                this._idleWaiters.push({ resolve, reject });
+            });
+        }
         if (!this.idling) {
             return await this.run('IDLE', this.maxIdleTime);
         }

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

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

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.7.0";
+exports.version = "2.9.0";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/types.d.ts

@@ -745,6 +745,16 @@ export interface MailboxOpenOptions {
     /** QRESYNC (RFC 7162): the UIDVALIDITY known from the previous session, required with `changedSince` */
     uidValidity?: bigint | number | string | undefined;
 }
+export interface IdleOptions {
+    /**
+     * Wait until the connection is free before starting IDLE: no mailbox lock held or queued, no
+     * command running or queued, no download open. Use it from code that does not hold a mailbox
+     * lock, so IDLE does not land between another caller's commands. A lock holder must not set it,
+     * it would wait for its own release. The returned promise rejects with `NoConnection` when the
+     * connection closes while waiting.
+     */
+    whenFree?: boolean | undefined;
+}
 export interface MailboxLockOptions extends MailboxOpenOptions {
     /**
      * Optional timeout in milliseconds to wait for the lock to be granted.

package/dist/esm/commands/compress.js

@@ -42,7 +42,7 @@ export default async function compress(connection) {
         // STARTTLS guard does (starttls.ts records a flag, upgradeToSTARTTLS decides):
         // only the command module holds the response before its backpressure release,
         // so only it can order teardown ahead of that release.
-        connection.closeAfter();
+        connection.closeConnectionAfter();
         response.next();
         throw error;
     }

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

@@ -4,7 +4,7 @@
 import { EventEmitter } from 'node:events';
 import { PassThrough, type Readable } from 'node:stream';
 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, ImapTransportSocket } from './types.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, IdleOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo, ImapTransportSocket } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
 export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
@@ -157,8 +157,17 @@ export declare class ImapFlow extends EventEmitter {
      * what tells a server dropping an idle session from one dropping a session mid-command
      */
     idlingAtClose: boolean;
+    /**
+     * Whether the application ended the connection (`close()`, `closeAfter()`, `logout()`, disposing
+     * the client), `false` while it is open and when the server, the network or an error ended it.
+     * Tells a session the server dropped from one the application closed, also for an application
+     * that closes a connection only to open a new one
+     */
+    closedByClient: boolean;
     /** Whether log entries are also emitted as 'log' events, see the `emitLogs` option */
     emitLogs: boolean;
+    /** How often IDLE is restarted, in milliseconds (the `maxIdleTime` option), `false` for never */
+    maxIdleTime: number | false;
     /** Hash algorithm for the fallback message id, see `ImapFlowOptions.idHashAlgorithm` */
     idHashAlgorithm: string;
     /** The personal namespace, from the NAMESPACE command */
@@ -378,8 +387,10 @@ export declare class ImapFlow extends EventEmitter {
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
      * Unlike auto-IDLE, a direct call does not wait for the connection to be free: a mailbox lock
-     * holder may idle inside its own lock, and idle() can not tell it from another caller.
+     * holder may idle inside its own lock, and idle() can not tell it from another caller. Code that
+     * holds no lock passes `{ whenFree: true }` to wait for the connection to be free first.
      *
+     * @param options IDLE options
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -387,7 +398,7 @@ export declare class ImapFlow extends EventEmitter {
      *
      * await client.idle();
      */
-    idle(): Promise<boolean | undefined>;
+    idle(options?: IdleOptions | undefined): Promise<boolean | undefined>;
     /**
      * Sets flags for a message or message range
      *

package/dist/esm/imap-flow.js

@@ -259,7 +259,10 @@ export class ImapFlow extends EventEmitter {
         this.context = this.options.context;
         this.connectedAt = null;
         this.lastClientWrite = null;
+        this._idleWaiters = [];
         this.idlingAtClose = false;
+        this.closedByClient = false;
+        this._closePending = false;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
         this.untaggedHandlers = {};
@@ -271,6 +274,11 @@ export class ImapFlow extends EventEmitter {
         this.idRequested = false;
         this.maxIdleTime = this.options.maxIdleTime || false;
         this.autoIdleDelay = normalizeAutoIdleDelay(this.options.autoIdleDelay, this.socketTimeout, this.log, this.id);
+        // A server that needs IDLE restarted this often can cut the silence before the first IDLE just
+        // as well: the connection is never left quiet for longer than maxIdleTime
+        if (this.maxIdleTime && this.autoIdleDelay > this.maxIdleTime) {
+            this.autoIdleDelay = this.maxIdleTime;
+        }
         this._lastPollAt = 0;
         this._openDownloads = 0;
         this._recoveryPending = false;
@@ -290,7 +298,7 @@ export class ImapFlow extends EventEmitter {
         // than emitting an error event to the caller.
         this._streamerErrorHandler = (err) => {
             if (['Z_BUF_ERROR', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'EHOSTUNREACH'].includes(err.code)) {
-                this.closeAfter();
+                this.closeConnectionAfter();
                 return;
             }
             this.log.error({ err, cid: this.id });
@@ -311,7 +319,7 @@ export class ImapFlow extends EventEmitter {
         // only awaited connect(), as an unhandled 'error' that throws.
         if (this._errorReported) {
             this.log.debug({ msg: 'Suppressed error after the connection already reported one', err, cid: this.id });
-            this.closeAfter();
+            this.closeConnectionAfter();
             return;
         }
         // During a STARTTLS handshake the upgrade owns the single error path (its settle()
@@ -329,7 +337,7 @@ export class ImapFlow extends EventEmitter {
                 return;
             }
             this.upgrading = false;
-            this.closeAfter();
+            this.closeConnectionAfter();
             return;
         }
         // While the initial connect promise is still pending it owns error reporting:
@@ -340,12 +348,12 @@ export class ImapFlow extends EventEmitter {
             this.initialResolve = false;
             this.initialReject = false;
             this._errorReported = true;
-            this.closeAfter();
+            this.closeConnectionAfter();
             reject(err);
             return;
         }
         this._errorReported = true;
-        this.closeAfter();
+        this.closeConnectionAfter();
         this.emit('error', err);
     }
     /** @internal */
@@ -371,7 +379,7 @@ export class ImapFlow extends EventEmitter {
         }
         if (this.writeSocket.destroyed) {
             this.log.error({ msg: 'Write socket destroyed', cid: this.id });
-            this.close();
+            this.closeConnection();
             return;
         }
         // Append CRLF only to the final part of a command. When sending literals,
@@ -1221,8 +1229,8 @@ export class ImapFlow extends EventEmitter {
                     this.log.error({ err, cid: this.id });
                     this.emitError(err);
                 });
-        this._socketClose = this._socketClose || (() => this.close());
-        this._socketEnd = this._socketEnd || (() => this.close());
+        this._socketClose = this._socketClose || (() => this.closeConnection());
+        this._socketEnd = this._socketEnd || (() => this.closeConnection());
         /**
          * Socket timeout event handler.
          *
@@ -1276,7 +1284,7 @@ export class ImapFlow extends EventEmitter {
                             .catch(err => {
                             this.log.warn({ msg: 'Connection recovery failed after timeout', err, cid: this.id });
                             if (!this.isClosed) {
-                                this.close();
+                                this.closeConnection();
                             }
                         })
                             .finally(() => {
@@ -1587,7 +1595,7 @@ export class ImapFlow extends EventEmitter {
         // is rejected there instead (with a generic TLS error rather than STARTTLS_INJECTION).
         const failSTARTTLSInjection = () => {
             let err = createImapError('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack', 'STARTTLS_INJECTION', { tlsFailed: true });
-            this.closeAfter();
+            this.closeConnectionAfter();
             return err;
         };
         // Check 1: the parser saw more input already buffered right after the tagged OK
@@ -1655,7 +1663,7 @@ export class ImapFlow extends EventEmitter {
                     // Preserve the original error, marked as a TLS failure so callers can tell
                     // an upgrade failure from an ordinary command failure.
                     err.tlsFailed = true;
-                    this.closeAfter();
+                    this.closeConnectionAfter();
                     return reject(err);
                 }
                 resolve(result);
@@ -1845,7 +1853,7 @@ export class ImapFlow extends EventEmitter {
             .catch(err => {
             // The transport goes with the failed attempt: the instance can not be reused, and
             // an open socket would only trip the inactivity watchdog later
-            this.closeAfter();
+            this.closeConnectionAfter();
             if (typeof this.initialReject === 'function') {
                 this.log.error({ err, cid: this.id });
                 clearTimer(this.greetingTimeout);
@@ -1895,7 +1903,7 @@ export class ImapFlow extends EventEmitter {
         // that answers a LOGOUT is the exception: its tagged completion closes the connection.
         const answersLogout = !!this.currentRequest && this.currentRequest.command.toUpperCase() === 'LOGOUT';
         if (!this.greetingReceived || !answersLogout) {
-            this.closeAfter();
+            this.closeConnectionAfter();
         }
     }
     // Drops every capability-derived field together - the counterpart of
@@ -2144,6 +2152,19 @@ export class ImapFlow extends EventEmitter {
     connectionBusy() {
         return !!(this.currentLock || this.locks.length || this.currentRequest || this.requestQueue.length || this._openDownloads);
     }
+    // Settles every idle({ whenFree: true }) call waiting for the connection: resolved to re-check
+    // it, or rejected when the connection is gone
+    /** @internal */
+    settleIdleWaiters(err) {
+        for (let { resolve, reject } of this._idleWaiters.splice(0)) {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        }
+    }
     // Timer process-liveness policy: connection establishment and greeting deadlines keep the
     // process alive, because a caller is waiting on connect() to settle. Background timers
     // (auto-IDLE, IDLE restart, fallback polling, throttle back-off, the held-lock diagnostic) are
@@ -2151,6 +2172,9 @@ export class ImapFlow extends EventEmitter {
     // explicitly on close().
     /** @internal */
     autoidle() {
+        // every place the connection may have become free calls this, so it is where waiting
+        // idle({ whenFree: true }) calls re-check it, also with auto-IDLE turned off
+        this.settleIdleWaiters();
         clearTimer(this.idleStartTimer);
         if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
@@ -2258,7 +2282,7 @@ export class ImapFlow extends EventEmitter {
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
                 this.log.error({ err, cid: this.id });
-                this.closeAfter();
+                this.closeConnectionAfter();
                 reject(err);
             }, deadline.remaining());
             let onConnect = () => {
@@ -2285,7 +2309,7 @@ export class ImapFlow extends EventEmitter {
                             }
                         });
                         this.log.error({ err, cid: this.id });
-                        this.closeAfter();
+                        this.closeConnectionAfter();
                         reject(err);
                     }, this.options.greetingTimeout || GREETING_TIMEOUT);
                     const connected = this.socket;
@@ -2339,7 +2363,7 @@ export class ImapFlow extends EventEmitter {
                 catch (err) {
                     // refused up front: the connection deadline must not stay armed
                     clearTimer(this.connectTimeout);
-                    this.closeAfter();
+                    this.closeConnectionAfter();
                     this.log.error({ err, cid: this.id });
                     reject(err);
                     return;
@@ -2353,7 +2377,7 @@ export class ImapFlow extends EventEmitter {
             this._connectErrorHandler = (err) => {
                 clearTimer(this.connectTimeout);
                 clearTimer(this.greetingTimeout);
-                this.closeAfter();
+                this.closeConnectionAfter();
                 this.log.error({ err, cid: this.id });
                 reject(err);
             };
@@ -2371,6 +2395,9 @@ export class ImapFlow extends EventEmitter {
      * await client.logout();
      */
     async logout() {
+        // marked before the exchange: a server may answer with BYE and drop the socket before the
+        // tagged OK, which closes the connection from the socket's side first
+        this.markClosedByClient();
         return await this.run('LOGOUT');
     }
     /**
@@ -2379,7 +2406,21 @@ export class ImapFlow extends EventEmitter {
      * caller function to proceed, and run `close()` function afterwards.
      */
     closeAfter() {
-        setImmediate(() => this.close());
+        this.markClosedByClient();
+        this.closeConnectionAfter();
+    }
+    // The deferred close ImapFlow itself starts (a server BYE, an error), which closedByClient leaves alone
+    /** @internal */
+    closeConnectionAfter() {
+        this._closePending = true;
+        setImmediate(() => this.closeConnection());
+    }
+    // The application asked for the close, unless the connection is already closed or closing
+    /** @internal */
+    markClosedByClient() {
+        if (!this.isClosed && !this._closePending) {
+            this.closedByClient = true;
+        }
     }
     // Connection-scoped wrapper around the shared stamping helper; see buildConnectionError().
     /** @internal */
@@ -2415,6 +2456,13 @@ export class ImapFlow extends EventEmitter {
      * client.close();
      */
     close() {
+        this.markClosedByClient();
+        this.closeConnection();
+    }
+    // The close itself, for the application's close() and for the closes ImapFlow starts on its own
+    // (the socket ending, a write to a destroyed socket, a failed timeout recovery)
+    /** @internal */
+    closeConnection() {
         try {
             this.closeTimers();
             this.usable = false;
@@ -2458,6 +2506,9 @@ export class ImapFlow extends EventEmitter {
             }
             this.closeRequests();
             this.closeLocks();
+            if (this._idleWaiters.length) {
+                this.settleIdleWaiters(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'idleWait', command: 'IDLE' }));
+            }
             this.closeStreams();
             // clear socket handlers
             this.clearSocketHandlers();
@@ -2898,8 +2949,10 @@ export class ImapFlow extends EventEmitter {
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
      * Unlike auto-IDLE, a direct call does not wait for the connection to be free: a mailbox lock
-     * holder may idle inside its own lock, and idle() can not tell it from another caller.
+     * holder may idle inside its own lock, and idle() can not tell it from another caller. Code that
+     * holds no lock passes `{ whenFree: true }` to wait for the connection to be free first.
      *
+     * @param options IDLE options
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -2907,7 +2960,13 @@ export class ImapFlow extends EventEmitter {
      *
      * await client.idle();
      */
-    async idle() {
+    async idle(options) {
+        // Re-checked on every wake, as another IDLE may have started meanwhile
+        while (options?.whenFree && !this.idling && this.usable && this.connectionBusy()) {
+            await new Promise((resolve, reject) => {
+                this._idleWaiters.push({ resolve, reject });
+            });
+        }
         if (!this.idling) {
             return await this.run('IDLE', this.maxIdleTime);
         }

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

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

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.7.0";
+export const version = "2.9.0";
 export const homepage = "https://imapflow.com/";

package/dist/esm/types.d.ts

@@ -745,6 +745,16 @@ export interface MailboxOpenOptions {
     /** QRESYNC (RFC 7162): the UIDVALIDITY known from the previous session, required with `changedSince` */
     uidValidity?: bigint | number | string | undefined;
 }
+export interface IdleOptions {
+    /**
+     * Wait until the connection is free before starting IDLE: no mailbox lock held or queued, no
+     * command running or queued, no download open. Use it from code that does not hold a mailbox
+     * lock, so IDLE does not land between another caller's commands. A lock holder must not set it,
+     * it would wait for its own release. The returned promise rejects with `NoConnection` when the
+     * connection closes while waiting.
+     */
+    whenFree?: boolean | undefined;
+}
 export interface MailboxLockOptions extends MailboxOpenOptions {
     /**
      * Optional timeout in milliseconds to wait for the lock to be granted.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.7.0",
+    "version": "2.9.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",