imapflow 2.5.9 → 2.7.0

package/dist/cjs/types.d.ts

@@ -76,8 +76,13 @@ export interface ImapFlowOptions {
     emitLogs?: boolean | undefined;
     /** If true, then logs out automatically after successful authentication */
     verifyOnly?: boolean | undefined;
-    /** If true and verifyOnly is set, lists mailboxes */
+    /** If true and verifyOnly is set, lists mailboxes. The listing is in `client.mailboxList` once `connect()` resolved */
     includeMailboxes?: boolean | undefined;
+    /**
+     * Data of the application's own to keep with the client, such as the account the connection
+     * belongs to. ImapFlow never reads it, it is the initial value of `client.context`
+     */
+    context?: unknown;
     /**
      * Proxy URL. Supports HTTP CONNECT (http:, https:) and SOCKS (socks:, socks4:, socks4a:,
      * socks5:) proxies. IPv6 proxy endpoints are given in URL form, e.g. `socks5://[2001:db8::1]:1080`.
@@ -789,6 +794,22 @@ export interface ExistsEvent {
     /** Message count before this update */
     prevCount: number;
 }
+/**
+ * Payload of the `highestModseq` event: the HIGHESTMODSEQ of the selected mailbox changed (RFC
+ * 7162), so flags or other message metadata changed on the server. Emitted when a poll on a
+ * server without IDLE (`missingIdleCommand` STATUS or SELECT) or a STATUS or re-SELECT of the
+ * open mailbox reports a new value, which is when the changes themselves are not delivered as
+ * `flags` events. A consumer resynchronizes with `fetch(range, { flags: true }, { changedSince:
+ * prevHighestModseq })`.
+ */
+export interface HighestModseqEvent {
+    /** Mailbox path */
+    path: string;
+    /** The new HIGHESTMODSEQ value */
+    highestModseq: bigint;
+    /** The value before this update, undefined when none was known */
+    prevHighestModseq?: bigint | undefined;
+}
 export interface FlagsEvent {
     /** Mailbox path */
     path: string;
@@ -888,7 +909,10 @@ export interface TlsInfo extends CipherNameAndProtocol {
 export interface ImapFlowEvents {
     /** Connection close event */
     close: [];
-    /** Error event */
+    /**
+     * Error event. Emitted at most once per connection, the connection closes after it. An error
+     * while `connect()` is pending rejects `connect()` instead and is not emitted
+     */
     error: [error: Error];
     /** Message count in currently opened mailbox changed */
     exists: [data: ExistsEvent];
@@ -896,7 +920,13 @@ export interface ImapFlowEvents {
     expunge: [data: ExpungeEvent];
     /** Flags were updated for a message */
     flags: [data: FlagsEvent];
-    /** Mailbox was opened */
+    /** The HIGHESTMODSEQ of the selected mailbox changed without the changes being reported, see {@link HighestModseqEvent} */
+    highestModseq: [data: HighestModseqEvent];
+    /**
+     * Mailbox was opened. Also emitted, after `mailboxClose` for the old mailbox object, when the
+     * open mailbox turned out to have a new UIDVALIDITY (a re-SELECT, or a STATUS poll on a server
+     * without IDLE, which then selects the mailbox again): every cached UID of it is invalid
+     */
     mailboxOpen: [mailbox: MailboxObject];
     /** Mailbox was closed, either explicitly or because the connection went away while a mailbox was still selected */
     mailboxClose: [mailbox: MailboxObject];

package/dist/esm/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/esm/commands/fetch.js

@@ -7,11 +7,17 @@ import { createImapError } from '../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)
  */
 export default async function fetch(connection, range, query, options) {
     let mailbox = 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/esm/commands/idle.js

@@ -212,6 +212,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,
@@ -222,6 +223,12 @@ async function pollOnce(connection, session) {
             if (!status) {
                 throw 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/esm/commands/select.js

@@ -211,8 +211,13 @@ export default 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) {
             emitSafe(connection, 'mailboxClose', currentMailbox);
         }
         connection.mailbox = map;
@@ -220,13 +225,19 @@ export default 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) {
             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
-            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) {
+                emitSafe(connection, 'exists', { path, count: map.exists, prevCount: currentMailbox.exists });
+            }
+            if (map.highestModseq && map.highestModseq !== currentMailbox.highestModseq) {
+                emitSafe(connection, 'highestModseq', { path, highestModseq: map.highestModseq, prevHighestModseq: currentMailbox.highestModseq });
+            }
         }
         response.next();
         return map;

package/dist/esm/commands/status.js

@@ -14,8 +14,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
+            emitSafe(connection, 'highestModseq', { path, highestModseq: value, prevHighestModseq });
+        }
     }
 };
 /**
@@ -65,13 +70,22 @@ export default async function status(connection, path, query) {
                     if (!list) {
                         return;
                     }
+                    let updates = [];
                     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/esm/download.js

@@ -229,9 +229,9 @@ export 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/esm/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/esm/errors.js

@@ -60,7 +60,9 @@ export const 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/esm/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/esm/imap-flow.js

@@ -168,6 +168,18 @@ export class ImapFlow extends 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
      */
@@ -219,6 +231,7 @@ export class ImapFlow extends 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;
@@ -243,6 +256,10 @@ export class ImapFlow extends 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 = {};
@@ -288,6 +305,15 @@ export class ImapFlow extends 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
@@ -298,6 +324,7 @@ export class ImapFlow extends 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;
             }
