imapflow 1.7.8 → 2.0.1

package/{lib → dist/esm}/commands/status-fields.js

@@ -1,7 +1,4 @@
-'use strict';
-
-const { parseBigIntValue, parseUintValue, MAX_UINT32_DIGITS } = require('../tools.js');
-
+import { parseBigIntValue, parseUintValue, MAX_UINT32_DIGITS } from '../tools.js';
 // STATUS data items (RFC 3501 section 6.3.10, RFC 7162 for HIGHESTMODSEQ, RFC 9051 for SIZE
 // and DELETED) mapped to the property name each one is exposed under, together with the
 // parser that turns the raw response token into a usable value. Shared by the STATUS command
@@ -12,8 +9,7 @@ const { parseBigIntValue, parseUintValue, MAX_UINT32_DIGITS } = require('../tool
 // mailbox state, where a NaN or a value coerced to Infinity corrupts every later range
 // computation. A plain isNaN() test is not enough: it passes '1e5', ' 12 ' and 'Infinity',
 // and BigInt() throws on all three, aborting the walk over the remaining fields.
-const uint32 = value => parseUintValue(value, MAX_UINT32_DIGITS);
-
+const uint32 = (value) => parseUintValue(value, MAX_UINT32_DIGITS);
 const STATUS_FIELDS = {
     MESSAGES: { key: 'messages', parser: uint32 },
     RECENT: { key: 'recent', parser: uint32 },
@@ -28,41 +24,34 @@ const STATUS_FIELDS = {
     SIZE: { key: 'size', parser: value => parseUintValue(value) },
     DELETED: { key: 'deleted', parser: uint32 }
 };
-
 /**
  * Walks a STATUS data-item list - alternating item-name and item-value tokens - and reports
  * every recognized field that parsed successfully. Unknown item names and unusable values are
  * skipped, so one bad field never costs the rest of the response.
  *
- * @param {Array} list - Parsed attribute list from the untagged STATUS response.
- * @param {Function} onField - Called as (key, value) for each usable field.
+ * @param list - Parsed attribute list from the untagged STATUS response.
+ * @param onField - Called as (key, value) for each usable field.
  */
-const parseStatusList = (list, onField) => {
+export const parseStatusList = (list, onField) => {
     let name;
     list.forEach((entry, i) => {
         if (i % 2 === 0) {
             name = entry && typeof entry.value === 'string' ? entry.value : false;
             return;
         }
-
         if (!name || !entry) {
             return;
         }
-
         // The item name is server-controlled, but uppercasing it before the lookup means no
         // Object.prototype member can be reached: every builtin name has a lowercase letter.
         const field = STATUS_FIELDS[name.toUpperCase()];
         if (!field) {
             return;
         }
-
         const value = field.parser(entry.value);
         if (value === false) {
             return;
         }
-
         onField(field.key, value);
     });
 };
-
-module.exports = { parseStatusList };

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

@@ -0,0 +1,12 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { StatusObject, StatusQuery } from '../types.js';
+/**
+ * Requests status information about a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query
+ * @param query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
+ * @returns Status information object, or false if preconditions not met or on failure
+ * @throws {Error} If the mailbox does not exist
+ */
+export default function status(connection: ImapFlow, path: string | string[], query: StatusQuery | undefined): Promise<StatusObject | false>;

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

@@ -1,15 +1,13 @@
-'use strict';
-
-const { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active } = require('../tools.js');
-const { parseStatusList } = require('./status-fields.js');
-
+import { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active } from '../tools.js';
+import { parseStatusList } from './status-fields.js';
 // STATUS fields that also refresh the live mailbox state when the queried mailbox is the
 // currently selected one. Keyed by the output property name parseStatusList() reports.
 const MAILBOX_UPDATERS = {
     messages: (value, connection, path) => {
-        let prevCount = connection.mailbox.exists;
+        let mailbox = connection.mailbox;
+        let prevCount = mailbox.exists;
         if (prevCount !== value) {
-            connection.mailbox.exists = value;
+            mailbox.exists = value;
             connection.emit('exists', { path, count: value, prevCount });
         }
     },
@@ -20,45 +18,37 @@ const MAILBOX_UPDATERS = {
         connection.mailbox.highestModseq = value;
     }
 };
-
 /**
  * Requests status information about a mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Mailbox path to query
- * @param {Object} query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
- * @returns {Promise<{path: string, messages?: number, recent?: number, uidNext?: number, uidValidity?: BigInt, unseen?: number, highestModseq?: BigInt}|boolean>} Status information object, or false if preconditions not met or on failure
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query
+ * @param query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
+ * @returns Status information object, or false if preconditions not met or on failure
  * @throws {Error} If the mailbox does not exist
  */
-module.exports = async (connection, path, query) => {
+export default async function status(connection, path, query) {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !path) {
         // nothing to do here
         return false;
     }
-
     path = normalizePath(connection, path);
     let encodedPath = encodePath(connection, path);
-
     // Use quoted STRING if the encoded path contains '&' (modified UTF-7 marker),
     // otherwise use unquoted ATOM. Same approach as in SELECT.
     let attributes = [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }];
-
     // Build the list of STATUS data items the caller wants
     let queryAttributes = buildStatusQueryAttributes(connection, query);
-
     // RECENT does not exist in IMAP4rev2 so it is never requested from a rev2
     // session; its defined value there is always 0. Synthesizing it keeps the
     // return shape identical to a rev1 session for the same query.
     let syntheticRecent = query && query.recent && isRev2Active(connection);
-
     if (!queryAttributes.length) {
         // A query that only contained items unavailable on this session - the
         // caller still gets a status object if every such item has a defined value
         return syntheticRecent ? { path, recent: 0 } : false;
     }
-
     attributes.push(queryAttributes);
-
     let response;
     try {
         let map = { path };
@@ -66,20 +56,19 @@ module.exports = async (connection, path, query) => {
             untagged: {
                 // STATUS response: * STATUS <mailbox> (<key> <value> <key> <value> ...)
                 // Parsed as alternating key-value pairs (i % 2 pattern).
-                STATUS: async untagged => {
+                STATUS: async (untagged) => {
                     // If querying the currently selected mailbox, also update the
                     // connection's live mailbox state and emit events for changes.
                     let updateCurrent = connection.state === connection.states.SELECTED && path === connection.mailbox.path;
-
                     let list = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
                     if (!list) {
                         return;
                     }
                     parseStatusList(list, (key, value) => {
                         map[key] = value;
-
-                        if (updateCurrent && MAILBOX_UPDATERS[key]) {
-                            MAILBOX_UPDATERS[key](value, connection, path);
+                        let updater = MAILBOX_UPDATERS[key];
+                        if (updateCurrent && updater) {
+                            updater(value, connection, path);
                         }
                     });
                 }
@@ -90,9 +79,10 @@ module.exports = async (connection, path, query) => {
             map.recent = 0;
         }
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         // A NO response usually means the mailbox doesn't exist. Verify by
-        // running LIST -- if no results, throw a clear NotFound error instead
+        // running LIST: if no results, throw a clear NotFound error instead
         // of the generic IMAP error.
         // Note: this uses run(), so when STATUS was dispatched by fallback polling through
         // runInternal() the LIST awaits that polling session's own preCheck and cancels it.
@@ -107,8 +97,7 @@ module.exports = async (connection, path, query) => {
                 throw error;
             }
         }
-
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

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

@@ -0,0 +1,19 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { StoreOptions } from '../types.js';
+/**
+ * Options for the STORE command
+ */
+export interface StoreCommandOptions extends StoreOptions {
+    /** Operation type: 'set', 'add', or 'remove' */
+    operation?: string | undefined;
+}
+/**
+ * Updates flags or labels for messages in the selected mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param flags - Flag(s) to set, add, or remove
+ * @param options - Store options
+ * @returns True on success, false on failure or if nothing to do
+ */
+export default function store(connection: ImapFlow, range: string, flags: string | string[], options: StoreCommandOptions): Promise<boolean>;

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

@@ -1,43 +1,32 @@
-'use strict';
-
-const { formatFlag, canUseFlag, enhanceCommandError } = require('../tools.js');
-
+import { formatFlag, canUseFlag, enhanceCommandError } from '../tools.js';
 /**
  * Updates flags or labels for messages in the selected mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} range - Message sequence number or UID range
- * @param {string|string[]} flags - Flag(s) to set, add, or remove
- * @param {Object} options - Store options
- * @param {boolean} [options.uid] - If true, use UID STORE instead of STORE
- * @param {boolean} [options.useLabels] - If true, operate on Gmail labels instead of flags
- * @param {boolean} [options.silent] - If true, use .SILENT variant to suppress server response
- * @param {string} [options.operation] - Operation type: 'set', 'add', or 'remove'
- * @param {string} [options.unchangedSince] - Only update messages not changed since this modseq value
- * @returns {Promise<boolean>} True on success, false on failure or if nothing to do
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param flags - Flag(s) to set, add, or remove
+ * @param options - Store options
+ * @returns True on success, false on failure or if nothing to do
  */
-module.exports = async (connection, range, flags, options) => {
+export default async function store(connection, range, flags, options) {
     if (connection.state !== connection.states.SELECTED || !range || (options.useLabels && !connection.capabilities.has('X-GM-EXT-1'))) {
         // nothing to do here
         return false;
     }
-
     /* c8 ignore next */ // options.useLabels is dereferenced in the guard above, so options is always defined here
     options = options || {};
-
     // Build the IMAP STORE operation name. The format is:
     //   [+|-]FLAGS[.SILENT] or [+|-]X-GM-LABELS
     // Where: no prefix = replace all, + = add, - = remove
     // .SILENT suppresses the server from sending back updated flags (saves bandwidth).
     let operation = 'FLAGS';
-
     if (options.useLabels) {
         // Gmail labels (X-GM-EXT-1 extension): operates on labels instead of IMAP flags
         operation = 'X-GM-LABELS';
-    } else if (options.silent) {
+    }
+    else if (options.silent) {
         operation = `${operation}.SILENT`;
     }
-
     // Prefix determines the operation: none = set (replace), + = add, - = remove
     switch ((options.operation || '').toLowerCase()) {
         case 'set':
@@ -50,29 +39,27 @@ module.exports = async (connection, range, flags, options) => {
             operation = `+${operation}`;
             break;
     }
-
     // Validate each flag: format it (normalize backslash prefix for system flags),
     // then check if the mailbox's permanentFlags allow it. Removal is always allowed
     // since it doesn't require the flag to be in permanentFlags.
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
-            flag = formatFlag(flag);
-
-            if (!canUseFlag(connection.mailbox, flag) && options.operation !== 'remove') {
-                return false;
-            }
-
-            return flag;
-        })
-        .filter(flag => flag);
-
+        let formatted = formatFlag(flag);
+        if (!canUseFlag(connection.mailbox, formatted) && options.operation !== 'remove') {
+            return false;
+        }
+        return formatted;
+    })
+        .filter((flag) => !!flag);
     // Allow empty flags only for 'set' operation (which clears all flags)
     if (!flags.length && options.operation !== 'set') {
         return false;
     }
-
-    let attributes = [{ type: 'SEQUENCE', value: range }, { type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag }))];
-
+    let attributes = [
+        { type: 'SEQUENCE', value: range },
+        { type: 'ATOM', value: operation },
+        flags.map(flag => ({ type: 'ATOM', value: flag }))
+    ];
     // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
     // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
     if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !connection.mailbox.noModseq) {
@@ -87,15 +74,15 @@ module.exports = async (connection, range, flags, options) => {
             }
         ]);
     }
-
     let response;
     try {
         response = await connection.exec(options.uid ? 'UID STORE' : 'STORE', attributes);
         response.next();
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

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

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Subscribes to a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to subscribe to
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+export default function subscribe(connection: ImapFlow, path: string | string[]): Promise<boolean | undefined>;

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

@@ -1,30 +1,26 @@
-'use strict';
-
-const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
-
+import { encodePath, normalizePath, enhanceCommandError } from '../tools.js';
 /**
  * Subscribes to a mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Mailbox path to subscribe to
- * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to subscribe to
+ * @returns True on success, false on failure, or undefined if preconditions not met
  */
-module.exports = async (connection, path) => {
+export default async function subscribe(connection, path) {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
         return;
     }
-
     path = normalizePath(connection, path);
-
     let response;
     try {
         response = await connection.exec('SUBSCRIBE', [{ type: 'ATOM', value: encodePath(connection, path) }]);
         response.next();
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

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

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Unsubscribes from a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to unsubscribe from
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+export default function unsubscribe(connection: ImapFlow, path: string | string[]): Promise<boolean | undefined>;

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

@@ -1,30 +1,26 @@
-'use strict';
-
-const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
-
+import { encodePath, normalizePath, enhanceCommandError } from '../tools.js';
 /**
  * Unsubscribes from a mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Mailbox path to unsubscribe from
- * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to unsubscribe from
+ * @returns True on success, false on failure, or undefined if preconditions not met
  */
-module.exports = async (connection, path) => {
+export default async function unsubscribe(connection, path) {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
         return;
     }
-
     path = normalizePath(connection, path);
-
     let response;
     try {
         response = await connection.exec('UNSUBSCRIBE', [{ type: 'ATOM', value: encodePath(connection, path) }]);
         response.next();
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

package/dist/esm/connection-deadline.d.ts

@@ -0,0 +1,49 @@
+import type { ImapFlowError } from './errors.js';
+export declare const CONNECT_TIMEOUT: number;
+/**
+ * One deadline for an entire connection attempt.
+ *
+ * DNS resolution, proxy negotiation and the transport handshake all draw from the same budget, so
+ * a phase that stalls cannot extend the documented `connectionTimeout`. Every expiry - whether it
+ * comes from this deadline or is normalized from a dependency - is reported with the same
+ * `CONNECT_TIMEOUT` error shape, so callers do not need to know which phase was blocked.
+ */
+export declare class ConnectionDeadline {
+    timeout: number;
+    startedAt: number;
+    /**
+     * @param timeout Configured connection timeout in milliseconds. Normalized once
+     *   here; 0 and any other falsy or invalid value fall back to the 90 second default.
+     */
+    constructor(timeout?: number | string | undefined);
+    /**
+     * @returns Milliseconds left in the budget, never negative.
+     */
+    remaining(): number;
+    /**
+     * @returns The shared `CONNECT_TIMEOUT` error.
+     */
+    error(): ImapFlowError;
+    /**
+     * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one
+     * timeout error whichever layer noticed first. The original error is kept as `_err`. Anything
+     * that is not a timeout is returned unchanged.
+     *
+     * @param err Error raised by a dependency during a connection phase.
+     * @returns Either the normalized timeout error or the original error.
+     */
+    normalize<T extends ImapFlowError | null | undefined>(err: T): T | ImapFlowError;
+    /**
+     * Throws before a phase is started if the budget is already used up, so no work is begun
+     * that could only ever time out.
+     */
+    check(): void;
+    /**
+     * Races a phase against the remaining budget. The timer is always cleared, so a completed
+     * phase never leaves a pending timer behind.
+     *
+     * @param promise Phase to run under the deadline.
+     * @returns Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
+     */
+    race<T>(promise: Promise<T>): Promise<T>;
+}

package/{lib → dist/esm}/connection-deadline.js

@@ -1,8 +1,6 @@
-'use strict';
-
+import { clearTimer } from './tools.js';
 // Default upper bound for establishing a usable transport, including DNS and proxy negotiation.
-const CONNECT_TIMEOUT = 90 * 1000;
-
+export const CONNECT_TIMEOUT = 90 * 1000;
 /**
  * One deadline for an entire connection attempt.
  *
@@ -11,25 +9,23 @@ const CONNECT_TIMEOUT = 90 * 1000;
  * comes from this deadline or is normalized from a dependency - is reported with the same
  * `CONNECT_TIMEOUT` error shape, so callers do not need to know which phase was blocked.
  */
-class ConnectionDeadline {
+export class ConnectionDeadline {
     /**
-     * @param {Number} [timeout] Configured connection timeout in milliseconds. Normalized once
+     * @param timeout Configured connection timeout in milliseconds. Normalized once
      *   here; 0 and any other falsy or invalid value fall back to the 90 second default.
      */
     constructor(timeout) {
         this.timeout = Number(timeout) || CONNECT_TIMEOUT;
         this.startedAt = Date.now();
     }
-
     /**
-     * @returns {Number} Milliseconds left in the budget, never negative.
+     * @returns Milliseconds left in the budget, never negative.
      */
     remaining() {
         return Math.max(0, this.timeout - (Date.now() - this.startedAt));
     }
-
     /**
-     * @returns {Error} The shared `CONNECT_TIMEOUT` error.
+     * @returns The shared `CONNECT_TIMEOUT` error.
      */
     error() {
         let err = new Error('Failed to establish connection in required time');
@@ -37,30 +33,26 @@ class ConnectionDeadline {
         err.details = { connectionTimeout: this.timeout };
         return err;
     }
-
     /**
      * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one
      * timeout error whichever layer noticed first. The original error is kept as `_err`. Anything
      * that is not a timeout is returned unchanged.
      *
-     * @param {Error} err Error raised by a dependency during a connection phase.
-     * @returns {Error} Either the normalized timeout error or the original error.
+     * @param err Error raised by a dependency during a connection phase.
+     * @returns Either the normalized timeout error or the original error.
      */
     normalize(err) {
         if (!err || err.code === 'CONNECT_TIMEOUT') {
             return err;
         }
-
         // The `socks` client reports its own expiry as "Proxy connection timed out"
         if (err.code !== 'ETIMEDOUT' && !/timed out/i.test(err.message || '')) {
             return err;
         }
-
         let normalized = this.error();
         normalized._err = err;
         return normalized;
     }
-
     /**
      * Throws before a phase is started if the budget is already used up, so no work is begun
      * that could only ever time out.
@@ -70,29 +62,26 @@ class ConnectionDeadline {
             throw this.error();
         }
     }
-
     /**
      * Races a phase against the remaining budget. The timer is always cleared, so a completed
      * phase never leaves a pending timer behind.
      *
-     * @param {Promise} promise Phase to run under the deadline.
-     * @returns {Promise<*>} Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
+     * @param promise Phase to run under the deadline.
+     * @returns Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
      */
     async race(promise) {
         this.check();
-
         let timer = null;
         try {
             return await Promise.race([
                 promise,
-                new Promise((resolve, reject) => {
+                new Promise((_resolve, reject) => {
                     timer = setTimeout(() => reject(this.error()), this.remaining());
                 })
             ]);
-        } finally {
-            clearTimeout(timer);
+        }
+        finally {
+            clearTimer(timer);
         }
     }
 }
-
-module.exports = { ConnectionDeadline, CONNECT_TIMEOUT };