imapflow 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.1.2](https://github.com/postalsys/imapflow/compare/v2.1.1...v2.1.2) (2026-09-28)
+
+
+### Bug Fixes
+
+* **deps:** update libmime to 5.4.6 and mailsplit to 5.4.19 ([f6afb32](https://github.com/postalsys/imapflow/commit/f6afb32cbb1df43993a1df2cbd003e013bc10fa8))
+
+## [2.1.1](https://github.com/postalsys/imapflow/compare/v2.1.0...v2.1.1) (2026-09-28)
+
+
+### Bug Fixes
+
+* settle every pending connect on close, refuse empty search operands, keep NIL envelope rows, prefer top-level special-use folders ([27a93cc](https://github.com/postalsys/imapflow/commit/27a93ccd292fc95842bcc27cdc76e0cb0de613ba))
+
 ## [2.1.0](https://github.com/postalsys/imapflow/compare/v2.0.8...v2.1.0) (2026-09-27)
 
 

package/README.md

@@ -68,6 +68,8 @@ const main = async () => {
 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`.
+
 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/list.js

@@ -151,10 +151,12 @@ async function list(connection, reference, mailbox, options) {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;
                         }
+                        // A name sent as a literal arrives as a Buffer, so convert it once for both fields
+                        let rawPath = ((untagged.attributes[2] && untagged.attributes[2].value) || '').toString();
                         let entry = {
                             // Decode from modified UTF-7 wire format and normalize the path
-                            path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, ((untagged.attributes[2] && untagged.attributes[2].value) || ''))),
-                            pathAsListed: ((untagged.attributes[2] && untagged.attributes[2].value) || ''),
+                            path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, rawPath)),
+                            pathAsListed: rawPath,
                             flags: new Set((0, tools_js_1.getStringList)(untagged.attributes[0])),
                             delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
                             listed: true
@@ -382,9 +384,11 @@ async function list(connection, reference, mailbox, options) {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;
                         }
+                        // A name sent as a literal arrives as a Buffer, so convert it once for both fields
+                        let rawPath = ((untagged.attributes[2] && untagged.attributes[2].value) || '').toString();
                         let entry = {
-                            path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, ((untagged.attributes[2] && untagged.attributes[2].value) || ''))),
-                            pathAsListed: ((untagged.attributes[2] && untagged.attributes[2].value) || ''),
+                            path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, rawPath)),
+                            pathAsListed: rawPath,
                             flags: new Set((0, tools_js_1.getStringList)(untagged.attributes[0])),
                             delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
                             subscribed: true
@@ -450,15 +454,23 @@ async function list(connection, reference, mailbox, options) {
         // Resolve special-use conflicts. Each type goes to one mailbox and each mailbox gets
         // at most one type. Candidates are taken in priority order across all types (user >
         // extension > name, then alphabetically), so a mailbox claimed by a stronger match
-        // leaves its other type to that type's next candidate instead of to nobody.
+        // leaves its other type to that type's next candidate instead of to nobody. Within a
+        // source a shallower mailbox wins before the alphabetical order is consulted, so that
+        // INBOX.Sent is preferred over INBOX.Archive.Sent.
         let candidates = Object.entries(specialUseMatches).flatMap(([type, matches]) => matches.map(match => ({ type, ...match })));
         candidates.sort((a, b) => {
             let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
             let bSource = SOURCE_SORT_ORDER.indexOf(b.source);
-            if (aSource === bSource) {
-                return a.entry.path.localeCompare(b.entry.path);
+            if (aSource !== bSource) {
+                return aSource - bSource;
             }
-            return aSource - bSource;
+            // parent is set on every listed entry before the candidates are ranked
+            let aDepth = a.entry.parent.length;
+            let bDepth = b.entry.parent.length;
+            if (aDepth !== bDepth) {
+                return aDepth - bDepth;
+            }
+            return a.entry.path.localeCompare(b.entry.path);
         });
         let assignedTypes = new Set();
         for (let { type, entry, source } of candidates) {

package/dist/cjs/errors.d.ts

@@ -37,12 +37,14 @@ export declare const ImapFlowErrorCode: {
     readonly InvalidTokenValue: "InvalidTokenValue";
     readonly InvalidTextValue: "InvalidTextValue";
     readonly InvalidSequenceSet: "InvalidSequenceSet";
+    readonly InvalidSearchQuery: "InvalidSearchQuery";
     readonly DownloadOverflow: "DownloadOverflow";
     readonly DownloadIncomplete: "DownloadIncomplete";
     readonly ProxyError: "ProxyError";
     readonly EPROXY: "EPROXY";
     readonly UnsupportedProxyAddress: "UnsupportedProxyAddress";
     readonly ERR_INVALID_URL: "ERR_INVALID_URL";
+    readonly InstanceReused: "InstanceReused";
 };
 /** One of the {@link ImapFlowErrorCode} values */
 export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];

package/dist/cjs/errors.js

@@ -44,6 +44,7 @@ exports.ImapFlowErrorCode = {
     InvalidTokenValue: 'InvalidTokenValue',
     InvalidTextValue: 'InvalidTextValue',
     InvalidSequenceSet: 'InvalidSequenceSet',
+    InvalidSearchQuery: 'InvalidSearchQuery',
     // download()
     DownloadOverflow: 'DownloadOverflow',
     DownloadIncomplete: 'DownloadIncomplete',
@@ -51,7 +52,9 @@ exports.ImapFlowErrorCode = {
     ProxyError: 'ProxyError',
     EPROXY: 'EPROXY',
     UnsupportedProxyAddress: 'UnsupportedProxyAddress',
-    ERR_INVALID_URL: 'ERR_INVALID_URL'
+    ERR_INVALID_URL: 'ERR_INVALID_URL',
+    // API misuse
+    InstanceReused: 'InstanceReused'
 };
 /**
  * Error subclass thrown when IMAP authentication fails.

package/dist/cjs/handler/imap-stream.js

@@ -1,11 +1,8 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImapStream = void 0;
 const node_stream_1 = require("node:stream");
-const logger_js_1 = __importDefault(require("../logger.js"));
+const logger_js_1 = require("../logger.js");
 const limits_js_1 = require("./limits.js");
 const LINE = 0x01;
 const LITERAL = 0x02;
@@ -36,13 +33,12 @@ class ImapStream extends node_stream_1.Transform {
         });
         this.options = options || {};
         this.cid = this.options.cid;
-        this.log =
-            this.options.logger && typeof this.options.logger === 'object'
-                ? this.options.logger
-                : logger_js_1.default.child({
-                    component: 'imap-connection',
-                    cid: this.cid
-                });
+        if (this.options.logger && typeof this.options.logger === 'object') {
+            this.log = this.options.logger;
+        }
+        else {
+            this.log = (0, logger_js_1.createConnectionLogger)({ cid: this.cid, logRaw: this.options.logRaw });
+        }
         this.readBytesCounter = 0;
         // Maximum length of a single line (response without a literal). Bounds the line buffer
         // so a server that never sends a line terminator cannot exhaust memory.

package/dist/cjs/imap-flow.js

@@ -46,7 +46,7 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_zlib_1 = __importDefault(require("node:zlib"));
 const node_events_1 = require("node:events");
 const node_stream_1 = require("node:stream");
-const logger_js_1 = __importDefault(require("./logger.js"));
+const logger_js_1 = require("./logger.js");
 const packageInfo = __importStar(require("./package-info.js"));
 const imap_stream_js_1 = require("./handler/imap-stream.js");
 const imap_handler_js_1 = require("./handler/imap-handler.js");
@@ -1931,9 +1931,17 @@ class ImapFlow extends node_events_1.EventEmitter {
     async connect() {
         if (this._connectCalled) {
             // Prevent re-using ImapFlow instances by allowing to call connect just once.
-            throw new Error('Can not re-use ImapFlow instance');
+            let err = new Error('Can not re-use ImapFlow instance');
+            err.code = 'InstanceReused';
+            throw err;
         }
         this._connectCalled = true;
+        let closedError = () => this.createNoConnectionError(this.byeReason, { rejectedFrom: 'connect' });
+        // close() already ran, so there is no connection to set up and nothing would ever
+        // settle a connect attempt started now.
+        if (this.isClosed) {
+            throw closedError();
+        }
         // One deadline for the whole attempt, started before anything is resolved or negotiated.
         // Proxy DNS and proxy negotiation used to run entirely outside the timer, so a stalled
         // proxy could hang far beyond the documented connectionTimeout.
@@ -1979,9 +1987,20 @@ class ImapFlow extends node_events_1.EventEmitter {
                 error._err = err;
                 throw error;
             }
+            // close() during proxy setup found no socket to destroy and no connect to reject,
+            // so the tunnel that just opened is dropped here instead of being handed to a
+            // closed client.
+            if (this.isClosed) {
+                socket.destroy();
+                throw closedError();
+            }
         }
         // Guarded: close() rejects a pending connect() synchronously. See guardedPromise().
         let connectPromise = (0, tools_js_1.guardedPromise)((resolve, reject) => {
+            // Stored before the transport is up, so a close() that lands before onConnect
+            // still rejects this attempt through closeConnectSteps().
+            this.initialResolve = resolve;
+            this.initialReject = reject;
             // Whatever the proxy phase already used is gone from the budget
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
@@ -2033,9 +2052,6 @@ class ImapFlow extends node_events_1.EventEmitter {
                     this.setSocketHandlers();
                     this.setEventHandlers();
                     connected.pipe(this.streamer);
-                    // executed by initial "* OK"
-                    this.initialResolve = resolve;
-                    this.initialReject = reject;
                     /* c8 ignore next 4 */ // defensive: the onConnect setup body does not throw under normal operation
                 }
                 catch (ex) {
@@ -2219,7 +2235,10 @@ class ImapFlow extends node_events_1.EventEmitter {
             this._upgradeReject = null;
             reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
         }
-        if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
+        // A verifyOnly session closes itself with LOGOUT and startSession() settles connect()
+        // with the outcome, so the close is not a failure there. Before the greeting nothing
+        // else can settle it (BYE greeting, FIN, close() while the transport is still coming up).
+        if (typeof this.initialReject === 'function' && (!this.options.verifyOnly || !this.greetingReceived)) {
             (0, tools_js_1.clearTimer)(this.greetingTimeout);
             let reject = this.initialReject;
             this.initialResolve = false;
@@ -2530,7 +2549,26 @@ class ImapFlow extends node_events_1.EventEmitter {
      * // 125
      */
     async mailboxOpen(path, options) {
-        return await this.run('SELECT', path, options);
+        try {
+            return await this.run('SELECT', path, options);
+        }
+        catch (err) {
+            if (err.responseStatus === 'NO') {
+                // SELECT failed with NO: verify whether the mailbox exists at all by running
+                // 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) {
+                        err.mailboxMissing = true;
+                    }
+                }
+                catch (E) {
+                    this.log.trace({ msg: 'Failed to verify failed mailbox', path, err: E });
+                }
+            }
+            throw err;
+        }
     }
     /**
      * Closes a previously opened mailbox
@@ -3232,20 +3270,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                     break; // Wait for this lock to be released
                 }
                 catch (err) {
-                    if (err.responseStatus === 'NO') {
-                        // SELECT failed with NO: verify whether the mailbox exists
-                        // at all by running LIST. This sets mailboxMissing on the error
-                        // so the caller can distinguish "doesn't exist" from other failures.
-                        try {
-                            let folders = await this.run('LIST', '', path, { listOnly: true });
-                            if (!folders || !folders.length) {
-                                err.mailboxMissing = true;
-                            }
-                        }
-                        catch (E) {
-                            this.log.trace({ msg: 'Failed to verify failed mailbox', path, err: E });
-                        }
-                    }
+                    // mailboxOpen() has already marked a missing mailbox (mailboxMissing)
                     this.log.trace({
                         msg: 'Failed to acquire mailbox lock',
                         path,
@@ -3336,12 +3361,14 @@ class ImapFlow extends node_events_1.EventEmitter {
     }
     /** @internal */
     getLogger() {
-        let mainLogger = this.options.logger && typeof this.options.logger === 'object'
-            ? this.options.logger
-            : logger_js_1.default.child({
-                component: 'imap-connection',
-                cid: this.id
-            });
+        let mainLogger = {};
+        if (this.options.logger && typeof this.options.logger === 'object') {
+            mainLogger = this.options.logger;
+        }
+        else if (this.options.logger !== false) {
+            // {logger:false} never consults mainLogger, so it does not create the default logger
+            mainLogger = (0, logger_js_1.createConnectionLogger)({ cid: this.id, logRaw: this.options.logRaw });
+        }
         let synteticLogger = {};
         let levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
         for (let level of levels) {

package/dist/cjs/logger.d.ts

@@ -1,3 +1,21 @@
-import pino from 'pino';
-declare const logger: pino.Logger<never, boolean>;
-export default logger;
+import { type Logger as PinoLogger } from 'pino';
+/**
+ * Returns the shared default logger, used when a connection is given no logger of its own.
+ * Created on first use, so importing the library does not set up a stdout logger nobody asked
+ * for. Level info: a caller that asks for raw socket data (logRaw) lowers its own child logger
+ * to trace.
+ *
+ * @returns The default pino logger
+ */
+export declare function getDefaultLogger(): PinoLogger;
+/**
+ * Returns the child of the default logger a connection logs through when it was given no
+ * logger of its own.
+ *
+ * @param options - cid is the connection id to stamp on entries, logRaw asks for raw socket data
+ * @returns A child logger of the default logger
+ */
+export declare function createConnectionLogger(options: {
+    cid?: string | undefined;
+    logRaw?: boolean | undefined;
+}): PinoLogger;

package/dist/cjs/logger.js

@@ -3,9 +3,39 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultLogger = getDefaultLogger;
+exports.createConnectionLogger = createConnectionLogger;
 const pino_1 = __importDefault(require("pino"));
-const logger = (0, pino_1.default)();
-logger.level = 'trace';
-exports.default = logger;
-module.exports = exports.default;
-Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });
+let logger = null;
+/**
+ * Returns the shared default logger, used when a connection is given no logger of its own.
+ * Created on first use, so importing the library does not set up a stdout logger nobody asked
+ * for. Level info: a caller that asks for raw socket data (logRaw) lowers its own child logger
+ * to trace.
+ *
+ * @returns The default pino logger
+ */
+function getDefaultLogger() {
+    if (!logger) {
+        logger = (0, pino_1.default)({ level: 'info' });
+    }
+    return logger;
+}
+/**
+ * Returns the child of the default logger a connection logs through when it was given no
+ * logger of its own.
+ *
+ * @param options - cid is the connection id to stamp on entries, logRaw asks for raw socket data
+ * @returns A child logger of the default logger
+ */
+function createConnectionLogger(options) {
+    let child = getDefaultLogger().child({
+        component: 'imap-connection',
+        cid: options.cid
+    });
+    // Raw socket data is logged at trace level, so asking for it lowers the threshold
+    if (options.logRaw) {
+        child.level = 'trace';
+    }
+    return child;
+}

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

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

package/dist/cjs/search-compiler.d.ts

@@ -9,7 +9,7 @@ export type SearchAttribute = ImapAttributeNode | SearchAttribute[];
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
- * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param connection - IMAP connection object (capabilities and enabled extensions are read)
  * @param query - Search query object
  * @returns Array of IMAP search attributes
  * @throws {Error} When required server extensions are not available

package/dist/cjs/search-compiler.js

@@ -91,6 +91,17 @@ let processDateField = (attributes, term, value) => {
 };
 // Pre-compiled regex for better performance
 const UNICODE_PATTERN = /[^\x00-\x7F]/;
+/**
+ * Throws a coded search compilation error.
+ *
+ * @param code - Error code, one of the ImapFlowErrorCode values
+ * @param message - Error message
+ */
+let fail = (code, message) => {
+    let error = new Error(message);
+    error.code = code;
+    throw error;
+};
 /**
  * Checks if a string contains Unicode characters.
  * Used to determine if CHARSET UTF-8 needs to be specified.
@@ -110,7 +121,7 @@ let isUnicodeString = (str) => {
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
- * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param connection - IMAP connection object (capabilities and enabled extensions are read)
  * @param query - Search query object
  * @returns Array of IMAP search attributes
  * @throws {Error} When required server extensions are not available
@@ -136,21 +147,29 @@ const searchCompiler = (connection, query) => {
     const attributes = [];
     // Track if we need to specify UTF-8 charset
     let hasUnicode = false;
-    const mailbox = connection.mailbox;
     /**
      * Recursively walks through the query object and builds IMAP attributes.
      * @param params - Query parameters to process
      */
     const walk = (params) => {
-        // Walks a query object and wraps the resulting attributes in a
-        // sub-array so the IMAP compiler emits parentheses around them.
-        // Used when a single search-key is required (NOT, OR operands)
-        // but the condition has multiple keys (RFC 3501 Section 6.4.4).
-        let walkGrouped = (obj) => {
+        // Compiles one NOT or OR operand, which the caller has already put its operator in
+        // front of. An operand with several keys is wrapped in a sub-array so the IMAP compiler
+        // emits parentheses around it, as the operator takes a single search-key
+        // (RFC 3501 Section 6.4.4). An operand that compiles to nothing (an invalid date, an
+        // empty object, ...) is refused: the operator would otherwise bind to whatever
+        // criterion follows it and invert or widen the search.
+        let walkOperand = (operator, obj) => {
             let startIdx = attributes.length;
-            walk(obj);
-            let subAttrs = attributes.splice(startIdx);
-            attributes.push(subAttrs);
+            if (obj && typeof obj === 'object') {
+                walk(obj);
+            }
+            if (attributes.length === startIdx) {
+                fail('InvalidSearchQuery', `Search operand for ${operator} does not include any usable search criteria`);
+            }
+            if (Object.keys(obj).length > 1) {
+                let subAttrs = attributes.splice(startIdx);
+                attributes.push(subAttrs);
+            }
         };
         Object.keys(params || {}).forEach(term => {
             switch (term.toUpperCase()) {
@@ -196,9 +215,7 @@ const searchCompiler = (connection, query) => {
                         // reject the whole search with a tagged BAD, so fail with a
                         // descriptive error instead
                         if ((0, tools_js_1.isRev2Active)(connection)) {
-                            let error = new Error(`The "${term.toLowerCase()}" search key does not exist in IMAP4rev2`);
-                            error.code = 'MissingServerExtension';
-                            throw error;
+                            fail('MissingServerExtension', `The "${term.toLowerCase()}" search key does not exist in IMAP4rev2`);
                         }
                         setBoolOpt(attributes, term, true);
                     }
@@ -244,6 +261,11 @@ const searchCompiler = (connection, query) => {
                         // Fallback to Gmail message ID
                         setOpt(attributes, 'X-GM-MSGID', params[term]);
                     }
+                    else if (params[term]) {
+                        // Dropping the criterion would widen the search to every message
+                        // matching the rest of the query, which a delete or move acts on
+                        fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for EMAILID');
+                    }
                     break;
                 // Thread ID support (OBJECTID or Gmail extension)
                 case 'THREADID':
@@ -254,6 +276,11 @@ const searchCompiler = (connection, query) => {
                         // Fallback to Gmail thread ID
                         setOpt(attributes, 'X-GM-THRID', params[term]);
                     }
+                    else if (params[term]) {
+                        // Dropping the criterion would widen the search to every message
+                        // matching the rest of the query, which a delete or move acts on
+                        fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for THREADID');
+                    }
                     break;
                 // Gmail raw search
                 case 'GMRAW':
@@ -265,9 +292,7 @@ const searchCompiler = (connection, query) => {
                         setOpt(attributes, 'X-GM-RAW', params[term]);
                     }
                     else {
-                        let error = new Error('Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
-                        error.code = 'MissingServerExtension';
-                        throw error;
+                        fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
                     }
                     break;
                 // Gmail label search. Compiles { has, not } into an X-GM-RAW "label:"/"-label:" query
@@ -301,9 +326,7 @@ const searchCompiler = (connection, query) => {
                         break;
                     }
                     if (!connection.capabilities.has('X-GM-EXT-1')) {
-                        let error = new Error('Server does not support X-GM-EXT-1 extension required for label search');
-                        error.code = 'MissingServerExtension';
-                        throw error;
+                        fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for label search');
                     }
                     let rawQuery = rawParts.join(' ');
                     if (isUnicodeString(rawQuery)) {
@@ -347,8 +370,10 @@ const searchCompiler = (connection, query) => {
                 case 'UNKEYWORD':
                     {
                         let flag = (0, tools_js_1.formatFlag)(params[term]);
-                        // Only add if flag is supported or already exists in mailbox
-                        if ((0, tools_js_1.canUseFlag)(mailbox, flag) || mailbox.flags.has(flag)) {
+                        // Compiled even when the mailbox does not allow the keyword: the
+                        // correct answer is then the empty set, which dropping the
+                        // criterion would turn into every message matching the rest
+                        if (flag) {
                             setOpt(attributes, term, flag);
                         }
                     }
@@ -377,12 +402,7 @@ const searchCompiler = (connection, query) => {
                 case 'NOT':
                     if (params[term] && typeof params[term] === 'object') {
                         attributes.push({ type: 'ATOM', value: 'NOT' });
-                        if (Object.keys(params[term]).length > 1) {
-                            walkGrouped(params[term]);
-                        }
-                        else {
-                            walk(params[term]);
-                        }
+                        walkOperand('NOT', params[term]);
                     }
                     break;
                 // OR operator - complex logic for building OR trees
@@ -441,14 +461,7 @@ const searchCompiler = (connection, query) => {
                                 entry.forEach(walkOrTree);
                                 return;
                             }
-                            if (entry && typeof entry === 'object') {
-                                if (Object.keys(entry).length > 1) {
-                                    walkGrouped(entry);
-                                }
-                                else {
-                                    walk(entry);
-                                }
-                            }
+                            walkOperand('OR', entry);
                         };
                         walkOrTree(genOrTree(params[term]));
                     }

package/dist/cjs/tools.js

@@ -816,11 +816,18 @@ async function formatMessageResponse(untagged, mailbox) {
             case 'flags':
                 map.flags = new Set(getArray(attribute));
                 break;
+            // A server with nothing to report can answer ENVELOPE NIL or BODYSTRUCTURE NIL.
+            // The field is left unset then: parsing NIL threw, and the whole message
+            // disappeared from the FETCH result.
             case 'envelope':
-                map.envelope = parseEnvelope(attribute);
+                if (Array.isArray(attribute)) {
+                    map.envelope = parseEnvelope(attribute);
+                }
                 break;
             case 'bodystructure':
-                map.bodyStructure = parseBodystructure(attribute);
+                if (Array.isArray(attribute)) {
+                    map.bodyStructure = parseBodystructure(attribute);
+                }
                 break;
             case 'internaldate': {
                 let value = getString(attribute);

package/dist/esm/commands/list.js

@@ -148,10 +148,12 @@ export default async function list(connection, reference, mailbox, options) {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;
                         }
+                        // A name sent as a literal arrives as a Buffer, so convert it once for both fields
+                        let rawPath = ((untagged.attributes[2] && untagged.attributes[2].value) || '').toString();
                         let entry = {
                             // Decode from modified UTF-7 wire format and normalize the path
-                            path: normalizePath(connection, decodePath(connection, ((untagged.attributes[2] && untagged.attributes[2].value) || ''))),
-                            pathAsListed: ((untagged.attributes[2] && untagged.attributes[2].value) || ''),
+                            path: normalizePath(connection, decodePath(connection, rawPath)),
+                            pathAsListed: rawPath,
                             flags: new Set(getStringList(untagged.attributes[0])),
                             delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
                             listed: true
@@ -379,9 +381,11 @@ export default async function list(connection, reference, mailbox, options) {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;
                         }
+                        // A name sent as a literal arrives as a Buffer, so convert it once for both fields
+                        let rawPath = ((untagged.attributes[2] && untagged.attributes[2].value) || '').toString();
                         let entry = {
-                            path: normalizePath(connection, decodePath(connection, ((untagged.attributes[2] && untagged.attributes[2].value) || ''))),
-                            pathAsListed: ((untagged.attributes[2] && untagged.attributes[2].value) || ''),
+                            path: normalizePath(connection, decodePath(connection, rawPath)),
+                            pathAsListed: rawPath,
                             flags: new Set(getStringList(untagged.attributes[0])),
                             delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
                             subscribed: true
@@ -447,15 +451,23 @@ export default async function list(connection, reference, mailbox, options) {
         // Resolve special-use conflicts. Each type goes to one mailbox and each mailbox gets
         // at most one type. Candidates are taken in priority order across all types (user >
         // extension > name, then alphabetically), so a mailbox claimed by a stronger match
-        // leaves its other type to that type's next candidate instead of to nobody.
+        // leaves its other type to that type's next candidate instead of to nobody. Within a
+        // source a shallower mailbox wins before the alphabetical order is consulted, so that
+        // INBOX.Sent is preferred over INBOX.Archive.Sent.
         let candidates = Object.entries(specialUseMatches).flatMap(([type, matches]) => matches.map(match => ({ type, ...match })));
         candidates.sort((a, b) => {
             let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
             let bSource = SOURCE_SORT_ORDER.indexOf(b.source);
-            if (aSource === bSource) {
-                return a.entry.path.localeCompare(b.entry.path);
+            if (aSource !== bSource) {
+                return aSource - bSource;
             }
-            return aSource - bSource;
+            // parent is set on every listed entry before the candidates are ranked
+            let aDepth = a.entry.parent.length;
+            let bDepth = b.entry.parent.length;
+            if (aDepth !== bDepth) {
+                return aDepth - bDepth;
+            }
+            return a.entry.path.localeCompare(b.entry.path);
         });
         let assignedTypes = new Set();
         for (let { type, entry, source } of candidates) {

package/dist/esm/errors.d.ts

@@ -37,12 +37,14 @@ export declare const ImapFlowErrorCode: {
     readonly InvalidTokenValue: "InvalidTokenValue";
     readonly InvalidTextValue: "InvalidTextValue";
     readonly InvalidSequenceSet: "InvalidSequenceSet";
+    readonly InvalidSearchQuery: "InvalidSearchQuery";
     readonly DownloadOverflow: "DownloadOverflow";
     readonly DownloadIncomplete: "DownloadIncomplete";
     readonly ProxyError: "ProxyError";
     readonly EPROXY: "EPROXY";
     readonly UnsupportedProxyAddress: "UnsupportedProxyAddress";
     readonly ERR_INVALID_URL: "ERR_INVALID_URL";
+    readonly InstanceReused: "InstanceReused";
 };
 /** One of the {@link ImapFlowErrorCode} values */
 export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];

package/dist/esm/errors.js

@@ -41,6 +41,7 @@ export const ImapFlowErrorCode = {
     InvalidTokenValue: 'InvalidTokenValue',
     InvalidTextValue: 'InvalidTextValue',
     InvalidSequenceSet: 'InvalidSequenceSet',
+    InvalidSearchQuery: 'InvalidSearchQuery',
     // download()
     DownloadOverflow: 'DownloadOverflow',
     DownloadIncomplete: 'DownloadIncomplete',
@@ -48,7 +49,9 @@ export const ImapFlowErrorCode = {
     ProxyError: 'ProxyError',
     EPROXY: 'EPROXY',
     UnsupportedProxyAddress: 'UnsupportedProxyAddress',
-    ERR_INVALID_URL: 'ERR_INVALID_URL'
+    ERR_INVALID_URL: 'ERR_INVALID_URL',
+    // API misuse
+    InstanceReused: 'InstanceReused'
 };
 /**
  * Error subclass thrown when IMAP authentication fails.

package/dist/esm/handler/imap-stream.js

@@ -1,5 +1,5 @@
 import { Transform } from 'node:stream';
-import logger from '../logger.js';
+import { createConnectionLogger } from '../logger.js';
 import { MAX_LITERAL_SIZE, MAX_LINE_SIZE, MAX_RESPONSE_SIZE, normalizeLimit, createLiteralTooLargeError } from './limits.js';
 const LINE = 0x01;
 const LITERAL = 0x02;
@@ -30,13 +30,12 @@ export class ImapStream extends Transform {
         });
         this.options = options || {};
         this.cid = this.options.cid;
-        this.log =
-            this.options.logger && typeof this.options.logger === 'object'
-                ? this.options.logger
-                : logger.child({
-                    component: 'imap-connection',
-                    cid: this.cid
-                });
+        if (this.options.logger && typeof this.options.logger === 'object') {
+            this.log = this.options.logger;
+        }
+        else {
+            this.log = createConnectionLogger({ cid: this.cid, logRaw: this.options.logRaw });
+        }
         this.readBytesCounter = 0;
         // Maximum length of a single line (response without a literal). Bounds the line buffer
         // so a server that never sends a line terminator cannot exhaust memory.

package/dist/esm/imap-flow.js

@@ -7,7 +7,7 @@ import crypto from 'node:crypto';
 import zlib from 'node:zlib';
 import { EventEmitter } from 'node:events';
 import { PassThrough } from 'node:stream';
-import logger from './logger.js';
+import { createConnectionLogger } from './logger.js';
 import * as packageInfo from './package-info.js';
 import { ImapStream } from './handler/imap-stream.js';
 import { parser, compiler } from './handler/imap-handler.js';
@@ -1890,9 +1890,17 @@ export class ImapFlow extends EventEmitter {
     async connect() {
         if (this._connectCalled) {
             // Prevent re-using ImapFlow instances by allowing to call connect just once.
-            throw new Error('Can not re-use ImapFlow instance');
+            let err = new Error('Can not re-use ImapFlow instance');
+            err.code = 'InstanceReused';
+            throw err;
         }
         this._connectCalled = true;
+        let closedError = () => this.createNoConnectionError(this.byeReason, { rejectedFrom: 'connect' });
+        // close() already ran, so there is no connection to set up and nothing would ever
+        // settle a connect attempt started now.
+        if (this.isClosed) {
+            throw closedError();
+        }
         // One deadline for the whole attempt, started before anything is resolved or negotiated.
         // Proxy DNS and proxy negotiation used to run entirely outside the timer, so a stalled
         // proxy could hang far beyond the documented connectionTimeout.
@@ -1938,9 +1946,20 @@ export class ImapFlow extends EventEmitter {
                 error._err = err;
                 throw error;
             }
+            // close() during proxy setup found no socket to destroy and no connect to reject,
+            // so the tunnel that just opened is dropped here instead of being handed to a
+            // closed client.
+            if (this.isClosed) {
+                socket.destroy();
+                throw closedError();
+            }
         }
         // Guarded: close() rejects a pending connect() synchronously. See guardedPromise().
         let connectPromise = guardedPromise((resolve, reject) => {
+            // Stored before the transport is up, so a close() that lands before onConnect
+            // still rejects this attempt through closeConnectSteps().
+            this.initialResolve = resolve;
+            this.initialReject = reject;
             // Whatever the proxy phase already used is gone from the budget
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
@@ -1992,9 +2011,6 @@ export class ImapFlow extends EventEmitter {
                     this.setSocketHandlers();
                     this.setEventHandlers();
                     connected.pipe(this.streamer);
-                    // executed by initial "* OK"
-                    this.initialResolve = resolve;
-                    this.initialReject = reject;
                     /* c8 ignore next 4 */ // defensive: the onConnect setup body does not throw under normal operation
                 }
                 catch (ex) {
@@ -2178,7 +2194,10 @@ export class ImapFlow extends EventEmitter {
             this._upgradeReject = null;
             reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
         }
-        if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
+        // A verifyOnly session closes itself with LOGOUT and startSession() settles connect()
+        // with the outcome, so the close is not a failure there. Before the greeting nothing
+        // else can settle it (BYE greeting, FIN, close() while the transport is still coming up).
+        if (typeof this.initialReject === 'function' && (!this.options.verifyOnly || !this.greetingReceived)) {
             clearTimer(this.greetingTimeout);
             let reject = this.initialReject;
             this.initialResolve = false;
@@ -2489,7 +2508,26 @@ export class ImapFlow extends EventEmitter {
      * // 125
      */
     async mailboxOpen(path, options) {
-        return await this.run('SELECT', path, options);
+        try {
+            return await this.run('SELECT', path, options);
+        }
+        catch (err) {
+            if (err.responseStatus === 'NO') {
+                // SELECT failed with NO: verify whether the mailbox exists at all by running
+                // 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) {
+                        err.mailboxMissing = true;
+                    }
+                }
+                catch (E) {
+                    this.log.trace({ msg: 'Failed to verify failed mailbox', path, err: E });
+                }
+            }
+            throw err;
+        }
     }
     /**
      * Closes a previously opened mailbox
@@ -3191,20 +3229,7 @@ export class ImapFlow extends EventEmitter {
                     break; // Wait for this lock to be released
                 }
                 catch (err) {
-                    if (err.responseStatus === 'NO') {
-                        // SELECT failed with NO: verify whether the mailbox exists
-                        // at all by running LIST. This sets mailboxMissing on the error
-                        // so the caller can distinguish "doesn't exist" from other failures.
-                        try {
-                            let folders = await this.run('LIST', '', path, { listOnly: true });
-                            if (!folders || !folders.length) {
-                                err.mailboxMissing = true;
-                            }
-                        }
-                        catch (E) {
-                            this.log.trace({ msg: 'Failed to verify failed mailbox', path, err: E });
-                        }
-                    }
+                    // mailboxOpen() has already marked a missing mailbox (mailboxMissing)
                     this.log.trace({
                         msg: 'Failed to acquire mailbox lock',
                         path,
@@ -3295,12 +3320,14 @@ export class ImapFlow extends EventEmitter {
     }
     /** @internal */
     getLogger() {
-        let mainLogger = this.options.logger && typeof this.options.logger === 'object'
-            ? this.options.logger
-            : logger.child({
-                component: 'imap-connection',
-                cid: this.id
-            });
+        let mainLogger = {};
+        if (this.options.logger && typeof this.options.logger === 'object') {
+            mainLogger = this.options.logger;
+        }
+        else if (this.options.logger !== false) {
+            // {logger:false} never consults mainLogger, so it does not create the default logger
+            mainLogger = createConnectionLogger({ cid: this.id, logRaw: this.options.logRaw });
+        }
         let synteticLogger = {};
         let levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
         for (let level of levels) {

package/dist/esm/logger.d.ts

@@ -1,3 +1,21 @@
-import pino from 'pino';
-declare const logger: pino.Logger<never, boolean>;
-export default logger;
+import { type Logger as PinoLogger } from 'pino';
+/**
+ * Returns the shared default logger, used when a connection is given no logger of its own.
+ * Created on first use, so importing the library does not set up a stdout logger nobody asked
+ * for. Level info: a caller that asks for raw socket data (logRaw) lowers its own child logger
+ * to trace.
+ *
+ * @returns The default pino logger
+ */
+export declare function getDefaultLogger(): PinoLogger;
+/**
+ * Returns the child of the default logger a connection logs through when it was given no
+ * logger of its own.
+ *
+ * @param options - cid is the connection id to stamp on entries, logRaw asks for raw socket data
+ * @returns A child logger of the default logger
+ */
+export declare function createConnectionLogger(options: {
+    cid?: string | undefined;
+    logRaw?: boolean | undefined;
+}): PinoLogger;

package/dist/esm/logger.js

@@ -1,4 +1,34 @@
 import pino from 'pino';
-const logger = pino();
-logger.level = 'trace';
-export default logger;
+let logger = null;
+/**
+ * Returns the shared default logger, used when a connection is given no logger of its own.
+ * Created on first use, so importing the library does not set up a stdout logger nobody asked
+ * for. Level info: a caller that asks for raw socket data (logRaw) lowers its own child logger
+ * to trace.
+ *
+ * @returns The default pino logger
+ */
+export function getDefaultLogger() {
+    if (!logger) {
+        logger = pino({ level: 'info' });
+    }
+    return logger;
+}
+/**
+ * Returns the child of the default logger a connection logs through when it was given no
+ * logger of its own.
+ *
+ * @param options - cid is the connection id to stamp on entries, logRaw asks for raw socket data
+ * @returns A child logger of the default logger
+ */
+export function createConnectionLogger(options) {
+    let child = getDefaultLogger().child({
+        component: 'imap-connection',
+        cid: options.cid
+    });
+    // Raw socket data is logged at trace level, so asking for it lowers the threshold
+    if (options.logRaw) {
+        child.level = 'trace';
+    }
+    return child;
+}

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

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.1.0";
+export declare const version = "2.1.2";
 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.1.0";
+export const version = "2.1.2";
 export const homepage = "https://imapflow.com/";

package/dist/esm/search-compiler.d.ts

@@ -9,7 +9,7 @@ export type SearchAttribute = ImapAttributeNode | SearchAttribute[];
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
- * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param connection - IMAP connection object (capabilities and enabled extensions are read)
  * @param query - Search query object
  * @returns Array of IMAP search attributes
  * @throws {Error} When required server extensions are not available

package/dist/esm/search-compiler.js

@@ -1,5 +1,5 @@
 /* eslint no-control-regex:0 */
-import { formatDate, formatFlag, canUseFlag, toValidDate, isRev2Active } from './tools.js';
+import { formatDate, formatFlag, toValidDate, isRev2Active } from './tools.js';
 /**
  * Sets a boolean flag in the IMAP search attributes.
  * Automatically handles UN- prefixing for falsy values.
@@ -88,6 +88,17 @@ let processDateField = (attributes, term, value) => {
 };
 // Pre-compiled regex for better performance
 const UNICODE_PATTERN = /[^\x00-\x7F]/;
+/**
+ * Throws a coded search compilation error.
+ *
+ * @param code - Error code, one of the ImapFlowErrorCode values
+ * @param message - Error message
+ */
+let fail = (code, message) => {
+    let error = new Error(message);
+    error.code = code;
+    throw error;
+};
 /**
  * Checks if a string contains Unicode characters.
  * Used to determine if CHARSET UTF-8 needs to be specified.
@@ -107,7 +118,7 @@ let isUnicodeString = (str) => {
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
- * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param connection - IMAP connection object (capabilities and enabled extensions are read)
  * @param query - Search query object
  * @returns Array of IMAP search attributes
  * @throws {Error} When required server extensions are not available
@@ -133,21 +144,29 @@ export const searchCompiler = (connection, query) => {
     const attributes = [];
     // Track if we need to specify UTF-8 charset
     let hasUnicode = false;
-    const mailbox = connection.mailbox;
     /**
      * Recursively walks through the query object and builds IMAP attributes.
      * @param params - Query parameters to process
      */
     const walk = (params) => {
-        // Walks a query object and wraps the resulting attributes in a
-        // sub-array so the IMAP compiler emits parentheses around them.
-        // Used when a single search-key is required (NOT, OR operands)
-        // but the condition has multiple keys (RFC 3501 Section 6.4.4).
-        let walkGrouped = (obj) => {
+        // Compiles one NOT or OR operand, which the caller has already put its operator in
+        // front of. An operand with several keys is wrapped in a sub-array so the IMAP compiler
+        // emits parentheses around it, as the operator takes a single search-key
+        // (RFC 3501 Section 6.4.4). An operand that compiles to nothing (an invalid date, an
+        // empty object, ...) is refused: the operator would otherwise bind to whatever
+        // criterion follows it and invert or widen the search.
+        let walkOperand = (operator, obj) => {
             let startIdx = attributes.length;
-            walk(obj);
-            let subAttrs = attributes.splice(startIdx);
-            attributes.push(subAttrs);
+            if (obj && typeof obj === 'object') {
+                walk(obj);
+            }
+            if (attributes.length === startIdx) {
+                fail('InvalidSearchQuery', `Search operand for ${operator} does not include any usable search criteria`);
+            }
+            if (Object.keys(obj).length > 1) {
+                let subAttrs = attributes.splice(startIdx);
+                attributes.push(subAttrs);
+            }
         };
         Object.keys(params || {}).forEach(term => {
             switch (term.toUpperCase()) {
@@ -193,9 +212,7 @@ export const searchCompiler = (connection, query) => {
                         // reject the whole search with a tagged BAD, so fail with a
                         // descriptive error instead
                         if (isRev2Active(connection)) {
-                            let error = new Error(`The "${term.toLowerCase()}" search key does not exist in IMAP4rev2`);
-                            error.code = 'MissingServerExtension';
-                            throw error;
+                            fail('MissingServerExtension', `The "${term.toLowerCase()}" search key does not exist in IMAP4rev2`);
                         }
                         setBoolOpt(attributes, term, true);
                     }
@@ -241,6 +258,11 @@ export const searchCompiler = (connection, query) => {
                         // Fallback to Gmail message ID
                         setOpt(attributes, 'X-GM-MSGID', params[term]);
                     }
+                    else if (params[term]) {
+                        // Dropping the criterion would widen the search to every message
+                        // matching the rest of the query, which a delete or move acts on
+                        fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for EMAILID');
+                    }
                     break;
                 // Thread ID support (OBJECTID or Gmail extension)
                 case 'THREADID':
@@ -251,6 +273,11 @@ export const searchCompiler = (connection, query) => {
                         // Fallback to Gmail thread ID
                         setOpt(attributes, 'X-GM-THRID', params[term]);
                     }
+                    else if (params[term]) {
+                        // Dropping the criterion would widen the search to every message
+                        // matching the rest of the query, which a delete or move acts on
+                        fail('MissingServerExtension', 'Server does not support OBJECTID or X-GM-EXT-1 extension required for THREADID');
+                    }
                     break;
                 // Gmail raw search
                 case 'GMRAW':
@@ -262,9 +289,7 @@ export const searchCompiler = (connection, query) => {
                         setOpt(attributes, 'X-GM-RAW', params[term]);
                     }
                     else {
-                        let error = new Error('Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
-                        error.code = 'MissingServerExtension';
-                        throw error;
+                        fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
                     }
                     break;
                 // Gmail label search. Compiles { has, not } into an X-GM-RAW "label:"/"-label:" query
@@ -298,9 +323,7 @@ export const searchCompiler = (connection, query) => {
                         break;
                     }
                     if (!connection.capabilities.has('X-GM-EXT-1')) {
-                        let error = new Error('Server does not support X-GM-EXT-1 extension required for label search');
-                        error.code = 'MissingServerExtension';
-                        throw error;
+                        fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for label search');
                     }
                     let rawQuery = rawParts.join(' ');
                     if (isUnicodeString(rawQuery)) {
@@ -344,8 +367,10 @@ export const searchCompiler = (connection, query) => {
                 case 'UNKEYWORD':
                     {
                         let flag = formatFlag(params[term]);
-                        // Only add if flag is supported or already exists in mailbox
-                        if (canUseFlag(mailbox, flag) || mailbox.flags.has(flag)) {
+                        // Compiled even when the mailbox does not allow the keyword: the
+                        // correct answer is then the empty set, which dropping the
+                        // criterion would turn into every message matching the rest
+                        if (flag) {
                             setOpt(attributes, term, flag);
                         }
                     }
@@ -374,12 +399,7 @@ export const searchCompiler = (connection, query) => {
                 case 'NOT':
                     if (params[term] && typeof params[term] === 'object') {
                         attributes.push({ type: 'ATOM', value: 'NOT' });
-                        if (Object.keys(params[term]).length > 1) {
-                            walkGrouped(params[term]);
-                        }
-                        else {
-                            walk(params[term]);
-                        }
+                        walkOperand('NOT', params[term]);
                     }
                     break;
                 // OR operator - complex logic for building OR trees
@@ -438,14 +458,7 @@ export const searchCompiler = (connection, query) => {
                                 entry.forEach(walkOrTree);
                                 return;
                             }
-                            if (entry && typeof entry === 'object') {
-                                if (Object.keys(entry).length > 1) {
-                                    walkGrouped(entry);
-                                }
-                                else {
-                                    walk(entry);
-                                }
-                            }
+                            walkOperand('OR', entry);
                         };
                         walkOrTree(genOrTree(params[term]));
                     }

package/dist/esm/tools.js

@@ -761,11 +761,18 @@ export async function formatMessageResponse(untagged, mailbox) {
             case 'flags':
                 map.flags = new Set(getArray(attribute));
                 break;
+            // A server with nothing to report can answer ENVELOPE NIL or BODYSTRUCTURE NIL.
+            // The field is left unset then: parsing NIL threw, and the whole message
+            // disappeared from the FETCH result.
             case 'envelope':
-                map.envelope = parseEnvelope(attribute);
+                if (Array.isArray(attribute)) {
+                    map.envelope = parseEnvelope(attribute);
+                }
                 break;
             case 'bodystructure':
-                map.bodyStructure = parseBodystructure(attribute);
+                if (Array.isArray(attribute)) {
+                    map.bodyStructure = parseBodystructure(attribute);
+                }
                 break;
             case 'internaldate': {
                 let value = getString(attribute);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.1.0",
+    "version": "2.1.2",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -81,12 +81,12 @@
         "wrangler": "4.142.0"
     },
     "dependencies": {
-        "@zone-eu/mailsplit": "5.4.17",
+        "@zone-eu/mailsplit": "5.4.19",
         "encoding-japanese": "2.4.0",
         "iconv-lite": "0.7.3",
-        "libbase64": "1.3.0",
-        "libmime": "5.4.4",
-        "libqp": "2.1.1",
+        "libbase64": "1.3.1",
+        "libmime": "5.4.6",
+        "libqp": "2.1.2",
         "pino": "10.3.1",
         "socks": "2.8.10"
     },