imapflow 1.2.14 → 1.2.15

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.2.14",
+    "version": "1.2.15",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

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