imapflow 2.5.9 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* expose mailboxList, context, connectedAt and lastClientWrite on the client ([c054bd3](https://github.com/postalsys/imapflow/commit/c054bd33ab0068531c64d613718233d3a1eff9e6))
+
+
+### Bug Fixes
+
+* emit the error event at most once per connection ([434e6eb](https://github.com/postalsys/imapflow/commit/434e6eb84021892703d02a63dc28da4a8bf086d6))
+* let idle() wait for a free connection before starting IDLE ([4a3d7df](https://github.com/postalsys/imapflow/commit/4a3d7df2116321997a966e0856d7035ed2b60992))
+* reject a mailbox lock when the processLocks pass handling it throws ([a207cd0](https://github.com/postalsys/imapflow/commit/a207cd093535025524ff6066aed092779b0ff569))
+* reject fetch() without a selected mailbox instead of returning nothing ([78036b8](https://github.com/postalsys/imapflow/commit/78036b806b9f70e70a78fa2bc668e340e63297af))
+* report UIDVALIDITY and HIGHESTMODSEQ changes found by the polling fallback ([0f4c306](https://github.com/postalsys/imapflow/commit/0f4c306259ffc9bb973d4cb54f790707c100cc94))
+* require an exact LIST match before treating a failed SELECT mailbox as existing ([99a5db0](https://github.com/postalsys/imapflow/commit/99a5db09a02da721b230fd56bb7d1b240cbb2a0f))
+* start IDLE right away again when idle() is called inside a mailbox lock ([018967d](https://github.com/postalsys/imapflow/commit/018967ded2d6e44801c4af8e211b10870e0f2f44))
+
 ## [2.5.9](https://github.com/postalsys/imapflow/compare/v2.5.8...v2.5.9) (2026-10-20)
 
 

package/README.md

@@ -128,6 +128,16 @@ main().catch(console.error);
 
 An `ImapFlow` instance holds a single connection and cannot reconnect. Once the connection has closed, or after `connect()` has been called once, create a new instance to connect again. Calling `connect()` a second time on the same instance throws an error with the code `InstanceReused`.
 
+### Connection state
+
+Besides `mailbox`, `usable`, `authenticated` and `capabilities`, a client exposes:
+
+- `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.
 
 ## Documentation

package/dist/cjs/commands/fetch.d.ts

@@ -25,6 +25,7 @@ export interface FetchCommandResult {
  * @param range - Message sequence number or UID range
  * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
  * @param options - Fetch options
- * @returns Object with message count and list, or undefined if not in SELECTED state
+ * @returns Object with message count and list, or undefined when the range is empty
+ * @throws NoMailboxSelected when not in SELECTED state (NoConnection once the connection is gone)
  */
 export default function fetch(connection: ImapFlow, range: string, query: FetchQueryObject, options?: FetchCommandOptions | undefined): Promise<FetchCommandResult | undefined>;

package/dist/cjs/commands/fetch.js

@@ -10,11 +10,17 @@ const errors_js_1 = require("../errors.js");
  * @param range - Message sequence number or UID range
  * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
  * @param options - Fetch options
- * @returns Object with message count and list, or undefined if not in SELECTED state
+ * @returns Object with message count and list, or undefined when the range is empty
+ * @throws NoMailboxSelected when not in SELECTED state (NoConnection once the connection is gone)
  */
 async function fetch(connection, range, query, options) {
     let mailbox = (0, tools_js_1.getSelectedMailbox)(connection);
-    if (!mailbox || !range) {
+    if (!mailbox) {
+        // queued behind a CLOSE or a failed SELECT: rejecting keeps fetch() from yielding
+        // nothing as if the mailbox were empty
+        throw connection.createNoMailboxError('FETCH');
+    }
+    if (!range) {
         // nothing to do here
         return;
     }

package/dist/cjs/commands/idle.js

@@ -215,6 +215,7 @@ async function pollOnce(connection, session) {
             // HIGHESTMODSEQ is filtered out again unless the server advertises CONDSTORE, so a
             // CONDSTORE session keeps mailbox.highestModseq current without asking a plain
             // server for an item it does not know.
+            let polled = connection.mailbox;
             let status = await connection.runInternal('STATUS', path, {
                 messages: true,
                 uidNext: true,
@@ -225,6 +226,12 @@ async function pollOnce(connection, session) {
             if (!status) {
                 throw (0, errors_js_1.createImapError)('STATUS poll failed', 'PollFailed');
             }
+            // STATUS can only tell that the UIDs changed, the selected view is stale then: select
+            // the mailbox again, which reports it as closed and opened anew with the new state
+            if (polled && connection.mailbox === polled && status.uidValidity && polled.uidValidity && status.uidValidity !== polled.uidValidity) {
+                connection.log.info({ msg: 'UIDVALIDITY changed, selecting the mailbox again', path, cid: connection.id });
+                await connection.runInternal('SELECT', path, { readOnly: session.selectCommand.command === 'EXAMINE' });
+            }
             break;
         }
         case 'NOOP':

package/dist/cjs/commands/select.js

@@ -214,8 +214,13 @@ async function select(connection, pathInput, options) {
         let currentMailbox = connection.mailbox;
         connection.mailbox = false;
         // Emit mailboxClose if we're switching from a different mailbox.
-        // Re-selecting the same mailbox (e.g., for resync) does not trigger close/open.
-        if (currentMailbox && currentMailbox.path !== path) {
+        // Re-selecting the same mailbox (e.g., for resync) does not trigger close/open, unless
+        // it came back with a new UIDVALIDITY: the old view and every UID in it are gone then,
+        // which is reported the way a fresh mailboxOpen() of another mailbox would be.
+        let reopened = !currentMailbox ||
+            currentMailbox.path !== path ||
+            (!!currentMailbox.uidValidity && !!map.uidValidity && currentMailbox.uidValidity !== map.uidValidity);
+        if (currentMailbox && reopened) {
             (0, tools_js_1.emitSafe)(connection, 'mailboxClose', currentMailbox);
         }
         connection.mailbox = map;
@@ -223,13 +228,19 @@ async function select(connection, pathInput, options) {
         // re-issues the SELECT to detect changes on servers without IDLE support).
         connection.currentSelectCommand = selectCommand;
         connection.state = connection.states.SELECTED;
-        if (!currentMailbox || currentMailbox.path !== path) {
+        if (reopened || !currentMailbox) {
             (0, tools_js_1.emitSafe)(connection, 'mailboxOpen', connection.mailbox);
         }
-        else if (typeof map.exists === 'number' && map.exists !== currentMailbox.exists) {
+        else {
             // A re-SELECT of the open mailbox (the SELECT polling fallback) gets its EXISTS here
-            // instead of in the global handler, so it is reported the same way
-            (0, tools_js_1.emitSafe)(connection, 'exists', { path, count: map.exists, prevCount: currentMailbox.exists });
+            // instead of in the global handler, so it is reported the same way. Flag changes are
+            // not reported by SELECT, a new HIGHESTMODSEQ is the cue to resync them.
+            if (typeof map.exists === 'number' && map.exists !== currentMailbox.exists) {
+                (0, tools_js_1.emitSafe)(connection, 'exists', { path, count: map.exists, prevCount: currentMailbox.exists });
+            }
+            if (map.highestModseq && map.highestModseq !== currentMailbox.highestModseq) {
+                (0, tools_js_1.emitSafe)(connection, 'highestModseq', { path, highestModseq: map.highestModseq, prevHighestModseq: currentMailbox.highestModseq });
+            }
         }
         response.next();
         return map;

package/dist/cjs/commands/status.js

@@ -17,8 +17,13 @@ const MAILBOX_UPDATERS = {
     uidNext: (value, mailbox) => {
         mailbox.uidNext = value;
     },
-    highestModseq: (value, mailbox) => {
-        mailbox.highestModseq = value;
+    highestModseq: (value, mailbox, connection, path) => {
+        let prevHighestModseq = mailbox.highestModseq;
+        if (prevHighestModseq !== value) {
+            mailbox.highestModseq = value;
+            // the changes behind it are not reported by STATUS, the event is the cue to resync
+            (0, tools_js_1.emitSafe)(connection, 'highestModseq', { path, highestModseq: value, prevHighestModseq });
+        }
     }
 };
 /**
@@ -68,13 +73,22 @@ async function status(connection, path, query) {
                     if (!list) {
                         return;
                     }
+                    let updates = [];
                     (0, status_fields_js_1.parseStatusList)(list, (key, value) => {
                         map[key] = value;
-                        let updater = MAILBOX_UPDATERS[key];
-                        if (currentMailbox && updater) {
-                            updater(value, currentMailbox, connection, path);
+                        if (currentMailbox && MAILBOX_UPDATERS[key]) {
+                            updates.push([key, value]);
                         }
                     });
+                    // Under a new UIDVALIDITY the counts describe a mailbox the selected view no
+                    // longer matches, so they are not applied to it; the STATUS poll selects the
+                    // mailbox again instead, which reports it as opened anew
+                    if (currentMailbox && map.uidValidity && currentMailbox.uidValidity && map.uidValidity !== currentMailbox.uidValidity) {
+                        return;
+                    }
+                    for (let [key, value] of updates) {
+                        MAILBOX_UPDATERS[key](value, currentMailbox, connection, path);
+                    }
                 }
             }
         });

package/dist/cjs/download.js

@@ -236,9 +236,9 @@ async function downloadMessage(client, range, part, options) {
         };
         let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
-            // An empty answer also comes from a connection that closed while the consumer was
-            // paused between chunks (fetchOne() finds no mailbox then), and that is not a
-            // missing message: a caller that retries would skip it
+            // An empty answer from a connection that closed while the consumer was paused
+            // between chunks is not a missing message: a caller that retries would skip it
+            // (fetchOne() itself rejects with NoConnection when it finds no mailbox then)
             if (!client.usable) {
                 throw client.createNoConnectionError(false, { rejectedFrom: 'download' });
             }

package/dist/cjs/errors.d.ts

@@ -51,6 +51,7 @@ export declare const ImapFlowErrorCode: {
     readonly ERR_INVALID_URL: "ERR_INVALID_URL";
     readonly UnsupportedTransportOption: "UnsupportedTransportOption";
     readonly InstanceReused: "InstanceReused";
+    readonly NoMailboxSelected: "NoMailboxSelected";
 };
 /** One of the {@link ImapFlowErrorCode} values */
 export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];

package/dist/cjs/errors.js

@@ -64,7 +64,9 @@ exports.ImapFlowErrorCode = {
     // the transport option
     UnsupportedTransportOption: 'UnsupportedTransportOption',
     // API misuse
-    InstanceReused: 'InstanceReused'
+    InstanceReused: 'InstanceReused',
+    // a message command (FETCH) was called while no mailbox was selected
+    NoMailboxSelected: 'NoMailboxSelected'
 };
 /**
  * Error subclass thrown when IMAP authentication fails.

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

@@ -134,6 +134,29 @@ export declare class ImapFlow extends EventEmitter {
      * Is current mailbox idling (`true`) or not (`false`)
      */
     idling: boolean;
+    /**
+     * Data of the application's own, kept with the client and never read by ImapFlow. Starts as
+     * the `context` option; cast it to the type the application stores there
+     */
+    context: unknown;
+    /**
+     * When the TCP (or TLS) connection to the server was established, in milliseconds since the
+     * epoch, `null` before that. Kept after the connection closed
+     */
+    connectedAt: number | null;
+    /**
+     * When the client last wrote to the server (a command, a literal, the DONE that ends IDLE, an
+     * authentication response), in milliseconds since the epoch, `null` before the first write.
+     * Servers drop sessions that have not sent anything for a while, the IDLE ones included
+     * (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` */
@@ -148,6 +171,16 @@ export declare class ImapFlow extends EventEmitter {
     byeReason: string | undefined;
     /** Negotiated TLS session details, `false` for a cleartext connection */
     tls: TlsInfo | false | undefined;
+    /**
+     * The mailboxes a `verifyOnly` connection with `includeMailboxes` listed before it logged out,
+     * `undefined` otherwise
+     *
+     * @example
+     * let client = new ImapFlow({ ..., verifyOnly: true, includeMailboxes: true });
+     * await client.connect();
+     * console.log(client.mailboxList.map(mailbox => mailbox.path));
+     */
+    get mailboxList(): ListResponse[] | undefined;
     /**
      * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
      */
@@ -344,6 +377,9 @@ export declare class ImapFlow extends EventEmitter {
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * 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.
+     *
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -505,6 +541,9 @@ export declare class ImapFlow extends EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @yields Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected (for example
+     *   after `mailboxClose()` or a failed `mailboxOpen()`), or `NoConnection` once the connection
+     *   is gone. Earlier releases yielded nothing in that case, as for an empty mailbox
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -526,6 +565,7 @@ export declare class ImapFlow extends EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @returns Array of Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch()
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -542,7 +582,9 @@ export declare class ImapFlow extends EventEmitter {
      * @param seq Single UID or sequence number of the message to fetch for
      * @param query Fetch query
      * @param options Fetch options
-     * @returns Message data object
+     * @returns Message data object, `false` when the message was not found
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch().
+     *   Earlier releases resolved `undefined` then
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -550,7 +592,7 @@ export declare class ImapFlow extends EventEmitter {
      * let lastMsg = await client.fetchOne('*', {uid: true})
      * console.log(lastMsg.uid);
      */
-    fetchOne(seq: SequenceString, query: FetchQueryObject, options?: FetchOptions | undefined): Promise<FetchMessageObject | false | undefined>;
+    fetchOne(seq: SequenceString, query: FetchQueryObject, options?: FetchOptions | undefined): Promise<FetchMessageObject | false>;
     /**
      * Download either full rfc822 formatted message or a specific bodystructure part as a Stream.
      * Bodystructure parts are decoded so the resulting stream is a binary file. Text content

package/dist/cjs/imap-flow.js

@@ -211,6 +211,18 @@ class ImapFlow extends node_events_1.EventEmitter {
      * Current module version as a static class property
      */
     static { this.version = packageInfo.version; }
+    /**
+     * The mailboxes a `verifyOnly` connection with `includeMailboxes` listed before it logged out,
+     * `undefined` otherwise
+     *
+     * @example
+     * let client = new ImapFlow({ ..., verifyOnly: true, includeMailboxes: true });
+     * await client.connect();
+     * console.log(client.mailboxList.map(mailbox => mailbox.path));
+     */
+    get mailboxList() {
+        return this._mailboxList;
+    }
     /**
      * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
      */
@@ -262,6 +274,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         this._throttleWaits = new Set();
         this._upgradeReject = null;
         this.isClosed = false;
+        this._errorReported = false;
         this.states = states;
         this.state = this.states.NOT_AUTHENTICATED;
         this.lockCounter = 0;
@@ -286,6 +299,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         this.mailbox = false;
         this.currentSelectCommand = false;
         this.idling = false;
+        this.context = this.options.context;
+        this.connectedAt = null;
+        this.lastClientWrite = null;
+        this.idlingAtClose = false;
         this.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
         this.untaggedHandlers = {};
@@ -331,6 +348,15 @@ class ImapFlow extends node_events_1.EventEmitter {
             return;
         }
         err._connId = err._connId || this.id;
+        // One error per connection: emitError() closes the connection, and until the deferred
+        // close() runs a second socket, deflate or parser error may still arrive. Emitting it as
+        // well would reach a consumer that removed its listener after the first one, or one that
+        // 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();
+            return;
+        }
         // During a STARTTLS handshake the upgrade owns the single error path (its settle()
         // helper). Route the error there so a streamer-originated failure is surfaced with its
         // real code (instead of a generic ClosedAfterConnect*) and cannot hang a verifyOnly
@@ -341,6 +367,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             this._upgradeReject = null;
             if (typeof reject === 'function') {
                 // settle() clears the upgrade timer and flags, and closes the connection
+                this._errorReported = true;
                 reject(err);
                 return;
             }
@@ -355,10 +382,12 @@ class ImapFlow extends node_events_1.EventEmitter {
             let reject = this.initialReject;
             this.initialResolve = false;
             this.initialReject = false;
+            this._errorReported = true;
             this.closeAfter();
             reject(err);
             return;
         }
+        this._errorReported = true;
         this.closeAfter();
         this.emit('error', err);
     }
@@ -412,6 +441,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         else {
             return false;
         }
+        this.lastClientWrite = Date.now();
         for (let data of frames) {
             if (this.logRaw) {
                 // Client frames of an authentication exchange carry credentials: the LOGIN
@@ -1302,7 +1332,9 @@ class ImapFlow extends node_events_1.EventEmitter {
                     }
                 });
         const socket = this.socket;
-        socket.once('error', this._socketError);
+        // on(), not once(): with compression the deflate and writeSocket errors are forwarded
+        // onto this socket, and a second one before close() must not find it without a listener
+        socket.on('error', this._socketError);
         socket.once('close', this._socketClose);
         socket.once('end', this._socketEnd);
         socket.on('tlsClientError', this._socketError);
@@ -2281,6 +2313,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 }
                 try {
                     (0, tools_js_1.clearTimer)(this.connectTimeout);
+                    this.connectedAt = Date.now();
                     // ImapFlow now owns the socket; drop the proxy's early error handler
                     // (its "before connection setup" message no longer applies).
                     (0, proxy_connection_js_1.detachEarlyErrorHandler)(socket);
@@ -2406,6 +2439,15 @@ class ImapFlow extends node_events_1.EventEmitter {
         }
         return error;
     }
+    // What a message command called without a selected mailbox rejects with: NoMailboxSelected,
+    // or NoConnection once the connection is gone, as that is why the mailbox is missing then
+    /** @internal */
+    createNoMailboxError(command) {
+        if (!this.usable) {
+            return this.createNoConnectionError(this.byeReason, { rejectedFrom: 'noMailbox', command });
+        }
+        return (0, errors_js_1.createImapError)('No mailbox is selected', 'NoMailboxSelected', { command });
+    }
     /**
      * Closes TCP connection without notifying the server.
      *
@@ -2423,6 +2465,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') {
@@ -2846,8 +2890,14 @@ class ImapFlow extends node_events_1.EventEmitter {
                 // LIST. This sets mailboxMissing on the error so the caller can distinguish
                 // "doesn't exist" from other failures, for getMailboxLock() callers as well.
                 try {
-                    let folders = await this.run('LIST', '', (0, tools_js_1.normalizePath)(this, path), { listOnly: true });
-                    if (!folders || !folders.length) {
+                    let normalized = (0, tools_js_1.normalizePath)(this, path);
+                    let folders = await this.run('LIST', '', normalized, { listOnly: true });
+                    // The path is the LIST pattern, so a % or * in a name also matches other
+                    // mailboxes, and an entry marked \NonExistent (RFC 5258) does not exist either
+                    let exists = Array.isArray(folders) &&
+                        folders.some(entry => (0, tools_js_1.comparePaths)(this, entry.path, normalized) &&
+                            ![...(entry.flags || [])].some(flag => typeof flag === 'string' && flag.toUpperCase() === '\\NONEXISTENT'));
+                    if (!exists) {
                         err.mailboxMissing = true;
                     }
                 }
@@ -2890,6 +2940,9 @@ class ImapFlow extends node_events_1.EventEmitter {
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * 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.
+     *
      * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
@@ -3143,6 +3196,9 @@ class ImapFlow extends node_events_1.EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @yields Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected (for example
+     *   after `mailboxClose()` or a failed `mailboxOpen()`), or `NoConnection` once the connection
+     *   is gone. Earlier releases yielded nothing in that case, as for an empty mailbox
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3156,8 +3212,8 @@ class ImapFlow extends node_events_1.EventEmitter {
     async *fetch(range, query, options) {
         options = options || {};
         if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return;
+            // an empty result would look like an empty mailbox, for example right after close()
+            throw this.createNoMailboxError('FETCH');
         }
         let resolved = await this.resolveRange(range, options);
         if (!resolved) {
@@ -3267,6 +3323,7 @@ class ImapFlow extends node_events_1.EventEmitter {
      * @param query Fetch query
      * @param options Fetch options
      * @returns Array of Message data object
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch()
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3290,7 +3347,9 @@ class ImapFlow extends node_events_1.EventEmitter {
      * @param seq Single UID or sequence number of the message to fetch for
      * @param query Fetch query
      * @param options Fetch options
-     * @returns Message data object
+     * @returns Message data object, `false` when the message was not found
+     * @throws An error with the code `NoMailboxSelected` when no mailbox is selected, see fetch().
+     *   Earlier releases resolved `undefined` then
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -3300,8 +3359,9 @@ class ImapFlow extends node_events_1.EventEmitter {
      */
     async fetchOne(seq, query, options) {
         if (!this.mailbox) {
-            // no mailbox selected, nothing to do
-            return;
+            // undefined used to be returned here, indistinguishable from a missing message for a
+            // caller that only tests the result
+            throw this.createNoMailboxError('FETCH');
         }
         if (seq === '*') {
             if (!this.mailbox.exists) {
@@ -3479,6 +3539,9 @@ class ImapFlow extends node_events_1.EventEmitter {
             return;
         }
         this.processingLock = true;
+        // The lock taken off the queue and not settled yet. A pass that throws out of its loop
+        // rejects it, its caller would wait forever otherwise: it is in the queue no longer.
+        let unsettled = null;
         try {
             // Process all locks in queue until empty
             let processedCount = 0;
@@ -3495,6 +3558,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                     await new Promise(resolve => setImmediate(resolve));
                 }
                 const lock = this.locks.shift();
+                unsettled = lock;
                 const { resolve, reject, path, options, lockId } = lock;
                 // From here on the grant/reject path owns the outcome; the acquire
                 // timer must not race with resolution.
@@ -3560,6 +3624,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 };
                 if (!this.usable || !this.socket || this.socket.destroyed) {
                     this.log.trace({ msg: 'Failed to acquire mailbox lock', path, lockId, idling: this.idling });
+                    unsettled = null;
                     reject(this.createNoConnectionError(false, { rejectedFrom: 'mailboxLock', path }));
                     continue; // Process next lock in queue
                 }
@@ -3572,6 +3637,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                     this.currentLock = lock;
                     armHeldTimer();
                     this.autoidle();
+                    unsettled = null;
                     resolve({ path, release });
                 };
                 if (this.mailbox && this.mailbox.path === path && !!this.mailbox.readOnly === !!options.readOnly) {
@@ -3614,23 +3680,35 @@ class ImapFlow extends node_events_1.EventEmitter {
                         ...(options.description && { description: options.description }),
                         err
                     });
+                    unsettled = null;
                     reject(err);
                     // Continue to next lock in queue
                 }
             }
         }
+        catch (err) {
+            if (unsettled) {
+                let lock = unsettled;
+                unsettled = null;
+                // granted but not handed out (the grant itself failed): nobody can release it
+                if (this.currentLock === lock) {
+                    (0, tools_js_1.clearTimer)(lock.heldWarnTimer);
+                    lock.heldWarnTimer = null;
+                    this.currentLock = false;
+                }
+                lock.reject(err);
+            }
+            throw err;
+        }
         finally {
             this.processingLock = false;
-            // New locks may have been queued while we were processing (e.g.,
-            // a lock that failed immediately and the next getMailboxLock call
-            // arrived before we finished). Schedule another run if needed.
-            /* c8 ignore start */ // requires a lock to be enqueued during an in-flight processLocks pass; not reproducible deterministically
+            // A pass that ended with locks queued and none held (it threw out of its loop) would
+            // leave them waiting with nothing to start another pass. Schedule one.
             if (this.locks.length && !this.currentLock) {
                 setImmediate(() => {
                     this.processLocks().catch(err => this.log.error({ err, cid: this.id }));
                 });
             }
-            /* c8 ignore stop */
         }
     }
     /**
@@ -3825,7 +3903,8 @@ exports.ImapFlow = ImapFlow;
  */
 /**
  * Error event. In most cases getting an error event also means that connection is closed
- * and pending operations should return with a failure.
+ * and pending operations should return with a failure. Emitted at most once per connection,
+ * later errors while the connection is closing are only logged.
  *
  * @event ImapFlow#error
  * @example

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

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.5.9";
+export declare const version = "2.7.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.5.9";
+exports.version = "2.7.0";
 exports.homepage = "https://imapflow.com/";