imapflow 1.7.8 → 2.0.1

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

@@ -1,138 +1,42 @@
-'use strict';
-
-const {
-    enhanceCommandError,
-    hasCapability,
-    isValidSequenceValue,
-    parseBigIntValue,
-    parseUintValue,
-    MAX_UINT32_DIGITS,
-    EXPANDED_RANGE_LIMIT
-} = require('../tools.js');
-const { searchCompiler } = require('../search-compiler.js');
-
+import { enhanceCommandError, hasCapability, isValidSequenceValue, EXPANDED_RANGE_LIMIT } from '../tools.js';
+import { searchCompiler } from '../search-compiler.js';
+import { parseEsearchResponse } from './esearch-parser.js';
 /**
  * Strips the leading (TAG "X") correlator list and the optional UID atom from an
  * ESEARCH untagged response, leaving only the result keyword/value pairs.
  * The IMAP parser represents parenthesized groups as plain Arrays, not objects
  * with type: 'LIST'.
  *
- * @param {Array} attrs - Raw attribute array from the IMAP parser
- * @returns {Array} Attribute array starting at the first result keyword
+ * @param attrs - Raw attribute array from the IMAP parser
+ * @returns Attribute array starting at the first result keyword
  */
-const stripEsearchPrefix = attrs => {
+const stripEsearchPrefix = (attrs) => {
     let start = 0;
-    if (attrs[start] && Array.isArray(attrs[start])) start++;
-    if (attrs[start] && typeof attrs[start].value === 'string' && attrs[start].value.toUpperCase() === 'UID') start++;
+    if (attrs[start] && Array.isArray(attrs[start]))
+        start++;
+    if (attrs[start] && typeof attrs[start].value === 'string' && attrs[start].value.toUpperCase() === 'UID')
+        start++;
     return attrs.slice(start);
 };
-
-/**
- * Parses the key-value attributes from an ESEARCH untagged response.
- *
- * Receives the attribute list AFTER stripping the leading (TAG "X") list
- * and the UID atom — i.e. only the result keyword/value pairs remain.
- *
- * ALL and PARTIAL.messages are kept as compact sequence-set strings.
- * Use expandRange() from tools.js if you need to expand them.
- * MODSEQ (RFC 7162, sent when the search used a MODSEQ criterion) is
- * returned as a BigInt.
- *
- * @param {Array} attrs - Attribute array from the IMAP parser
- * @returns {Object} ESearchResult object
- */
-function parseEsearchResponse(attrs) {
-    const result = {};
-    let i = 0;
-    while (i < attrs.length) {
-        const token = attrs[i];
-        if (!token || token.type !== 'ATOM') {
-            i++;
-            continue;
-        }
-        const key = token.value.toUpperCase();
-        if (i + 1 >= attrs.length) {
-            i++;
-            continue;
-        }
-        switch (key) {
-            // COUNT is a plain message count; MIN and MAX are sequence numbers or UIDs. All
-            // three are bounded decimal runs - isNaN() would also admit '1e400' (Infinity)
-            case 'COUNT': {
-                const n = parseUintValue(attrs[++i]?.value, MAX_UINT32_DIGITS);
-                if (n !== false) result.count = n;
-                break;
-            }
-            case 'MIN': {
-                const n = parseUintValue(attrs[++i]?.value, MAX_UINT32_DIGITS);
-                if (n !== false) result.min = n;
-                break;
-            }
-            case 'MAX': {
-                const n = parseUintValue(attrs[++i]?.value, MAX_UINT32_DIGITS);
-                if (n !== false) result.max = n;
-                break;
-            }
-            case 'MODSEQ': {
-                // RFC 7162 section 3.1.5: present when the SEARCH used a MODSEQ
-                // criterion on a CONDSTORE-enabled session. BigInt because
-                // mod-sequence values are unsigned 63-bit
-                const modseq = parseBigIntValue(attrs[++i]?.value);
-                if (modseq !== false) result.modseq = modseq;
-                break;
-            }
-            case 'ALL': {
-                const allToken = attrs[++i];
-                if (allToken && typeof allToken.value === 'string') {
-                    result.all = allToken.value;
-                }
-                break;
-            }
-            case 'PARTIAL': {
-                const listToken = attrs[++i];
-                const items = Array.isArray(listToken) ? listToken : null;
-                if (!items || items.length < 2) break;
-                result.partial = {
-                    range: items[0].value,
-                    messages: items[1].value
-                };
-                break;
-            }
-            default:
-                // Skip the value token for unknown keys to keep the stream aligned.
-                // The loop's unconditional i++ at the bottom advances past the key;
-                // this extra i++ advances past the value token.
-                i++;
-                break;
-        }
-        i++;
-    }
-    return result;
-}
-
 /**
  * Searches for messages matching the specified criteria.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {Object|boolean} query - Search query object, or true/empty object to match all messages
- * @param {Object} [options] - Search options
- * @param {boolean} [options.uid] - If true, use UID SEARCH instead of SEARCH
- * @param {Array} [options.returnOptions] - ESEARCH RETURN options. When present AND the
+ * @param connection - IMAP connection instance
+ * @param query - Search query object, or true/empty object to match all messages
+ * @param options - Search options
+ * @param options.uid - If true, use UID SEARCH instead of SEARCH
+ * @param options.returnOptions - ESEARCH RETURN options. When present AND the
  *   server advertises ESEARCH capability, triggers ESEARCH and returns an ESearchResult.
  *   Items are strings ('MIN','MAX','COUNT','ALL') or objects ({ partial: '1:100' }).
  *   When server lacks ESEARCH, falls back to plain SEARCH and returns number[].
- * @returns {Promise<number[]|Object|boolean>}
  */
-module.exports = async (connection, query, options) => {
+export default async function search(connection, query, options) {
     if (connection.state !== connection.states.SELECTED) {
         // nothing to do here
         return false;
     }
-
     options = options || {};
-
     let attributes;
-
     // Three query branches:
     // 1. Empty/truthy/all-only query -> use IMAP "SEARCH ALL" to match every message
     // 2. Non-empty object -> compile into IMAP SEARCH criteria via searchCompiler
@@ -140,67 +44,67 @@ module.exports = async (connection, query, options) => {
     if (!query || query === true || (typeof query === 'object' && (!Object.keys(query).length || (Object.keys(query).length === 1 && query.all)))) {
         // search for all messages
         attributes = [{ type: 'ATOM', value: 'ALL' }];
-    } else if (query && typeof query === 'object') {
+    }
+    else if (query && typeof query === 'object') {
         // normal query
         attributes = searchCompiler(connection, query);
-    } else {
+    }
+    else {
         return false;
     }
-
     // ESEARCH is part of base IMAP4rev2
     const useEsearch = options.returnOptions && options.returnOptions.length > 0 && hasCapability(connection, 'ESEARCH');
-
     if (useEsearch) {
         // Build RETURN (...) item list
         const returnItems = [];
         for (const opt of options.returnOptions) {
             if (typeof opt === 'string') {
                 returnItems.push({ type: 'ATOM', value: opt.toUpperCase() });
-            } else if (opt && typeof opt.partial === 'string') {
+            }
+            else if (opt && typeof opt.partial === 'string') {
                 // RFC 9394: PARTIAL is an atom followed by the range atom, both inside RETURN (...)
                 returnItems.push({ type: 'ATOM', value: 'PARTIAL' });
                 returnItems.push({ type: 'ATOM', value: opt.partial });
             }
         }
-
         // If all returnOptions entries were invalid (e.g. objects lacking a string
         // `partial` field), returnItems would be empty. Emitting "RETURN ()" is
         // technically valid per RFC 4731 but returns nothing useful. Fall through
         // to the legacy SEARCH path instead so the caller gets a usable result.
         if (returnItems.length > 0) {
             const returnClause = [{ type: 'ATOM', value: 'RETURN' }, returnItems];
-
             let esearchResult = {};
             let response;
             try {
                 response = await connection.exec(options.uid ? 'UID SEARCH' : 'SEARCH', [...returnClause, ...attributes], {
                     untagged: {
-                        ESEARCH: async untagged => {
-                            if (!untagged || !untagged.attributes) return;
+                        ESEARCH: async (untagged) => {
+                            if (!untagged || !untagged.attributes)
+                                return;
                             esearchResult = parseEsearchResponse(stripEsearchPrefix(untagged.attributes));
                         }
                     }
                 });
                 response.next();
                 return esearchResult;
-            } catch (err) {
+            }
+            catch (err) {
                 await enhanceCommandError(err);
                 connection.log.warn({ err, cid: connection.id });
                 return false;
             }
         }
-        // returnItems was empty — fall through to legacy SEARCH path below
+        // returnItems was empty - fall through to legacy SEARCH path below
     }
-
-    // ── Legacy SEARCH path (no returnOptions, or server lacks ESEARCH) ────
-    // Use a Set to deduplicate sequence numbers/UIDs -- servers may return
+    // Legacy SEARCH path (no returnOptions, or server lacks ESEARCH)
+    // Use a Set to deduplicate sequence numbers/UIDs - servers may return
     // duplicates across multiple untagged SEARCH responses.
     let results = new Set();
     let response;
     try {
         response = await connection.exec(options.uid ? 'UID SEARCH' : 'SEARCH', attributes, {
             untagged: {
-                SEARCH: async untagged => {
+                SEARCH: async (untagged) => {
                     if (untagged && untagged.attributes && untagged.attributes.length) {
                         let truncated = false;
                         let discarded = false;
@@ -235,11 +139,10 @@ module.exports = async (connection, query, options) => {
                         }
                     }
                 },
-
                 // IMAP4rev2 servers answer even a plain SEARCH with an untagged
                 // ESEARCH response (RFC 9051 deprecated the SEARCH response), so
                 // both forms are collected into the same result set
-                ESEARCH: async untagged => {
+                ESEARCH: async (untagged) => {
                     if (!untagged || !untagged.attributes) {
                         return;
                     }
@@ -263,7 +166,7 @@ module.exports = async (connection, query, options) => {
                         // absolute ceiling expandRange() uses - a hostile server cannot
                         // bypass it by inflating EXISTS first
                         let overBudget = () => results.size >= existsCount() || results.size >= EXPANDED_RANGE_LIMIT;
-                        let resolveId = part => (part === '*' ? (options.uid ? 0 : existsCount()) : Number(part));
+                        let resolveId = (part) => (part === '*' ? (options.uid ? 0 : existsCount()) : Number(part));
                         let truncated = false;
                         let discarded = false;
                         sequenceSetLoop: for (let part of parsed.all.split(',')) {
@@ -311,12 +214,10 @@ module.exports = async (connection, query, options) => {
         response.next();
         // Sort numerically for consistent, predictable output order
         return Array.from(results).sort((a, b) => a - b);
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
-
-// Exported for unit testing — not intended as public library API
-module.exports.parseEsearchResponse = parseEsearchResponse;
+}

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

@@ -0,0 +1,25 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MailboxObject, MailboxOpenOptions } from '../types.js';
+/**
+ * Options for SELECT/EXAMINE: the public open options plus the QRESYNC resynchronization
+ * parameters, which are only honored when the QRESYNC extension has been enabled
+ */
+export interface SelectOptions extends MailboxOpenOptions {
+    /** QRESYNC modseq value to fetch changes since */
+    changedSince?: bigint | number | string | undefined;
+    /** QRESYNC UID validity value */
+    uidValidity?: bigint | number | string | undefined;
+}
+/**
+ * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to select
+ * @param options - Select options
+ * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
+ * @param options.changedSince - QRESYNC modseq value to fetch changes since
+ * @param options.uidValidity - QRESYNC UID validity value
+ * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
+ * @throws If the SELECT/EXAMINE command fails
+ */
+export default function select(connection: ImapFlow, pathInput: string | string[], options?: SelectOptions | undefined): Promise<MailboxObject | undefined>;

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

@@ -1,7 +1,4 @@
-'use strict';
-
-const { encodePath, normalizePath, enhanceCommandError, parseBigIntValue, parseUintValue, getStringList, MAX_UINT32_DIGITS } = require('../tools.js');
-
+import { encodePath, normalizePath, enhanceCommandError, parseBigIntValue, parseUintValue, getStringList, MAX_UINT32_DIGITS } from '../tools.js';
 // Response codes carrying a value that SELECT/EXAMINE may write to the mailbox object, keyed by
 // the lowercased code, mapped to the fixed public property name and the parser for the value.
 // Every parser returns false for a value it cannot use, and the field is then left unset.
@@ -18,62 +15,53 @@ const VALUED_RESPONSE_CODES = Object.assign(Object.create(null), {
     // A value that is not a bounded digit run is dropped rather than stored raw: every consumer
     // compares highestModseq relationally, and a relational compare against a non-numeric string
     // is false in both directions, so the value could never advance and delta sync would stop.
-    highestmodseq: { key: 'highestModseq', parse: value => parseBigIntValue(value) },
-
+    highestmodseq: { key: 'highestModseq', parse: (value) => parseBigIntValue(value) },
     // Unique identifier validity. If this changes between sessions, all previously cached UIDs
     // are invalid and the client must re-sync from scratch. Nominally 32-bit, but stored as a
     // BigInt precisely so a server that exceeds that still round-trips, hence the wider bound.
-    uidvalidity: { key: 'uidValidity', parse: value => parseBigIntValue(value) },
-
+    uidvalidity: { key: 'uidValidity', parse: (value) => parseBigIntValue(value) },
     // The next UID to be assigned in this mailbox, useful for detecting new arrivals. A huge
     // digit run would coerce to Infinity and corrupt every later UID range computation.
-    uidnext: { key: 'uidNext', parse: value => parseUintValue(value, MAX_UINT32_DIGITS) },
-
+    uidnext: { key: 'uidNext', parse: (value) => parseUintValue(value, MAX_UINT32_DIGITS) },
     // Sequence number of the first unseen message (RFC 3501 section 7.1). Not a count of unseen
     // messages - use mailboxStatus() with {unseen: true} for that.
-    unseen: { key: 'unseen', parse: value => parseUintValue(value, MAX_UINT32_DIGITS) },
-
+    unseen: { key: 'unseen', parse: (value) => parseUintValue(value, MAX_UINT32_DIGITS) },
     // APPENDLIMIT (RFC 7889): largest message size in octets the server accepts for APPEND into
     // this mailbox. Spelled all lowercase, unlike the camelCase fields around it, because that is
     // the name this object has always exposed.
-    appendlimit: { key: 'appendlimit', parse: value => parseUintValue(value) },
-
+    appendlimit: { key: 'appendlimit', parse: (value) => parseUintValue(value) },
     // OBJECTID (RFC 8474): server-assigned mailbox identifier that survives renames. Sent as a
     // parenthesized list, but servers in the wild send it bare too.
     mailboxid: {
         key: 'mailboxId',
-        parse: value => (Array.isArray(value) ? value.length > 0 && value[0] : typeof value === 'string' && value)
+        parse: (value) => (Array.isArray(value) ? value.length > 0 && value[0] : typeof value === 'string' && value)
     },
-
     // Flags the client may change permanently on messages in this mailbox, including \* if the
     // server allows custom flags. Only the parenthesized form carries flags, and a malformed
     // value must leave permanentFlags unset rather than set an empty Set: canUseFlag() reads
     // unset as permissive and empty as deny-all, so an empty Set would turn every later flag
     // update into a silent no-op for the rest of the session.
-    permanentflags: { key: 'permanentFlags', parse: value => Array.isArray(value) && new Set(value) }
+    permanentflags: { key: 'permanentFlags', parse: (value) => Array.isArray(value) && new Set(value) }
 });
-
 /**
  * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Mailbox path to select
- * @param {Object} [options] - Select options
- * @param {boolean} [options.readOnly] - If true, use EXAMINE instead of SELECT (read-only access)
- * @param {string} [options.changedSince] - QRESYNC modseq value to fetch changes since
- * @param {BigInt} [options.uidValidity] - QRESYNC UID validity value
- * @returns {Promise<Object|undefined>} Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
- * @throws {Error} If the SELECT/EXAMINE command fails
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to select
+ * @param options - Select options
+ * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
+ * @param options.changedSince - QRESYNC modseq value to fetch changes since
+ * @param options.uidValidity - QRESYNC UID validity value
+ * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
+ * @throws If the SELECT/EXAMINE command fails
  */
-module.exports = async (connection, path, options) => {
+export default async function select(connection, pathInput, options) {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
         return;
     }
     options = options || {};
-
-    path = normalizePath(connection, path);
-
+    let path = normalizePath(connection, pathInput);
     // Ensure we have folder metadata (delimiter, flags, specialUse) by running LIST if needed.
     // This is cached in connection.folders to avoid repeated LIST calls.
     // Note: this uses run() rather than runInternal(), so it terminates a running IDLE first,
@@ -90,9 +78,7 @@ module.exports = async (connection, path, options) => {
             connection.folders.set(folder.path, folder);
         });
     }
-
     let folderListData = connection.folders.has(path) ? connection.folders.get(path) : false;
-
     let response;
     try {
         let map = { path };
@@ -103,7 +89,6 @@ module.exports = async (connection, path, options) => {
                 }
             });
         }
-
         // QRESYNC (RFC 7162): allows efficient mailbox resynchronization by sending
         // the last known UIDVALIDITY and HIGHESTMODSEQ. Server responds with only
         // the changes (new flags, expunged UIDs) since that point.
@@ -118,9 +103,7 @@ module.exports = async (connection, path, options) => {
             ]);
             map.qresync = true;
         }
-
         let encodedPath = encodePath(connection, path);
-
         // SELECT opens the mailbox read-write; EXAMINE opens it read-only.
         // Path encoding: if the encoded path contains '&' (UTF-7 encoding marker),
         // send as quoted STRING to avoid parser issues with the ampersand.
@@ -129,7 +112,6 @@ module.exports = async (connection, path, options) => {
             /* c8 ignore next */ // extraArgs is always initialised to an array, so the [] fallback is unreachable
             arguments: [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || [])
         };
-
         response = await connection.exec(selectCommand.command, selectCommand.arguments, {
             untagged: {
                 // Untagged OK responses carry response codes in brackets, e.g.:
@@ -137,7 +119,7 @@ module.exports = async (connection, path, options) => {
                 // * OK [PERMANENTFLAGS (\Seen \Answered \*)] Flags permitted
                 // The section array holds the parsed bracket contents: section[0] is the
                 // key (e.g., "UIDVALIDITY"), section[1] is the value or list.
-                OK: async untagged => {
+                OK: async (untagged) => {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
                     }
@@ -146,16 +128,15 @@ module.exports = async (connection, path, options) => {
                     if (section && section.length > 1 && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
                         let key = section[0].value.toLowerCase();
                         let value;
-
                         // Value can be a single string or a list of strings (e.g., PERMANENTFLAGS).
                         // section[1] can be a parsed NIL (null), and so can any element inside a
                         // parenthesized list, so both levels need the guard
                         if (section[1] && typeof section[1].value === 'string') {
                             value = section[1].value;
-                        } else if (Array.isArray(section[1])) {
+                        }
+                        else if (Array.isArray(section[1])) {
                             value = getStringList(section[1]);
                         }
-
                         let field = VALUED_RESPONSE_CODES[key];
                         if (field) {
                             let parsed = field.parse(value);
@@ -164,52 +145,49 @@ module.exports = async (connection, path, options) => {
                             }
                         }
                     }
-
                     // Handle response codes with only a keyword (no value), e.g., [NOMODSEQ].
                     // NOMODSEQ means the mailbox does not support mod-sequences, so the
                     // CONDSTORE/QRESYNC features are unavailable for it.
-                    if (section && section.length === 1 && section[0] && section[0].type === 'ATOM' && section[0].value?.toUpperCase() === 'NOMODSEQ') {
+                    if (section &&
+                        section.length === 1 &&
+                        section[0] &&
+                        section[0].type === 'ATOM' &&
+                        section[0].value?.toUpperCase() === 'NOMODSEQ') {
                         map.noModseq = true;
                     }
                 },
-
                 // Untagged FLAGS response lists all flags defined for this mailbox
                 // (both system flags and custom flags). Example: * FLAGS (\Seen \Answered \Flagged)
-                FLAGS: async untagged => {
+                FLAGS: async (untagged) => {
                     if (!untagged.attributes || !untagged.attributes.length || !Array.isArray(untagged.attributes[0])) {
                         return;
                     }
                     map.flags = new Set(getStringList(untagged.attributes[0]));
                 },
-
                 // Untagged EXISTS response: "* <count> EXISTS" tells us the total number
                 // of messages in the mailbox. The count is in the command field (numeric prefix).
-                EXISTS: async untagged => {
+                EXISTS: async (untagged) => {
                     // Not a usable count: anything but a bounded digit run. A long digit run
                     // coerces to Infinity, which would corrupt every later range computation
                     let num = parseUintValue(untagged.command, MAX_UINT32_DIGITS);
                     if (num === false) {
                         return false;
                     }
-
                     map.exists = num;
                 },
-
                 // VANISHED responses (QRESYNC): server reports UIDs that have been expunged
                 // since the client's last known state. Only received when QRESYNC was requested.
                 // A dummy mailbox object is passed because the mailbox isn't officially open yet.
-                VANISHED: async untagged => {
+                VANISHED: async (untagged) => {
                     await connection.untaggedVanished(untagged, { path, uidNext: false, uidValidity: false });
                 },
-
                 // Untagged FETCH during SELECT/EXAMINE: only occurs with QRESYNC, delivering
                 // updated flags for messages that changed since the client's last modseq.
-                FETCH: async untagged => {
+                FETCH: async (untagged) => {
                     await connection.untaggedFetch(untagged, { path, uidNext: false, uidValidity: false });
                 }
             }
         });
-
         // The tagged OK response to SELECT/EXAMINE includes [READ-ONLY] or [READ-WRITE]
         // in its response code, indicating the access mode the server granted. A tagged OK
         // with no resp-text has no `attributes` property at all, and unlike the untagged
@@ -220,7 +198,6 @@ module.exports = async (connection, path, options) => {
         if (section && section.length && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
             map.readOnly = section[0].value.toUpperCase() === 'READ-ONLY';
         }
-
         // Validate QRESYNC preconditions (RFC 7162 Section 3.2.5):
         // QRESYNC results are only valid if UIDVALIDITY matches, HIGHESTMODSEQ is
         // present, and the mailbox supports mod-sequences. If any condition fails,
@@ -228,49 +205,41 @@ module.exports = async (connection, path, options) => {
         if (map.qresync && (options.uidValidity !== map.uidValidity || !map.highestModseq || map.noModseq)) {
             map.qresync = false;
         }
-
         // Transition mailbox state: save previous mailbox reference, temporarily
         // clear it, then emit events and set the new mailbox.
         let currentMailbox = connection.mailbox;
         connection.mailbox = false;
-
         // Emit mailboxClose if we're switching from a different mailbox.
         // Re-selecting the same mailbox (e.g., for resync) does not trigger close/open.
         if (currentMailbox && currentMailbox.path !== path) {
             connection.emit('mailboxClose', currentMailbox);
         }
-
         connection.mailbox = map;
         // Save the SELECT command for potential re-use (e.g., NOOP fallback polling
         // re-issues the SELECT to detect changes on servers without IDLE support).
         connection.currentSelectCommand = selectCommand;
         connection.state = connection.states.SELECTED;
-
         if (!currentMailbox || currentMailbox.path !== path) {
             connection.emit('mailboxOpen', connection.mailbox);
         }
-
         response.next();
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
-
         // If SELECT/EXAMINE fails while a mailbox was already selected, we must
         // reset to AUTHENTICATED state since the server has implicitly deselected
         // the previous mailbox on failure (RFC 3501 Section 6.3.1).
         if (connection.state === connection.states.SELECTED) {
             let currentMailbox = connection.mailbox;
-
             connection.mailbox = false;
             connection.currentSelectCommand = false;
             connection.state = connection.states.AUTHENTICATED;
-
             if (currentMailbox) {
                 connection.emit('mailboxClose', currentMailbox);
             }
         }
-
         connection.log.warn({ err, cid: connection.id });
         throw err;
     }
-};
+}

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

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Initiates STARTTLS connection upgrade.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True if STARTTLS was initiated, false if not supported or already secure
+ */
+export default function starttls(connection: ImapFlow): Promise<boolean>;

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

@@ -1,17 +1,14 @@
-'use strict';
-
 /**
  * Initiates STARTTLS connection upgrade.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Promise<boolean>} True if STARTTLS was initiated, false if not supported or already secure
+ * @param connection - IMAP connection instance
+ * @returns True if STARTTLS was initiated, false if not supported or already secure
  */
-module.exports = async connection => {
+export default async function starttls(connection) {
     if (!connection.capabilities.has('STARTTLS') || connection.secureConnection) {
         // nothing to do here
         return false;
     }
-
     let response;
     try {
         response = await connection.exec('STARTTLS');
@@ -20,8 +17,9 @@ module.exports = async connection => {
         connection._starttlsHadTrailingData = !!(response && response.hasTrailingData);
         response.next();
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

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

@@ -0,0 +1,14 @@
+import type { ImapAttributeList } from '../handler/types.js';
+/**
+ * A parsed STATUS value: counts and sizes as numbers, UIDVALIDITY and HIGHESTMODSEQ as BigInts
+ */
+export type StatusFieldValue = number | bigint;
+/**
+ * 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 list - Parsed attribute list from the untagged STATUS response.
+ * @param onField - Called as (key, value) for each usable field.
+ */
+export declare const parseStatusList: (list: ImapAttributeList, onField: (key: string, value: StatusFieldValue) => void) => void;