imapflow 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/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';
@@ -378,8 +378,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 +389,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,6 +302,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         this.context = this.options.context;
         this.connectedAt = null;
         this.lastClientWrite = null;
+        this._idleWaiters = [];
         this.idlingAtClose = false;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
@@ -2187,6 +2188,14 @@ class ImapFlow extends node_events_1.EventEmitter {
     connectionBusy() {
         return !!(this.currentLock || this.locks.length || this.currentRequest || this.requestQueue.length || this._openDownloads);
     }
+    /** @internal */
+    wakeIdleWaiters() {
+        if (this._idleWaiters.length) {
+            for (let { resolve } of this._idleWaiters.splice(0)) {
+                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 +2203,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.wakeIdleWaiters();
         (0, tools_js_1.clearTimer)(this.idleStartTimer);
         if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
@@ -2501,6 +2513,12 @@ class ImapFlow extends node_events_1.EventEmitter {
             }
             this.closeRequests();
             this.closeLocks();
+            if (this._idleWaiters.length) {
+                let waiterError = this.createNoConnectionError(this.byeReason, { rejectedFrom: 'idleWait', command: 'IDLE' });
+                for (let { reject } of this._idleWaiters.splice(0)) {
+                    reject(waiterError);
+                }
+            }
             this.closeStreams();
             // clear socket handlers
             this.clearSocketHandlers();
@@ -2941,8 +2959,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 +2970,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.8.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.8.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/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';
@@ -378,8 +378,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 +389,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,6 +259,7 @@ export class ImapFlow extends EventEmitter {
         this.context = this.options.context;
         this.connectedAt = null;
         this.lastClientWrite = null;
+        this._idleWaiters = [];
         this.idlingAtClose = false;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
@@ -2144,6 +2145,14 @@ export class ImapFlow extends EventEmitter {
     connectionBusy() {
         return !!(this.currentLock || this.locks.length || this.currentRequest || this.requestQueue.length || this._openDownloads);
     }
+    /** @internal */
+    wakeIdleWaiters() {
+        if (this._idleWaiters.length) {
+            for (let { resolve } of this._idleWaiters.splice(0)) {
+                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 +2160,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.wakeIdleWaiters();
         clearTimer(this.idleStartTimer);
         if (this.options.disableAutoIdle || !this.usable || this.state !== this.states.SELECTED) {
             return;
@@ -2458,6 +2470,12 @@ export class ImapFlow extends EventEmitter {
             }
             this.closeRequests();
             this.closeLocks();
+            if (this._idleWaiters.length) {
+                let waiterError = this.createNoConnectionError(this.byeReason, { rejectedFrom: 'idleWait', command: 'IDLE' });
+                for (let { reject } of this._idleWaiters.splice(0)) {
+                    reject(waiterError);
+                }
+            }
             this.closeStreams();
             // clear socket handlers
             this.clearSocketHandlers();
@@ -2898,8 +2916,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 +2927,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.8.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.8.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.8.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",