imapflow 2.5.8 → 2.6.0

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

@@ -134,6 +134,23 @@ 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 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 +165,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 +371,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 +535,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 +559,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 +576,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 +586,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,9 @@ 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.emitLogs = !!this.options.emitLogs;
         this.lo = 0;
         this.untaggedHandlers = {};
@@ -331,6 +347,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 +366,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 +381,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 +440,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
@@ -870,9 +899,17 @@ class ImapFlow extends node_events_1.EventEmitter {
     async handleResponse(data) {
         let parsed;
         try {
-            parsed = await (0, imap_handler_js_1.parser)(data.payload, { literals: data.literals });
+            parsed = await (0, imap_handler_js_1.parser)(data.payload, { literals: data.literals, maxResponseTokens: this.options.maxResponseTokens });
         }
         catch (err) {
+            if (err.code === 'TooManyTokens') {
+                // A size limit, so as terminal as the ones ImapStream enforces: the server is
+                // flooding responses, and skipping the line would only invite the next one
+                this.log.error({ msg: 'Response exceeded the token limit', payloadBytes: data.payload.length, err, cid: this.id });
+                this.rejectCurrentRequest(err);
+                this.failProtocol(err);
+                return false;
+            }
             // can not make sense of this. The payload can be up to the configured line
             // cap (1GB by default), so log only a bounded prefix: a server looping
             // unparseable garbage would otherwise turn this error log into a disk filler.
@@ -1294,7 +1331,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);
@@ -2273,6 +2312,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);
@@ -2398,6 +2438,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.
      *
@@ -2838,8 +2887,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;
                     }
                 }
@@ -2882,6 +2937,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
@@ -3135,6 +3193,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');
@@ -3148,8 +3209,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) {
@@ -3259,6 +3320,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');
@@ -3282,7 +3344,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');
@@ -3292,8 +3356,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) {
@@ -3471,6 +3536,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;
@@ -3487,6 +3555,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.
@@ -3552,6 +3621,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
                 }
@@ -3564,6 +3634,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) {
@@ -3606,23 +3677,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 */
         }
     }
     /**
@@ -3817,7 +3900,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.8";
+export declare const version = "2.6.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.8";
+exports.version = "2.6.0";
 exports.homepage = "https://imapflow.com/";

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`.
@@ -133,8 +138,9 @@ export interface ImapFlowOptions {
      * whatever is left of `maxResponseSize`, so lowering that also bounds line buffering.
      * Exceeding it is terminal: the connection fails with error code `LineTooLarge` and
      * no further input is parsed. The limit bounds the bytes of a line, not the memory its parse
-     * takes, which is several times the line size for a line of many small tokens. A SEARCH
-     * answer of plain numbers is read into an array of about the size of the line.
+     * takes, which is several times the line size for a line of many small tokens, see
+     * `maxResponseTokens`. A SEARCH answer of plain numbers is read into an array of about the
+     * size of the line.
      */
     maxLineLength?: number | undefined;
     /**
@@ -159,6 +165,16 @@ export interface ImapFlowOptions {
      * no further input is parsed.
      */
     maxResponseSize?: number | undefined;
+    /**
+     * Maximum number of tokens (atoms, strings, literals, lists and other parse tree nodes) in a
+     * single IMAP response. The byte limits bound what a server sends, this bounds what parsing it
+     * costs: each token takes around a hundred bytes of heap while the response is parsed, so a
+     * response of many small tokens costs about fifty times its size. Defaults to 1000000, far
+     * above any legitimate response (a SEARCH answer of plain numbers is not tokenized and does
+     * not count). Lower it in a memory-limited runtime. `Infinity` disables the limit. Exceeding it
+     * is terminal: the connection fails with error code `TooManyTokens`.
+     */
+    maxResponseTokens?: number | undefined;
     /**
      * Threshold in milliseconds for warning that a mailbox lock has been held
      * for a long time (diagnostic for forgotten release() calls). Defaults to
@@ -681,9 +697,12 @@ export type DownloadManyResult = {
 export interface AppendResponseObject {
     /** Full mailbox path where the message was uploaded to */
     destination: string;
-    /** Mailbox UIDVALIDITY if server has UIDPLUS extension enabled */
+    /** Mailbox UIDVALIDITY if server has UIDPLUS extension enabled, only set together with the `uid` it reported */
     uidValidity?: bigint | undefined;
-    /** UID of the uploaded message if server has UIDPLUS extension enabled */
+    /**
+     * UID of the uploaded message if server has UIDPLUS extension enabled. Without a usable APPENDUID,
+     * an append to the selected mailbox looks it up by sequence number instead, and `uidValidity` is not set
+     */
     uid?: number | undefined;
     /** Sequence number of the uploaded message if path is currently selected mailbox */
     seq?: number | undefined;
@@ -775,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;
@@ -874,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];
@@ -882,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/append.js

@@ -141,11 +141,14 @@ export default async function append(connection, destination, content, flags, id
                 // message was already stored and a retrying caller would duplicate it.
                 let uidValidity = parseBigIntValue(section[1] && section[1].value, MAX_UINT32_DIGITS);
                 let uid = parseUintValue(section[2] && section[2].value, MAX_UINT32_DIGITS);
-                if (uidValidity !== false) {
-                    map.uidValidity = uidValidity;
-                }
+                // UIDVALIDITY is only reported next to the UID it was sent with: kept without one,
+                // it would end up paired with the UID the SEARCH fallback below guesses from the
+                // sequence number, and the pair would pass for a server-confirmed identity.
                 if (uid) {
                     map.uid = uid;
+                    if (uidValidity) {
+                        map.uidValidity = uidValidity;
+                    }
                 }
             }
         }

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);
+                    }
                 }
             }
         });