imapflow 1.7.4 → 1.7.5

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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 { buildConnectionError, guardedPromise, hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -27,6 +27,27 @@ function claimIdling(connection) {
     };
 }
 
+/**
+ * Builds the rejection a queued IDLE-break waiter receives when the IDLE command itself fails.
+ *
+ * The waiters are separate promises with separate consumers, so handing them the command's own
+ * error would report a waiter that escapes as `rejectedFrom: 'pendingRequest'` - the site where
+ * the IDLE command was rejected, not the site where the waiter was. That is precisely the
+ * attribution the markers exist to give. Every own field of the original is carried over, because
+ * a waiter rejection reaches callers through run() and they branch on `responseStatus`,
+ * `serverResponseCode` and friends; only the site marker differs, and the original travels on as
+ * `cause` so the command failure behind it stays visible.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {Error} err - The error that failed the IDLE command
+ * @returns {Error} Error stamped for the waiter site
+ */
+function preCheckWaiterError(connection, err) {
+    let error = buildConnectionError(connection.id, err.code, err.message, Object.assign({}, err, { rejectedFrom: 'preCheckWaiter' }));
+    error.cause = err;
+    return error;
+}
+
 /**
  * Runs a single IDLE session on the connection.
  *
@@ -140,7 +161,7 @@ async function runIdle(connection) {
         logConnectionError(connection, 'IDLE session failed', err);
         while (preCheckWaitQueue.length) {
             let { reject } = preCheckWaitQueue.shift();
-            reject(err);
+            reject(preCheckWaiterError(connection, err));
         }
         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

@@ -75,6 +75,35 @@ const noop = () => {};
 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;
+    },
+
     /**
      * 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.5",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/unhandled-rejection-test.js

@@ -439,6 +439,68 @@ exports['Unhandled Rejection Prevention'] = {
         }, 100);
     },
 
+    'a preCheck() waiter rejection names its own site, not the IDLE command'(test) {
+        test.expect(6);
+
+        // IDLE is never acknowledged with a "+", so preCheck() cannot send DONE and its waiter
+        // stays queued until close() tears the IDLE command down.
+        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,
+                id: 'waiter-cid',
+                auth: {
+                    user: 'test',
+                    pass: 'test'
+                }
+            });
+
+            try {
+                await client.connect();
+                await client.mailboxOpen('INBOX');
+
+                client.idle().catch(() => {
+                    // Expected: IDLE rejects when the connection is closed
+                });
+
+                await new Promise(r => setTimeout(r, 100));
+
+                let waiter = client.preCheck();
+                client.close();
+
+                try {
+                    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.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');
+                }
+            } catch (err) {
+                test.ok(false, 'Unexpected error: ' + err.message);
+            } finally {
+                server.close(() => test.done());
+            }
+        });
+    },
+
     'preCheck() waiter rejected by close() should not cause unhandled rejection'(test) {
         test.expect(2);