imapflow 1.7.3 → 1.7.5

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* **search:** normalize search dates so invalid values cannot throw or emit NaN ([bf6c6bb](https://github.com/postalsys/imapflow/commit/bf6c6bb9c9e649ac9c28eba2c42f744b7d7d8e63)), closes [#385](https://github.com/postalsys/imapflow/issues/385)
+
 ## [1.7.3](https://github.com/postalsys/imapflow/compare/v1.7.2...v1.7.3) (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/search-compiler.js

@@ -2,7 +2,7 @@
 
 'use strict';
 
-const { formatDate, formatFlag, canUseFlag, isDate, isRev2Active } = require('./tools.js');
+const { formatDate, formatFlag, canUseFlag, toValidDate, isRev2Active } = require('./tools.js');
 
 /**
  * Sets a boolean flag in the IMAP search attributes.
@@ -71,15 +71,25 @@ let setOpt = (attributes, term, value) => {
  *
  * @param {Array} attributes - Array to append the attribute to
  * @param {string} term - The date search term (e.g., 'BEFORE', 'SINCE')
- * @param {*} value - Date value to format
+ * @param {Date|String} value - Date value to format
  */
 let processDateField = (attributes, term, value) => {
-    if (['BEFORE', 'SENTBEFORE'].includes(term.toUpperCase()) && isDate(value) && value.toISOString().substring(11) !== '00:00:00.000Z') {
+    // Normalize first. A Date brand check is not enough on its own: an invalid
+    // Date is still a Date and toISOString() throws on it. Normalizing here also
+    // means a date string behaves exactly like the equivalent Date object.
+    value = toValidDate(value);
+    if (!value) {
+        return;
+    }
+
+    if (['BEFORE', 'SENTBEFORE'].includes(term.toUpperCase()) && value.toISOString().substring(11) !== '00:00:00.000Z') {
         // Set to next day to include current day as well, othwerise BEFORE+AFTER
         // searches for the same day but different time values do not match anything
         value = new Date(value.getTime() + 24 * 3600 * 1000);
     }
 
+    // Still reachable after the guard above: the +24h shift can push a near-max
+    // Date past the representable range
     let date = formatDate(value);
     if (!date) {
         return;
@@ -338,18 +348,25 @@ module.exports.searchCompiler = (connection, query) => {
                 case 'BEFORE':
                 case 'SINCE':
                     {
+                        // Normalize above the capability check so the WITHIN shortcut
+                        // and the standard path agree on what counts as a usable date
+                        let value = toValidDate(params[term]);
+                        if (!value) {
+                            break;
+                        }
+
                         // Use WITHIN extension for better timezone handling if available
-                        if (connection.capabilities.has('WITHIN') && isDate(params[term])) {
+                        if (connection.capabilities.has('WITHIN')) {
                             // Convert to seconds ago from now
                             const now = Date.now();
-                            const withinSeconds = Math.round(Math.max(0, now - params[term].getTime()) / 1000);
+                            const withinSeconds = Math.round(Math.max(0, now - value.getTime()) / 1000);
                             const withinKeyword = term.toUpperCase() === 'BEFORE' ? 'OLDER' : 'YOUNGER';
                             setOpt(attributes, withinKeyword, withinSeconds.toString());
                             break;
                         }
 
                         // Fallback to standard date search
-                        processDateField(attributes, term, params[term]);
+                        processDateField(attributes, term, value);
                     }
                     break;
 

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.3",
+    "version": "1.7.5",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/search-compiler-test.js

@@ -710,6 +710,57 @@ module.exports['Search Compiler: Date with invalid value ignored'] = test => {
     test.done();
 };
 
+module.exports['Search Compiler: all date keys ignore an invalid Date object'] = test => {
+    // An invalid Date is still a Date, so a plain Date brand check let it through:
+    // BEFORE/SENTBEFORE threw RangeError from toISOString(), and with WITHIN
+    // advertised BEFORE/SINCE compiled a literal "OLDER NaN"/"YOUNGER NaN" token
+    for (let capabilities of [[['IMAP4rev1', true]], [['WITHIN', true]]]) {
+        for (let key of ['before', 'since', 'on', 'sentBefore', 'sentOn', 'sentSince']) {
+            let connection = createMockConnection({ capabilities });
+            let compiled = searchCompiler(connection, { [key]: new Date('not-a-date') });
+
+            test.deepEqual(compiled, [], `${key} should compile to no attributes`);
+        }
+    }
+
+    test.done();
+};
+
+module.exports['Search Compiler: invalid date drops only its own criterion'] = test => {
+    let connection = createMockConnection();
+    let compiled = searchCompiler(connection, { seen: true, before: new Date('not-a-date') });
+
+    test.deepEqual(compiled, [{ type: 'ATOM', value: 'SEEN' }]);
+    test.done();
+};
+
+module.exports['Search Compiler: date string and Date object compile alike for BEFORE'] = test => {
+    let asDate = searchCompiler(createMockConnection(), { before: new Date('2023-06-15T12:30:00.000Z') });
+    let asString = searchCompiler(createMockConnection(), { before: '2023-06-15T12:30:00.000Z' });
+
+    // Both input forms are documented, so both must get the +24h shift that makes
+    // same-day BEFORE+SINCE ranges match. The string form used to skip it.
+    test.deepEqual(asString, asDate);
+    test.ok(hasAttr(asString, '16-Jun-2023'));
+    test.done();
+};
+
+module.exports['Search Compiler: date string and Date object compile alike for WITHIN'] = test => {
+    let connection = createMockConnection({ capabilities: [['WITHIN', true]] });
+    let recentDate = new Date(Date.now() - 3600 * 1000); // 1 hour ago
+    let asDate = searchCompiler(connection, { since: recentDate });
+    let asString = searchCompiler(connection, { since: recentDate.toISOString() });
+
+    // The string form used to skip the WITHIN shortcut and compile SINCE instead
+    test.ok(hasAttr(asDate, 'YOUNGER'));
+    test.ok(hasAttr(asString, 'YOUNGER'));
+    // The keyword atom is followed by its value token
+    let seconds = attrs => Number(attrs[1].value);
+    // Both are measured against Date.now() at compile time, so allow a small drift
+    test.ok(Math.abs(seconds(asString) - seconds(asDate)) <= 1);
+    test.done();
+};
+
 // ============================================
 // KEYWORD tests
 // ============================================

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);