imapflow 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Features
+
+* expose idlingAtClose so a consumer can tell a session dropped in IDLE ([eb5ac6c](https://github.com/postalsys/imapflow/commit/eb5ac6c5307a735d4f2526c8e8a266e488dbe17f))
+
 ## [2.6.0](https://github.com/postalsys/imapflow/compare/v2.5.9...v2.6.0) (2026-10-21)
 
 

package/README.md

@@ -135,6 +135,7 @@ Besides `mailbox`, `usable`, `authenticated` and `capabilities`, a client expose
 - `client.context` - data of the application's own, never read by ImapFlow. It starts as the `context` option (`new ImapFlow({ ..., context: { account: 'a1' } })`) and can be replaced at any time. Its type is `unknown`, cast it to what you store there.
 - `client.connectedAt` - when the TCP or TLS connection was established, in milliseconds since the epoch, `null` before that.
 - `client.lastClientWrite` - when the client last wrote to the server (a command, a literal, the `DONE` that ends IDLE), in milliseconds since the epoch, `null` before the first write. Useful for staying ahead of server inactivity timers.
+- `client.idlingAtClose` - whether the connection was in IDLE (or the polling fallback) when it closed. `idling` is already cleared when the `close` event fires, so this tells a server dropping an idle session from one dropping a session mid-command.
 - `client.mailboxList` - with `verifyOnly` and `includeMailboxes`, the mailboxes listed before the connection logged out; `undefined` otherwise.
 
 See the [Quick Start guide](https://imapflow.com/docs/getting-started/quick-start) for more examples, including Gmail, Outlook, and Yahoo configuration.

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';
@@ -151,6 +151,12 @@ export declare class ImapFlow extends EventEmitter {
      * (RFC 9051 allows 30 minutes), and this is what their timer measures
      */
     lastClientWrite: number | null;
+    /**
+     * Whether the connection was in IDLE (or the polling fallback) when it closed, `false` while it
+     * is open. `idling` itself is already cleared by the time the 'close' event fires, so this is
+     * what tells a server dropping an idle session from one dropping a session mid-command
+     */
+    idlingAtClose: boolean;
     /** Whether log entries are also emitted as 'log' events, see the `emitLogs` option */
     emitLogs: boolean;
     /** Hash algorithm for the fallback message id, see `ImapFlowOptions.idHashAlgorithm` */
@@ -372,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
@@ -381,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,8 @@ 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;
         this.untaggedHandlers = {};
@@ -2186,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
@@ -2193,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;
@@ -2464,6 +2477,8 @@ class ImapFlow extends node_events_1.EventEmitter {
             // poll or IDLE that unwinds after this point sees that it no longer owns the flag and
             // leaves it alone (see claimIdling() in commands/idle.ts).
             this._idleSession = null;
+            // a later close() finds idling already cleared and keeps what the first one saw
+            this.idlingAtClose = this.idlingAtClose || this.idling;
             this.idling = false;
             this.closeConnectSteps();
             if (typeof this.preCheck === 'function') {
@@ -2498,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();
@@ -2938,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
@@ -2947,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.6.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.6.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';
@@ -151,6 +151,12 @@ export declare class ImapFlow extends EventEmitter {
      * (RFC 9051 allows 30 minutes), and this is what their timer measures
      */
     lastClientWrite: number | null;
+    /**
+     * Whether the connection was in IDLE (or the polling fallback) when it closed, `false` while it
+     * is open. `idling` itself is already cleared by the time the 'close' event fires, so this is
+     * what tells a server dropping an idle session from one dropping a session mid-command
+     */
+    idlingAtClose: boolean;
     /** Whether log entries are also emitted as 'log' events, see the `emitLogs` option */
     emitLogs: boolean;
     /** Hash algorithm for the fallback message id, see `ImapFlowOptions.idHashAlgorithm` */
@@ -372,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
@@ -381,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,8 @@ 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;
         this.untaggedHandlers = {};
@@ -2143,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
@@ -2150,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;
@@ -2421,6 +2434,8 @@ export class ImapFlow extends EventEmitter {
             // poll or IDLE that unwinds after this point sees that it no longer owns the flag and
             // leaves it alone (see claimIdling() in commands/idle.ts).
             this._idleSession = null;
+            // a later close() finds idling already cleared and keeps what the first one saw
+            this.idlingAtClose = this.idlingAtClose || this.idling;
             this.idling = false;
             this.closeConnectSteps();
             if (typeof this.preCheck === 'function') {
@@ -2455,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();
@@ -2895,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
@@ -2904,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.6.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.6.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.6.0",
+    "version": "2.8.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",