imapflow 1.7.4 → 1.7.6

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.4"
+    ".": "1.7.6"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.7.6](https://github.com/postalsys/imapflow/compare/v1.7.5...v1.7.6) (2026-08-24)
+
+
+### Bug Fixes
+
+* **errors:** stop a re-stamped rejection carrying the previous site's markers ([ffd266c](https://github.com/postalsys/imapflow/commit/ffd266c1459c6f29c5cc2286592a2b2ce88c2706))
+
+## [1.7.5](https://github.com/postalsys/imapflow/compare/v1.7.4...v1.7.5) (2026-08-24)
+
+
+### Bug Fixes
+
+* **errors:** give an IDLE-break waiter its own rejection site ([9534551](https://github.com/postalsys/imapflow/commit/95345519fa32ee26bff239a2ac90f6b8ddccb559))
+
 ## [1.7.4](https://github.com/postalsys/imapflow/compare/v1.7.3...v1.7.4) (2026-08-24)
 
 

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { guardedPromise, hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
+const { guardedPromise, hasCapability, logConnectionError, restampConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -138,9 +138,15 @@ async function runIdle(connection) {
         return;
     } catch (err) {
         logConnectionError(connection, 'IDLE session failed', err);
-        while (preCheckWaitQueue.length) {
-            let { reject } = preCheckWaitQueue.shift();
-            reject(err);
+        if (preCheckWaitQueue.length) {
+            // One error for the whole queue: every waiter failed at the same site, for the same
+            // reason. Built inside the guard so a teardown with nothing queued - the common case -
+            // does not pay for an Error and its stack capture.
+            let waiterError = restampConnectionError(err, { rejectedFrom: 'preCheckWaiter' });
+            while (preCheckWaitQueue.length) {
+                let { reject } = preCheckWaitQueue.shift();
+                reject(waiterError);
+            }
         }
         return false;
     } finally {

package/lib/imap-flow.js

@@ -43,6 +43,7 @@ const {
     parseUintValue,
     isUnsafeKey,
     getStringList,
+    buildConnectionError,
     guardedPromise,
     guardedReject,
     MAX_UINT32_DIGITS
@@ -2539,23 +2540,9 @@ class ImapFlow extends EventEmitter {
         setImmediate(() => this.close());
     }
 
-    // Builds an error describing a connection that is gone. Every such error is stamped here so
-    // the stamping cannot drift between sites: the connection id always travels on it, and each
-    // site names itself through `meta` (`rejectedFrom`, plus the command or mailbox path it
-    // belongs to).
-    //
-    // A stack trace only records where an error was built, and close() hands a rejection to every
-    // pending request and every queued lock in the same tick, so without these an error that
-    // reaches a global unhandledRejection handler arrives with nothing that identifies the
-    // connection it came from, let alone which of the rejected promises carried it.
+    // Connection-scoped wrapper around the shared stamping helper; see buildConnectionError().
     createConnectionError(code, message, meta) {
-        const error = new Error(message);
-        error.code = code;
-        error.cid = this.id;
-        if (meta) {
-            Object.assign(error, meta);
-        }
-        return error;
+        return buildConnectionError(this.id, code, message, meta);
     }
 
     // The standard "connection not available" error, optionally annotated with the server's BYE

package/lib/tools.js

@@ -72,9 +72,74 @@ class AuthenticationFailure extends Error {
 // Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
 const noop = () => {};
 
+// The fields buildConnectionError() stamps to say *where* a connection error was rejected, as
+// opposed to what went wrong. restampConnectionError() clears them, because they belong to the
+// site that built the error rather than to the failure it describes.
+const CONNECTION_ERROR_SITE_KEYS = ['rejectedFrom', 'command', 'path'];
+
 const tools = {
     noop,
 
+    /**
+     * Builds an error describing a connection that is gone, stamped so it can be traced back to
+     * where it came from: the connection id always travels on it, and each site names itself
+     * through `meta` (`rejectedFrom`, plus the command or mailbox path it belongs to).
+     *
+     * A stack trace only records where an error was built, and close() hands a rejection to every
+     * pending request and every queued lock in the same tick, so without these an error that
+     * reaches a global unhandledRejection handler arrives with nothing that identifies the
+     * connection it came from, let alone which of the rejected promises carried it.
+     *
+     * Takes the connection id rather than the connection, so the stamping stays in one place
+     * without every caller having to be a full ImapFlow instance.
+     *
+     * @param {String} cid - Connection id
+     * @param {String} code - Error code, e.g. 'NoConnection'
+     * @param {String} message - Error message
+     * @param {Object} [meta] - Fields to stamp on the error
+     * @returns {Error} The stamped error
+     */
+    buildConnectionError(cid, code, message, meta) {
+        const error = new Error(message);
+        error.code = code;
+        error.cid = cid;
+        if (meta) {
+            Object.assign(error, meta);
+        }
+        return error;
+    },
+
+    /**
+     * Re-stamps an existing connection error for a different rejection site.
+     *
+     * The same failure can be handed to more than one promise - close() rejects the in-flight
+     * command, and runIdle() then rejects everything queued behind it - and each of those is a
+     * separate promise with a separate consumer. Sharing one error object reports whichever of
+     * them escapes under the first site's marker, which is the attribution these markers exist to
+     * give.
+     *
+     * Everything describing *what went wrong* is carried over, because a re-stamped error reaches
+     * user code through run() and callers branch on `responseStatus`, `serverResponseCode` and
+     * friends. Everything describing *where it was rejected* is dropped, because the new site owns
+     * those and a leftover `command` from the previous site is exactly as misleading as a leftover
+     * `rejectedFrom`. The original travels on as `cause`.
+     *
+     * @param {Error} err - The error being re-stamped
+     * @param {Object} meta - Fields for the new site, e.g. { rejectedFrom: 'preCheckWaiter' }
+     * @returns {Error} A separate error describing the same failure at the new site
+     */
+    restampConnectionError(err, meta) {
+        let error = tools.buildConnectionError(err.cid, err.code, err.message, err);
+        for (let key of CONNECTION_ERROR_SITE_KEYS) {
+            delete error[key];
+        }
+        if (meta) {
+            Object.assign(error, meta);
+        }
+        error.cause = err;
+        return error;
+    },
+
     /**
      * Creates a promise whose rejection is observed as soon as it exists.
      *

package/package.json

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

package/test/unhandled-rejection-test.js

@@ -101,6 +101,59 @@ function installRejectionDetector(test) {
     };
 }
 
+// Drives a connection to the one state both IDLE-waiter tests need: IDLE issued but never
+// acknowledged with a "+", so preCheck() cannot send DONE and anything it queues stays queued
+// until close() tears the IDLE command down. Hands the connected client to `run`, and always
+// closes the server so the test ends.
+function withQueuedIdleWaiter(test, options, run, onError) {
+    const server = createMockServer({
+        extraCapabilities: 'IDLE',
+        onCommand(socket, tag, command) {
+            if (command === 'IDLE') {
+                return true;
+            }
+        }
+    });
+
+    server.listen(0, '127.0.0.1', async () => {
+        const client = new ImapFlow(
+            Object.assign(
+                {
+                    host: '127.0.0.1',
+                    port: server.address().port,
+                    secure: false,
+                    logger: false,
+                    disableAutoIdle: true,
+                    auth: { user: 'test', pass: 'test' }
+                },
+                options
+            )
+        );
+
+        try {
+            await client.connect();
+            await client.mailboxOpen('INBOX');
+
+            client.idle().catch(() => {
+                // Expected: IDLE rejects when the connection is closed
+            });
+
+            // Let the IDLE command reach the server and install preCheck()
+            await new Promise(r => setTimeout(r, 100));
+            test.equal(typeof client.preCheck, 'function', 'IDLE should have installed preCheck()');
+
+            await run(client);
+        } catch (err) {
+            if (onError) {
+                onError(err);
+            }
+            test.ok(false, 'Unexpected error: ' + err.message);
+        } finally {
+            server.close(() => test.done());
+        }
+    });
+}
+
 exports['Unhandled Rejection Prevention'] = {
     'exec() + close() race should not cause unhandled rejection'(test) {
         test.expect(2);
@@ -439,65 +492,47 @@ exports['Unhandled Rejection Prevention'] = {
         }, 100);
     },
 
-    'preCheck() waiter rejected by close() should not cause unhandled rejection'(test) {
-        test.expect(2);
-
-        // Never acknowledge IDLE with a "+" continuation. preCheck() can only send DONE once
-        // the server has acknowledged, so its waiter stays queued until close() tears the
-        // IDLE command down and runIdle() rejects everything still waiting.
-        const server = createMockServer({
-            extraCapabilities: 'IDLE',
-            onCommand(socket, tag, command) {
-                if (command === 'IDLE') {
-                    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,
-                disableAutoIdle: true,
-                auth: {
-                    user: 'test',
-                    pass: 'test'
-                }
-            });
+    'a preCheck() waiter rejection names its own site, not the IDLE command'(test) {
+        test.expect(8);
 
-            const detector = installRejectionDetector(test);
+        withQueuedIdleWaiter(test, { id: 'waiter-cid' }, async client => {
+            let waiter = client.preCheck();
+            client.close();
 
             try {
-                await client.connect();
-                await client.mailboxOpen('INBOX');
+                await waiter;
+                test.ok(false, 'the waiter should have rejected');
+            } catch (err) {
+                test.equal(err.rejectedFrom, 'preCheckWaiter', 'the waiter names its own rejection site');
+                test.equal(err.cid, 'waiter-cid', 'the waiter error carries the connection id');
+                test.equal(err.code, 'NoConnection', 'the original code is preserved for callers that branch on it');
+                test.strictEqual(err.command, undefined, 'the command belongs to the site the error came from, not to the waiter');
+                test.ok(err.cause, 'the command failure travels on as the cause');
+                test.equal(err.cause.rejectedFrom, 'pendingRequest', 'the cause still names the command site');
+                test.equal(err.cause.command, 'IDLE', 'the cause still names the command');
+            }
+        });
+    },
 
-                client.idle().catch(() => {
-                    // Expected: IDLE rejects when the connection is closed
-                });
+    'preCheck() waiter rejected by close() should not cause unhandled rejection'(test) {
+        test.expect(2);
 
-                // Let the IDLE command reach the server and install preCheck()
-                await new Promise(r => setTimeout(r, 100));
-                test.equal(typeof client.preCheck, 'function', 'IDLE should have installed preCheck()');
+        const detector = installRejectionDetector(test);
 
-                // Request an IDLE break and drop the returned promise on the floor, so the
-                // queued waiter has no handler of its own when close() rejects it
+        withQueuedIdleWaiter(
+            test,
+            {},
+            async client => {
+                // Request an IDLE break and drop the returned promise on the floor, so the queued
+                // waiter has no handler of its own when close() rejects it
                 client.preCheck();
-
                 client.close();
 
                 await new Promise(r => setTimeout(r, 100));
                 detector.check();
-            } catch (err) {
-                detector.check();
-                test.ok(false, 'Unexpected error: ' + err.message);
-            } finally {
-                server.close(() => test.done());
-            }
-        });
+            },
+            () => detector.check()
+        );
     },
 
     'BAD response to FETCH should not cause unhandled rejection (Death 2)'(test) {