@@ -312,10 +339,12 @@ export class ImapFlow extends 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);
     }
@@ -369,6 +398,7 @@ export class ImapFlow extends 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
@@ -1259,7 +1289,9 @@ export class ImapFlow extends 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);
@@ -2238,6 +2270,7 @@ export class ImapFlow extends EventEmitter {
                 }
                 try {
                     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).
                     detachEarlyErrorHandler(socket);
@@ -2363,6 +2396,15 @@ export class ImapFlow extends 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 createImapError('No mailbox is selected', 'NoMailboxSelected', { command });
+    }
     /**
      * Closes TCP connection without notifying the server.
      *
@@ -2380,6 +2422,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') {
@@ -2803,8 +2847,14 @@ export class ImapFlow extends 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', '', normalizePath(this, path), { listOnly: true });
-                    if (!folders || !folders.length) {
+                    let normalized = 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 => comparePaths(this, entry.path, normalized) &&
+                            ![...(entry.flags || [])].some(flag => typeof flag === 'string' && flag.toUpperCase() === '\\NONEXISTENT'));
+                    if (!exists) {
                         err.mailboxMissing = true;
                     }
                 }
@@ -2847,6 +2897,9 @@ export 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
@@ -3100,6 +3153,9 @@ export 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');
@@ -3113,8 +3169,8 @@ export class ImapFlow extends 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) {
@@ -3224,6 +3280,7 @@ export 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');
@@ -3247,7 +3304,9 @@ export 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');
@@ -3257,8 +3316,9 @@ export class ImapFlow extends 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) {
@@ -3436,6 +3496,9 @@ export class ImapFlow extends 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;
@@ -3452,6 +3515,7 @@ export class ImapFlow extends 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.
@@ -3517,6 +3581,7 @@ export class ImapFlow extends 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
                 }
@@ -3529,6 +3594,7 @@ export class ImapFlow extends EventEmitter {
                     this.currentLock = lock;
                     armHeldTimer();
                     this.autoidle();
+                    unsettled = null;
                     resolve({ path, release });
                 };
                 if (this.mailbox && this.mailbox.path === path && !!this.mailbox.readOnly === !!options.readOnly) {
@@ -3571,23 +3637,35 @@ export class ImapFlow extends 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) {
+                    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 */
         }
     }
     /**
@@ -3781,7 +3859,8 @@ export class ImapFlow extends EventEmitter {
  */
 /**
  * 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/esm/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/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.5.9";
+export const version = "2.7.0";
 export const homepage = "https://imapflow.com/";