imapflow 1.2.14 → 1.2.16

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.2.14"
+    ".": "1.2.16"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.2.16](https://github.com/postalsys/imapflow/compare/v1.2.15...v1.2.16) (2026-03-19)
+
+
+### Bug Fixes
+
+* parenthesize compound OR/NOT search conditions (RFC 3501) ([347f668](https://github.com/postalsys/imapflow/commit/347f66827ea089acab88aa78485752d84b7b7f3d)), closes [#106](https://github.com/postalsys/imapflow/issues/106)
+
+## [1.2.15](https://github.com/postalsys/imapflow/compare/v1.2.14...v1.2.15) (2026-03-16)
+
+
+### Bug Fixes
+
+* replace setImmediate with synchronous rejection in close() ([8807221](https://github.com/postalsys/imapflow/commit/8807221b2b3bae55848129b6a4b8d08880ae5de8))
+
 ## [1.2.14](https://github.com/postalsys/imapflow/compare/v1.2.13...v1.2.14) (2026-03-15)
 
 

package/lib/imap-flow.js

@@ -585,7 +585,7 @@ class ImapFlow extends EventEmitter {
         });
 
         // Prevent unhandled promise rejection if close() rejects this request
-        // via setImmediate before the caller's handler is attached. The rejection
+        // synchronously before the caller's handler is attached. The rejection
         // still propagates normally to the caller's await/.catch().
         promise.catch(noop);
 
@@ -1728,7 +1728,7 @@ class ImapFlow extends EventEmitter {
         });
 
         // Prevent unhandled promise rejection if close() rejects the connect
-        // promise via setImmediate. The rejection still propagates to the caller.
+        // promise synchronously. The rejection still propagates to the caller.
         connectPromise.catch(noop);
 
         await connectPromise;
@@ -1784,9 +1784,10 @@ class ImapFlow extends EventEmitter {
                 this.initialReject = false;
                 let err = new Error('Unexpected close');
                 err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
-                // Reject via setImmediate so the rest of close() cleanup runs first.
-                // The caller's connect() promise will reject after sockets are torn down.
-                setImmediate(() => reject(err));
+                // Synchronous rejection is safe: connectPromise.catch(noop) is already
+                // attached, so the rejection is observed immediately. close() is synchronous,
+                // so all cleanup completes before any microtask rejection handler runs.
+                reject(err);
             }
 
             if (typeof this.preCheck === 'function') {
@@ -1828,32 +1829,27 @@ class ImapFlow extends EventEmitter {
                 return error;
             };
 
-            // Reject pending requests via setImmediate so this synchronous close()
-            // method finishes first. This prevents unhandled promise rejections that
-            // would occur if we rejected inline before callers set up .catch() handlers.
-            if (pendingRequests.length) {
-                let byeReason = this.byeReason;
-                setImmediate(() => {
-                    for (let request of pendingRequests) {
-                        request.reject(createNoConnectionError(byeReason));
-                    }
-                });
+            // Reject pending requests and locks synchronously. Each exec() and
+            // getMailboxLock() promise already has .catch(noop) attached, so the
+            // rejection is observed immediately and will not trigger
+            // unhandledRejection. close() is synchronous, so all remaining cleanup
+            // runs before any microtask rejection handler fires.
+            let byeReason = this.byeReason;
+
+            for (let request of pendingRequests) {
+                request.reject(createNoConnectionError(byeReason));
             }
 
             // Clear current lock - holder will see errors when they try operations
             this.currentLock = false;
 
-            // Reject pending mailbox locks via setImmediate for consistency
             if (this.locks && this.locks.length) {
-                let byeReason = this.byeReason;
                 let pendingLocks = this.locks.splice(0); // Take all locks and clear the array
-                setImmediate(() => {
-                    for (let lock of pendingLocks) {
-                        if (typeof lock.reject === 'function') {
-                            lock.reject(createNoConnectionError(byeReason));
-                        }
+                for (let lock of pendingLocks) {
+                    if (typeof lock.reject === 'function') {
+                        lock.reject(createNoConnectionError(byeReason));
                     }
-                });
+                }
             }
 
             // cleanup compression streams if they exist
@@ -3634,7 +3630,7 @@ class ImapFlow extends EventEmitter {
         });
 
         // Prevent unhandled promise rejection if close() rejects this lock
-        // via setImmediate. The rejection still propagates to the caller.
+        // synchronously. The rejection still propagates to the caller.
         lockPromise.catch(noop);
 
         return lockPromise;

package/lib/search-compiler.js

@@ -142,6 +142,17 @@ module.exports.searchCompiler = (connection, query) => {
      * @param {Object} 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 => {
+            let startIdx = attributes.length;
+            walk(obj);
+            let subAttrs = attributes.splice(startIdx);
+            attributes.push(subAttrs);
+        };
+
         Object.keys(params || {}).forEach(term => {
             switch (term.toUpperCase()) {
                 // Custom sequence range support (non-standard)
@@ -318,8 +329,11 @@ module.exports.searchCompiler = (connection, query) => {
                 case 'NOT':
                     if (params[term] && typeof params[term] === 'object') {
                         attributes.push({ type: 'ATOM', value: 'NOT' });
-                        // Recursively process NOT conditions
-                        walk(params[term]);
+                        if (Object.keys(params[term]).length > 1) {
+                            walkGrouped(params[term]);
+                        } else {
+                            walk(params[term]);
+                        }
                     }
                     break;
 
@@ -388,7 +402,6 @@ module.exports.searchCompiler = (connection, query) => {
                          */
                         let walkOrTree = entry => {
                             if (Array.isArray(entry)) {
-                                // Only add OR for multiple items
                                 if (entry.length > 1) {
                                     attributes.push({ type: 'ATOM', value: 'OR' });
                                 }
@@ -396,7 +409,11 @@ module.exports.searchCompiler = (connection, query) => {
                                 return;
                             }
                             if (entry && typeof entry === 'object') {
-                                walk(entry);
+                                if (Object.keys(entry).length > 1) {
+                                    walkGrouped(entry);
+                                } else {
+                                    walk(entry);
+                                }
                             }
                         };
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.2.14",
+    "version": "1.2.16",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -48,7 +48,7 @@
         "libbase64": "1.3.0",
         "libmime": "5.3.7",
         "libqp": "2.1.1",
-        "nodemailer": "8.0.2",
+        "nodemailer": "8.0.3",
         "pino": "10.3.1",
         "socks": "2.8.7"
     }

package/test/connection-edge-cases-test.js

@@ -863,7 +863,7 @@ module.exports['Connection Edge: Close with empty locks array'] = test => {
     test.done();
 };
 
-module.exports['Connection Edge: Lock rejection is deferred via setImmediate'] = test => {
+module.exports['Connection Edge: Lock rejection happens synchronously during close'] = test => {
     let client = new ImapFlow({
         host: 'imap.example.com',
         port: 993,
@@ -871,7 +871,6 @@ module.exports['Connection Edge: Lock rejection is deferred via setImmediate'] =
     });
 
     let rejectionTime = null;
-    let closeTime = null;
 
     client.locks = [
         {
@@ -888,16 +887,10 @@ module.exports['Connection Edge: Lock rejection is deferred via setImmediate'] =
     client.usable = true;
 
     client.close();
-    closeTime = Date.now();
 
-    // Rejection should not have happened yet (synchronously)
-    test.equal(rejectionTime, null, 'Rejection should be deferred');
-
-    setImmediate(() => {
-        test.ok(rejectionTime !== null, 'Rejection should happen after setImmediate');
-        test.ok(rejectionTime >= closeTime, 'Rejection should happen after close()');
-        test.done();
-    });
+    // Rejection should have happened synchronously during close()
+    test.ok(rejectionTime !== null, 'Rejection should happen synchronously during close()');
+    test.done();
 };
 
 module.exports['Connection Edge: Pending requests and locks both rejected on close'] = test => {
@@ -940,11 +933,10 @@ module.exports['Connection Edge: Pending requests and locks both rejected on clo
 
     client.close();
 
-    setImmediate(() => {
-        test.ok(requestRejected, 'Pending request should be rejected');
-        test.ok(lockRejected, 'Pending lock should be rejected');
-        test.done();
-    });
+    // Rejections happen synchronously during close()
+    test.ok(requestRejected, 'Pending request should be rejected');
+    test.ok(lockRejected, 'Pending lock should be rejected');
+    test.done();
 };
 
 module.exports['Connection Edge: exec throws NoConnection when in LOGOUT state'] = async test => {

package/test/search-compiler-test.js

@@ -15,9 +15,19 @@ let createMockConnection = (options = {}) => ({
     mailbox: options.mailbox || createMockMailbox()
 });
 
-// Helper to find attribute by value
-let findAttr = (attrs, value) => attrs.find(a => a.value === value);
-let hasAttr = (attrs, value) => attrs.some(a => a.value === value);
+// Helper to find attribute by value (recurses into sub-arrays for parenthesized groups)
+let findAttr = (attrs, value) => {
+    for (let a of attrs) {
+        if (Array.isArray(a)) {
+            let found = findAttr(a, value);
+            if (found) return found;
+        } else if (a.value === value) {
+            return a;
+        }
+    }
+    return undefined;
+};
+let hasAttr = (attrs, value) => !!findAttr(attrs, value);
 
 // ============================================
 // Basic functionality tests
@@ -659,6 +669,10 @@ module.exports['Search Compiler: NOT with nested conditions'] = test => {
     test.ok(hasAttr(compiled, 'NOT'));
     test.ok(hasAttr(compiled, 'SEEN'));
     test.ok(hasAttr(compiled, 'FROM'));
+    // Compound NOT conditions should be wrapped in a sub-array (parenthesized)
+    // so the server treats them as a single search-key
+    test.equal(compiled[0].value, 'NOT');
+    test.ok(Array.isArray(compiled[1]), 'compound NOT should be parenthesized');
     test.done();
 };
 
@@ -899,6 +913,70 @@ module.exports['Search Compiler: OR with 5 conditions produces 4 OR atoms'] = te
     test.done();
 };
 
+module.exports['Search Compiler: OR with compound conditions wraps in parentheses'] = test => {
+    let connection = createMockConnection();
+    let compiled = searchCompiler(connection, {
+        or: [
+            { to: 'a@example.com', from: 'b@example.com' },
+            { to: 'c@example.com', from: 'd@example.com' }
+        ]
+    });
+
+    // OR should be present
+    test.equal(compiled[0].value, 'OR');
+    // Each compound condition should be a sub-array (parenthesized)
+    test.ok(Array.isArray(compiled[1]), 'first compound operand should be parenthesized');
+    test.ok(Array.isArray(compiled[2]), 'second compound operand should be parenthesized');
+    // Check contents of parenthesized groups
+    test.ok(hasAttr(compiled[1], 'TO'), 'first group should have TO');
+    test.ok(hasAttr(compiled[1], 'FROM'), 'first group should have FROM');
+    test.ok(hasAttr(compiled[2], 'TO'), 'second group should have TO');
+    test.ok(hasAttr(compiled[2], 'FROM'), 'second group should have FROM');
+    test.done();
+};
+
+module.exports['Search Compiler: OR with single-key conditions stays flat'] = test => {
+    let connection = createMockConnection();
+    let compiled = searchCompiler(connection, {
+        or: [{ from: 'a@example.com' }, { from: 'b@example.com' }]
+    });
+
+    // Single-key conditions should not be wrapped in sub-arrays
+    test.equal(compiled[0].value, 'OR');
+    test.ok(!Array.isArray(compiled[1]), 'single-key operand should not be parenthesized');
+    test.equal(compiled[1].value, 'FROM');
+    test.done();
+};
+
+module.exports['Search Compiler: OR with 5 compound conditions from issue #106'] = test => {
+    let connection = createMockConnection();
+    let compiled = searchCompiler(connection, {
+        or: [
+            { to: 'myemail@domain.com', from: '@anotherdomain.com' },
+            { to: 'myemail@domain.com', from: '@aseconddomain.com' },
+            { to: 'myemail@domain.com', from: '@athirddomain.fr' },
+            { to: 'anotheremail@domain.com', from: '@anotherdomain.fr' },
+            { to: 'anotheremail@domain.com', from: '@aseconddomain.com' }
+        ]
+    });
+
+    // 5 conditions need 4 OR atoms
+    let orCount = compiled.filter(a => a.value === 'OR').length;
+    test.equal(orCount, 4, 'should have exactly 4 OR atoms for 5 conditions');
+
+    // All compound conditions should be parenthesized (sub-arrays)
+    let subArrays = compiled.filter(a => Array.isArray(a));
+    test.equal(subArrays.length, 5, 'should have 5 parenthesized groups');
+
+    // Each group should contain both TO and FROM
+    subArrays.forEach((group, i) => {
+        test.ok(hasAttr(group, 'TO'), 'group ' + i + ' should have TO');
+        test.ok(hasAttr(group, 'FROM'), 'group ' + i + ' should have FROM');
+    });
+
+    test.done();
+};
+
 // ============================================
 // Unicode CHARSET in HEADER searches
 // ============================================

package/test/unhandled-rejection-test.js

@@ -3,10 +3,11 @@
 /**
  * Tests for unhandled rejection prevention.
  *
- * When close() runs, it rejects pending promises via setImmediate. Without
- * guards, the rejection can fire before the caller's handler is attached,
- * causing Node.js unhandledRejection. These tests verify that no unhandled
- * rejections escape while the caller still receives the expected error.
+ * When close() runs, it rejects pending promises synchronously. exec() and
+ * getMailboxLock() attach .catch(noop) before returning, so the rejection is
+ * observed immediately and does not trigger Node.js unhandledRejection.
+ * These tests verify that no unhandled rejections escape while the caller
+ * still receives the expected error.
  *
  * Key fix: exec() and getMailboxLock() are non-async, returning the promise
  * directly (with .catch(noop)), so the caller gets the same promise object
@@ -18,8 +19,13 @@
 const net = require('net');
 const { ImapFlow } = require('../lib/imap-flow');
 
-// Create a simple mock IMAP server
-function createMockServer() {
+// Create a mock IMAP server with optional custom behavior.
+// options.extraCapabilities - additional capabilities (e.g., 'IDLE')
+// options.onCommand(socket, tag, command) - custom handler; return true if handled
+function createMockServer(options) {
+    const extraCaps = options && options.extraCapabilities ? ' ' + options.extraCapabilities : '';
+    const onCommand = options && options.onCommand;
+
     const server = net.createServer(socket => {
         socket.write('* OK Mock IMAP Server ready\r\n');
 
@@ -34,8 +40,12 @@ function createMockServer() {
                 const tag = parts[0];
                 const command = parts[1] ? parts[1].toUpperCase() : '';
 
+                if (onCommand && onCommand(socket, tag, command, line)) {
+                    continue;
+                }
+
                 if (command === 'CAPABILITY') {
-                    socket.write('* CAPABILITY IMAP4rev1 AUTH=PLAIN\r\n');
+                    socket.write(`* CAPABILITY IMAP4rev1 AUTH=PLAIN${extraCaps}\r\n`);
                     socket.write(`${tag} OK CAPABILITY completed\r\n`);
                 } else if (command === 'LOGIN') {
                     socket.write(`${tag} OK LOGIN completed\r\n`);
@@ -53,6 +63,12 @@ function createMockServer() {
                 } else if (command === 'ID') {
                     socket.write('* ID NIL\r\n');
                     socket.write(`${tag} OK ID completed\r\n`);
+                } else if (command === 'SELECT' || command === 'EXAMINE') {
+                    socket.write('* 1 EXISTS\r\n');
+                    socket.write('* 1 RECENT\r\n');
+                    socket.write('* OK [UIDVALIDITY 1] UIDs valid\r\n');
+                    socket.write('* OK [UIDNEXT 2] Predicted next UID\r\n');
+                    socket.write(`${tag} OK SELECT completed\r\n`);
                 } else if (command === 'NOOP') {
                     socket.write(`${tag} OK NOOP completed\r\n`);
                 } else if (tag && command) {
@@ -103,9 +119,8 @@ exports['Unhandled Rejection Prevention'] = {
         const detector = installRejectionDetector(test);
 
         // Create a pending request, then immediately close.
-        // close() rejects the request via setImmediate. Without the fix,
-        // trySend()'s async chain rejects the promise through a microtask
-        // before the caller's handler is attached.
+        // close() rejects the request synchronously. The .catch(noop) on the
+        // exec() promise ensures the rejection is observed immediately.
         let promise = client.exec('NOOP');
         client.close();
 
@@ -246,7 +261,7 @@ exports['Unhandled Rejection Prevention'] = {
                 await client.connect();
 
                 // Request a lock, then immediately close before it resolves.
-                // close() rejects pending locks via setImmediate.
+                // close() rejects pending locks synchronously.
                 let lockPromise = client.getMailboxLock('INBOX');
                 client.close();
 
@@ -323,5 +338,129 @@ exports['Unhandled Rejection Prevention'] = {
                 }
             );
         });
+    },
+
+    'BYE during IDLE should not cause unhandled rejection (Death 1)'(test) {
+        test.expect(2);
+
+        const server = createMockServer({
+            extraCapabilities: 'IDLE',
+            onCommand(socket, tag, command) {
+                if (command === 'IDLE') {
+                    socket.write('+ idling\r\n');
+                    // After a short delay, send BYE and close (simulates token expiry)
+                    setTimeout(() => {
+                        try {
+                            socket.write('* BYE Session invalidated - AccessTokenExpired\r\n');
+                            socket.end();
+                        } catch {
+                            // socket may already be closed
+                        }
+                    }, 50);
+                    return true;
+                }
+            }
+        });
+
+        server.listen(0, '127.0.0.1', async () => {
+            const port = server.address().port;
+
+            const client = new ImapFlow({
+                host: '127.0.0.1',
+                port,
+                secure: false,
+                logger: false,
+                auth: {
+                    user: 'test',
+                    pass: 'test'
+                }
+            });
+
+            const detector = installRejectionDetector(test);
+
+            try {
+                await client.connect();
+                await client.mailboxOpen('INBOX');
+
+                // Start IDLE and wait for the BYE-triggered close
+                await new Promise((resolve, reject) => {
+                    client.idle().catch(() => {
+                        // Expected: IDLE rejects when BYE arrives
+                    });
+
+                    client.on('close', () => {
+                        // Wait for any deferred unhandled rejections to surface
+                        setTimeout(resolve, 100);
+                    });
+
+                    // Safety timeout
+                    setTimeout(() => reject(new Error('Timeout waiting for close')), 5000);
+                });
+
+                detector.check();
+                test.ok(true, 'No unhandled rejection during IDLE + BYE');
+            } catch (err) {
+                detector.check();
+                test.ok(false, 'Unexpected error: ' + err.message);
+            } finally {
+                server.close(() => test.done());
+            }
+        });
+    },
+
+    'BAD response to FETCH should not cause unhandled rejection (Death 2)'(test) {
+        test.expect(3);
+
+        const server = createMockServer({
+            onCommand(socket, tag, command) {
+                if (command === 'UID' || command === 'FETCH') {
+                    // Simulate "Server Unavailable" error for any FETCH variant
+                    socket.write(`${tag} BAD Server Unavailable. 15\r\n`);
+                    return true;
+                }
+            }
+        });
+
+        server.listen(0, '127.0.0.1', async () => {
+            const port = server.address().port;
+
+            const client = new ImapFlow({
+                host: '127.0.0.1',
+                port,
+                secure: false,
+                logger: false,
+                auth: {
+                    user: 'test',
+                    pass: 'test'
+                }
+            });
+
+            const detector = installRejectionDetector(test);
+
+            try {
+                await client.connect();
+                await client.mailboxOpen('INBOX');
+
+                // Attempt a FETCH that will get BAD response
+                try {
+                    await client.fetchOne('*', { uid: true }, { uid: true });
+                    test.ok(false, 'fetchOne should have rejected');
+                } catch (err) {
+                    test.equal(err.message, 'Command failed', 'Should get Command failed error');
+                    test.equal(err.responseStatus, 'BAD', 'Response status should be BAD');
+                }
+
+                // Wait for any deferred unhandled rejections
+                await new Promise(r => setTimeout(r, 100));
+                detector.check();
+
+                client.close();
+            } catch (err) {
+                detector.check();
+                test.ok(false, 'Unexpected error: ' + err.message);
+            } finally {
+                server.close(() => test.done());
+            }
+        });
     }
 };