imapflow 1.7.8 → 2.0.0

package/{lib → dist/esm}/commands/idle.js

@@ -1,9 +1,5 @@
-'use strict';
-
-const { guardedPromise, hasCapability, logConnectionError, restampConnectionError, unrefTimer } = require('../tools.js');
-
+import { guardedPromise, hasCapability, logConnectionError, restampConnectionError, unrefTimer, clearTimer } from '../tools.js';
 const NOOP_INTERVAL = 2 * 60 * 1000;
-
 /**
  * Marks the connection as idling on behalf of one session and returns a release function.
  *
@@ -11,14 +7,13 @@ const NOOP_INTERVAL = 2 * 60 * 1000;
  * finishes late (a poll that completes after cancellation, an IDLE that unwinds after a restart)
  * cannot clear the flag of the session that has since taken over.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Function} Release function, safe to call more than once
+ * @param connection - IMAP connection instance
+ * @returns Release function, safe to call more than once
  */
 function claimIdling(connection) {
     let token = {};
     connection._idleSession = token;
     connection.idling = true;
-
     return () => {
         if (connection._idleSession === token) {
             connection._idleSession = null;
@@ -26,25 +21,21 @@ function claimIdling(connection) {
         }
     };
 }
-
 /**
  * Runs a single IDLE session on the connection.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Promise<void|boolean>} Void on success, false on failure
+ * @param connection - IMAP connection instance
+ * @returns Void on success, false on failure
  */
 async function runIdle(connection) {
     let response;
-
     // Queue of promises waiting for IDLE to break. When another command needs to run,
     // it calls connection.preCheck() which queues a promise here and sends DONE to break IDLE.
     let preCheckWaitQueue = [];
-
     // The preCheck function this session owns. Only this session may clear it from the
     // connection, so a newer IDLE session that already installed its own is left alone.
     let ownPreCheck = null;
     let releaseIdling = claimIdling(connection);
-
     try {
         // State flags for the IDLE lifecycle:
         // - doneRequested: someone wants to break IDLE (e.g., to run another command)
@@ -53,7 +44,6 @@ async function runIdle(connection) {
         let doneRequested = false;
         let doneSent = false;
         let canEnd = false;
-
         // preCheck sends DONE to break out of IDLE. Called when another command
         // needs to run on this connection (e.g., a FETCH or STORE from user code).
         let preCheck = async () => {
@@ -63,25 +53,22 @@ async function runIdle(connection) {
                     src: 'c',
                     msg: `DONE`,
                     comment: `breaking IDLE`,
-                    lockId: connection.currentLock?.lockId,
+                    lockId: connection.currentLock ? connection.currentLock.lockId : undefined,
                     path: connection.mailbox && connection.mailbox.path,
                     cid: connection.id
                 });
                 connection.write('DONE');
                 doneSent = true;
-
                 releaseIdling();
                 if (connection.preCheck === ownPreCheck) {
                     connection.preCheck = false; // unset itself
                 }
-
                 while (preCheckWaitQueue.length) {
                     let { resolve } = preCheckWaitQueue.shift();
                     resolve();
                 }
             }
         };
-
         // Public interface for breaking IDLE. Returns a promise that resolves when
         // IDLE is actually broken and the connection is free for other commands.
         let connectionPreCheck = () => {
@@ -90,10 +77,9 @@ async function runIdle(connection) {
             let handler = guardedPromise((resolve, reject) => {
                 preCheckWaitQueue.push({ resolve, reject });
             });
-
             connection.log.trace({
                 msg: 'Requesting IDLE break',
-                lockId: connection.currentLock?.lockId,
+                lockId: connection.currentLock ? connection.currentLock.lockId : undefined,
                 path: connection.mailbox && connection.mailbox.path,
                 queued: preCheckWaitQueue.length,
                 doneRequested,
@@ -101,16 +87,12 @@ async function runIdle(connection) {
                 doneSent,
                 cid: connection.id
             });
-
-            preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE', err));
-
+            preCheck().catch((err) => logConnectionError(connection, 'Failed to break IDLE', err));
             return handler;
         };
-
         // Register preCheck on the connection so other code (e.g., getMailboxLock) can break IDLE
         ownPreCheck = connectionPreCheck;
         connection.preCheck = connectionPreCheck;
-
         response = await connection.exec('IDLE', false, {
             // Server responds with "+" continuation to acknowledge IDLE mode.
             // After this, the server will push untagged responses for mailbox changes.
@@ -118,7 +100,7 @@ async function runIdle(connection) {
             onPlusTag: async () => {
                 connection.log.debug({
                     msg: `Initiated IDLE, waiting for server input`,
-                    lockId: connection.currentLock?.lockId,
+                    lockId: connection.currentLock ? connection.currentLock.lockId : undefined,
                     doneRequested,
                     cid: connection.id
                 });
@@ -126,17 +108,18 @@ async function runIdle(connection) {
                 if (doneRequested) {
                     try {
                         await preCheck();
-                    } catch (err) {
+                    }
+                    catch (err) {
                         logConnectionError(connection, 'Failed to break IDLE', err);
                     }
                 }
             },
-            onSend: () => {}
+            onSend: () => { }
         });
-
         response.next();
         return;
-    } catch (err) {
+    }
+    catch (err) {
         logConnectionError(connection, 'IDLE session failed', err);
         if (preCheckWaitQueue.length) {
             // One error for the whole queue: every waiter failed at the same site, for the same
@@ -149,7 +132,8 @@ async function runIdle(connection) {
             }
         }
         return false;
-    } finally {
+    }
+    finally {
         // Single ownership cleanup for every outcome: explicit break, tagged completion
         // (including a server-terminated IDLE, where preCheck never ran), rejected command,
         // parser failure and connection close. `idling` drives socket-timeout handling, so it
@@ -164,7 +148,6 @@ async function runIdle(connection) {
         }
     }
 }
-
 /**
  * Runs one fallback poll. The real SELECT and STATUS commands are reused instead of replaying the
  * saved wire arguments, so a poll applies exactly the same mailbox state transitions, events and
@@ -172,19 +155,16 @@ async function runIdle(connection) {
  * than connection.run(), because run() awaits preCheck() - and the preCheck it would await is the
  * one this very polling session installed, so the session would cancel itself.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {Object} session - Polling session state
- * @returns {Promise<void>}
+ * @param connection - IMAP connection instance
+ * @param session - Polling session state
  */
 async function pollOnce(connection, session) {
     let path = connection.mailbox && connection.mailbox.path;
-
     switch (connection.missingIdleCommand) {
         case 'SELECT':
             connection.log.debug({ msg: `Running SELECT to detect changes in folder`, cid: connection.id });
             await connection.runInternal('SELECT', path, { readOnly: session.selectCommand.command === 'EXAMINE' });
             break;
-
         case 'STATUS': {
             connection.log.debug({ msg: `Running STATUS to detect changes in folder`, cid: connection.id });
             // HIGHESTMODSEQ is filtered out again unless the server advertises CONDSTORE, so a
@@ -204,7 +184,6 @@ async function pollOnce(connection, session) {
             }
             break;
         }
-
         case 'NOOP':
         default: {
             let response = await connection.exec('NOOP', false, { comment: 'IDLE not supported' });
@@ -213,7 +192,6 @@ async function pollOnce(connection, session) {
         }
     }
 }
-
 /**
  * Polls the selected mailbox at a fixed interval, for servers without IDLE support.
  *
@@ -221,25 +199,21 @@ async function pollOnce(connection, session) {
  * a poll starts and again before the next timer is scheduled, and a poll that completes after
  * cancellation can neither run again nor take ownership away from a newer IDLE session.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {number} [maxIdleTime] - Upper bound for the polling interval
- * @returns {Promise<void>}
+ * @param connection - IMAP connection instance
+ * @param maxIdleTime - Upper bound for the polling interval
  */
 async function runPollingFallback(connection, maxIdleTime) {
     if (!connection.currentSelectCommand) {
         return;
     }
-
     let session = {
         cancelled: false,
         timer: null,
         preCheck: null,
         selectCommand: connection.currentSelectCommand
     };
-
     let interval = maxIdleTime ? Math.min(NOOP_INTERVAL, maxIdleTime) : NOOP_INTERVAL;
     let releaseIdling = claimIdling(connection);
-
     try {
         await new Promise(resolve => {
             // Idempotent cancellation. Never keyed off connection.preCheck, because a newer IDLE
@@ -249,54 +223,47 @@ async function runPollingFallback(connection, maxIdleTime) {
                     return;
                 }
                 session.cancelled = true;
-                clearTimeout(session.timer);
+                clearTimer(session.timer);
                 session.timer = null;
                 resolve();
             };
-
             session.preCheck = async () => {
                 connection.log.debug({ msg: `Breaking NOOP loop`, cid: connection.id });
                 cancel();
             };
             connection.preCheck = session.preCheck;
-
             const runPoll = () => {
                 if (session.cancelled) {
                     return;
                 }
-
                 // The transport or the mailbox may be gone by the time the timer fires
                 if (!connection.socket || connection.socket.destroyed || connection.state !== connection.states.SELECTED || !connection.mailbox) {
                     return cancel();
                 }
-
                 pollOnce(connection, session)
                     .then(() => {
-                        // Stamped only after a poll actually completed: a failed poll must not
-                        // satisfy the resumed schedule below, or the next session would defer
-                        // its first poll a full interval past an attempt that checked nothing.
-                        connection._lastPollAt = Date.now();
-                        // Cancellation is re-checked here: the session may have been broken while
-                        // this poll was in flight, and an orphaned poller must not schedule again.
-                        if (session.cancelled) {
-                            return;
-                        }
-                        scheduleNextPoll(interval);
-                    })
-                    .catch(err => {
-                        logConnectionError(connection, 'Failed to poll for mailbox changes', err);
-                        cancel();
-                    });
+                    // Stamped only after a poll actually completed: a failed poll must not
+                    // satisfy the resumed schedule below, or the next session would defer
+                    // its first poll a full interval past an attempt that checked nothing.
+                    connection._lastPollAt = Date.now();
+                    // Cancellation is re-checked here: the session may have been broken while
+                    // this poll was in flight, and an orphaned poller must not schedule again.
+                    if (session.cancelled) {
+                        return;
+                    }
+                    scheduleNextPoll(interval);
+                })
+                    .catch((err) => {
+                    logConnectionError(connection, 'Failed to poll for mailbox changes', err);
+                    cancel();
+                });
             };
-
             function scheduleNextPoll(delay) {
                 session.timer = setTimeout(runPoll, delay);
                 // Background polling must not keep the process alive
                 unrefTimer(session.timer);
             }
-
             connection.log.debug({ msg: `Initiated NOOP loop`, cid: connection.id });
-
             // Every auto-IDLE restart begins a fresh polling session, so an unconditional first
             // poll would tie the poll rate to how often the caller runs commands rather than to
             // `interval`: with a short autoIdleDelay, a command every few seconds turns into a
@@ -308,13 +275,15 @@ async function runPollingFallback(connection, maxIdleTime) {
             let sinceLastPoll = Math.max(0, Date.now() - (connection._lastPollAt || 0));
             if (sinceLastPoll >= interval) {
                 runPoll();
-            } else {
+            }
+            else {
                 scheduleNextPoll(interval - sinceLastPoll);
             }
         });
-    } finally {
+    }
+    finally {
         session.cancelled = true;
-        clearTimeout(session.timer);
+        clearTimer(session.timer);
         session.timer = null;
         releaseIdling();
         if (connection.preCheck === session.preCheck) {
@@ -322,20 +291,18 @@ async function runPollingFallback(connection, maxIdleTime) {
         }
     }
 }
-
 /**
  * Listens for changes in the selected mailbox using IDLE or NOOP polling fallback.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {number} [maxIdleTime] - Maximum time in milliseconds to stay in IDLE before restarting
- * @returns {Promise<void|boolean|undefined>} Void on success, false on failure, or undefined if not in SELECTED state
+ * @param connection - IMAP connection instance
+ * @param maxIdleTime - Maximum time in milliseconds to stay in IDLE before restarting
+ * @returns Void on success, false on failure, or undefined if not in SELECTED state
  */
-module.exports = async (connection, maxIdleTime) => {
+export default async function idle(connection, maxIdleTime) {
     if (connection.state !== connection.states.SELECTED) {
         // nothing to do here
         return;
     }
-
     // If server supports IDLE (RFC 2177, folded into base IMAP4rev2), use it for
     // real-time push notifications. Otherwise, fall back to periodic polling with
     // NOOP/STATUS/SELECT.
@@ -354,7 +321,7 @@ module.exports = async (connection, maxIdleTime) => {
                             stillIdling = true;
                             // request IDLE break if IDLE has been running for allowed time
                             connection.log.trace({ msg: 'Max allowed IDLE time reached', cid: connection.id });
-                            connection.preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE for restart', err));
+                            connection.preCheck().catch((err) => logConnectionError(connection, 'Failed to break IDLE for restart', err));
                         }
                     }
                 }, maxIdleTime);
@@ -369,8 +336,7 @@ module.exports = async (connection, maxIdleTime) => {
             stillIdling = false;
         }
     }
-
     // Fallback for servers without IDLE support: poll at regular intervals using
     // NOOP (default), STATUS, or SELECT depending on missingIdleCommand config.
     return runPollingFallback(connection, maxIdleTime);
-};
+}

package/dist/esm/commands/list.d.ts

@@ -0,0 +1,16 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { ListOptions, ListResponse } from '../types.js';
+/**
+ * Lists mailboxes from the server, including subscription status and special-use flags.
+ *
+ * @param connection - IMAP connection instance
+ * @param reference - Reference name (namespace prefix)
+ * @param mailbox - Mailbox name pattern with possible wildcards
+ * @param options - List options
+ * @param options.listOnly - If true, return entries after LIST without LSUB or status queries
+ * @param options.statusQuery - Status data items to query for each listed mailbox
+ * @param options.specialUseHints - Hints mapping mailbox paths to special-use types (sent, junk, trash, drafts, archive)
+ * @returns Array of mailbox entries sorted by special-use flags and name
+ * @throws If the LIST command fails
+ */
+export default function list(connection: ImapFlow, reference: string | undefined, mailbox: string | undefined, options?: ListOptions | undefined): Promise<ListResponse[]>;