imapflow 1.7.8 → 2.0.0

package/{lib → dist/esm}/search-compiler.js

@@ -1,16 +1,12 @@
 /* eslint no-control-regex:0 */
-
-'use strict';
-
-const { formatDate, formatFlag, canUseFlag, toValidDate, isRev2Active } = require('./tools.js');
-
+import { formatDate, formatFlag, canUseFlag, toValidDate, isRev2Active } from './tools.js';
 /**
  * Sets a boolean flag in the IMAP search attributes.
  * Automatically handles UN- prefixing for falsy values.
  *
- * @param {Array} attributes - Array to append the attribute to
- * @param {string} term - The flag name (e.g., 'SEEN', 'DELETED')
- * @param {boolean} value - Whether to set or unset the flag
+ * @param attributes - Array to append the attribute to
+ * @param term - The flag name (e.g., 'SEEN', 'DELETED')
+ * @param value - Whether to set or unset the flag
  * @example
  * setBoolOpt(attributes, 'SEEN', false) // Adds 'UNSEEN'
  * setBoolOpt(attributes, 'UNSEEN', false) // Adds 'SEEN' (removes UN prefix)
@@ -21,114 +17,99 @@ let setBoolOpt = (attributes, term, value) => {
         if (/^un/i.test(term)) {
             // Remove existing UN prefix
             term = term.slice(2);
-        } else {
+        }
+        else {
             // Add UN prefix
             term = 'UN' + term;
         }
     }
-
     attributes.push({ type: 'ATOM', value: term.toUpperCase() });
 };
-
 /**
  * Normalizes a user-supplied sequence set (string, number, bigint, or an array of
  * them) into the single string value of a SEQUENCE token. An array is one
  * comma-joined set: separate tokens would be parsed by the server as extra
  * sequence-number search keys ANDed to the query, not as part of the set.
  *
- * @param {*} value - The sequence set value(s)
- * @returns {string} The joined sequence set string
+ * @param value - The sequence set value(s)
+ * @returns The joined sequence set string
  */
-let toSequenceValue = value => [].concat(value).join(',');
-
+let toSequenceValue = (value) => [].concat(value).join(',');
 /**
  * Adds a search option with its value(s) to the attributes array.
  * Handles NOT operations and array values.
  *
- * @param {Array} attributes - Array to append the attribute to
- * @param {string} term - The search term (e.g., 'FROM', 'SUBJECT')
- * @param {*} value - The value for the search term (string, array, or falsy for NOT)
+ * @param attributes - Array to append the attribute to
+ * @param term - The search term (e.g., 'FROM', 'SUBJECT')
+ * @param value - The value for the search term (string, array, or falsy for NOT)
  */
 let setOpt = (attributes, term, value) => {
     // Handle NOT operations for false or null values
     if (value === false || value === null) {
         attributes.push({ type: 'ATOM', value: 'NOT' });
     }
-
     attributes.push({ type: 'ATOM', value: term.toUpperCase() });
-
     // Handle array values (e.g. HEADER name/value pairs)
     if (Array.isArray(value)) {
         value.forEach(entry => attributes.push({ type: 'ATOM', value: (entry || '').toString() }));
-    } else {
+    }
+    else {
         attributes.push({ type: 'ATOM', value: value.toString() });
     }
 };
-
 /**
  * Processes date fields for IMAP search.
  * Converts JavaScript dates to IMAP date format.
  *
- * @param {Array} attributes - Array to append the attribute to
- * @param {string} term - The date search term (e.g., 'BEFORE', 'SINCE')
- * @param {Date|String} value - Date value to format
+ * @param attributes - Array to append the attribute to
+ * @param term - The date search term (e.g., 'BEFORE', 'SINCE')
+ * @param value - Date value to format
  */
 let processDateField = (attributes, term, value) => {
     // 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) {
+    let date = toValidDate(value);
+    if (!date) {
         return;
     }
-
-    if (['BEFORE', 'SENTBEFORE'].includes(term.toUpperCase()) && value.toISOString().substring(11) !== '00:00:00.000Z') {
+    if (['BEFORE', 'SENTBEFORE'].includes(term.toUpperCase()) && date.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);
+        date = new Date(date.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) {
+    let formatted = formatDate(date);
+    if (!formatted) {
         return;
     }
-
-    setOpt(attributes, term, date);
+    setOpt(attributes, term, formatted);
 };
-
 // Pre-compiled regex for better performance
 const UNICODE_PATTERN = /[^\x00-\x7F]/;
-
 /**
  * Checks if a string contains Unicode characters.
  * Used to determine if CHARSET UTF-8 needs to be specified.
  *
- * @param {*} str - String to check
- * @returns {boolean} True if string contains non-ASCII characters
+ * @param str - String to check
+ * @returns True if string contains non-ASCII characters
  */
-let isUnicodeString = str => {
+let isUnicodeString = (str) => {
     if (!str || typeof str !== 'string') {
         return false;
     }
-
     // Regex test is ~3-5x faster than Buffer.byteLength
     // Matches any character outside ASCII range (0x00-0x7F)
     return UNICODE_PATTERN.test(str);
 };
-
 /**
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
  *
- * @param {Object} connection - IMAP connection object
- * @param {Map} connection.capabilities - Map of server capabilities
- * @param {Set} connection.enabled - Set of enabled extensions
- * @param {Object} connection.mailbox - Current mailbox information
- * @param {Set} connection.mailbox.flags - Available flags in the mailbox
- * @param {Object} query - Search query object
- * @returns {Array} Array of IMAP search attributes
+ * @param connection - IMAP connection object (capabilities, enabled extensions and the current mailbox are read)
+ * @param query - Search query object
+ * @returns Array of IMAP search attributes
  * @throws {Error} When required server extensions are not available
  *
  * @example
@@ -148,29 +129,26 @@ let isUnicodeString = str => {
  *   since: new Date('2024-01-01')
  * });
  */
-module.exports.searchCompiler = (connection, query) => {
+export const searchCompiler = (connection, query) => {
     const attributes = [];
-
     // Track if we need to specify UTF-8 charset
     let hasUnicode = false;
     const mailbox = connection.mailbox;
-
     /**
      * Recursively walks through the query object and builds IMAP attributes.
-     * @param {Object} params - Query parameters to process
+     * @param params - Query parameters to process
      */
-    const walk = params => {
+    const walk = (params) => {
         // Walks a query object and wraps the resulting attributes in a
         // sub-array so the IMAP compiler emits parentheses around them.
         // Used when a single search-key is required (NOT, OR operands)
         // but the condition has multiple keys (RFC 3501 Section 6.4.4).
-        let walkGrouped = obj => {
+        let walkGrouped = (obj) => {
             let startIdx = attributes.length;
             walk(obj);
             let subAttrs = attributes.splice(startIdx);
             attributes.push(subAttrs);
         };
-
         Object.keys(params || {}).forEach(term => {
             switch (term.toUpperCase()) {
                 // Custom sequence range support (non-standard)
@@ -186,7 +164,6 @@ module.exports.searchCompiler = (connection, query) => {
                         }
                     }
                     break;
-
                 // Boolean flags that support UN- prefixing
                 case 'ANSWERED':
                 case 'DELETED':
@@ -201,14 +178,12 @@ module.exports.searchCompiler = (connection, query) => {
                     // toggles UN-prefix for falsy values
                     setBoolOpt(attributes, term, !!params[term]);
                     break;
-
                 // Simple boolean flags without UN- support
                 case 'ALL':
                     if (params[term]) {
                         setBoolOpt(attributes, term, true);
                     }
                     break;
-
                 case 'NEW':
                 case 'OLD':
                 case 'RECENT':
@@ -225,7 +200,6 @@ module.exports.searchCompiler = (connection, query) => {
                         setBoolOpt(attributes, term, true);
                     }
                     break;
-
                 // Numeric comparisons
                 case 'LARGER':
                 case 'SMALLER':
@@ -234,7 +208,6 @@ module.exports.searchCompiler = (connection, query) => {
                         setOpt(attributes, term, params[term]);
                     }
                     break;
-
                 // Text search fields - check for Unicode
                 case 'BCC':
                 case 'BODY':
@@ -250,7 +223,6 @@ module.exports.searchCompiler = (connection, query) => {
                         setOpt(attributes, term, params[term]);
                     }
                     break;
-
                 // UID sequences. The key stays an ATOM and only the value is a
                 // SEQUENCE token, so the compiler validates the sequence set
                 // itself rather than the "UID" keyword in front of it.
@@ -260,27 +232,26 @@ module.exports.searchCompiler = (connection, query) => {
                         attributes.push({ type: 'SEQUENCE', value: toSequenceValue(params[term]) });
                     }
                     break;
-
                 // Email ID support (OBJECTID or Gmail extension)
                 case 'EMAILID':
                     if (connection.capabilities.has('OBJECTID')) {
                         setOpt(attributes, 'EMAILID', params[term]);
-                    } else if (connection.capabilities.has('X-GM-EXT-1')) {
+                    }
+                    else if (connection.capabilities.has('X-GM-EXT-1')) {
                         // Fallback to Gmail message ID
                         setOpt(attributes, 'X-GM-MSGID', params[term]);
                     }
                     break;
-
                 // Thread ID support (OBJECTID or Gmail extension)
                 case 'THREADID':
                     if (connection.capabilities.has('OBJECTID')) {
                         setOpt(attributes, 'THREADID', params[term]);
-                    } else if (connection.capabilities.has('X-GM-EXT-1')) {
+                    }
+                    else if (connection.capabilities.has('X-GM-EXT-1')) {
                         // Fallback to Gmail thread ID
                         setOpt(attributes, 'X-GM-THRID', params[term]);
                     }
                     break;
-
                 // Gmail raw search
                 case 'GMRAW':
                 case 'GMAILRAW': // alias for GMRAW
@@ -289,13 +260,13 @@ module.exports.searchCompiler = (connection, query) => {
                             hasUnicode = true;
                         }
                         setOpt(attributes, 'X-GM-RAW', params[term]);
-                    } else {
+                    }
+                    else {
                         let error = new Error('Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
                         error.code = 'MissingServerExtension';
                         throw error;
                     }
                     break;
-
                 // Gmail label search. Compiles { has, not } into an X-GM-RAW "label:"/"-label:" query
                 // since Gmail labels are not a native IMAP SEARCH key. Gmail-only (X-GM-EXT-1).
                 case 'LABELS': {
@@ -303,16 +274,14 @@ module.exports.searchCompiler = (connection, query) => {
                     if (!labelQuery || typeof labelQuery !== 'object') {
                         break;
                     }
-
                     // Collapse whitespace/quotes and quote multi-word names so they survive as a single token
-                    let formatLabel = name => {
-                        name = (name || '')
+                    let formatLabel = (name) => {
+                        let label = (name || '')
                             .toString()
                             .replace(/[\s"]+/g, ' ')
                             .trim();
-                        return name.indexOf(' ') >= 0 ? `"${name}"` : name;
+                        return label.indexOf(' ') >= 0 ? `"${label}"` : label;
                     };
-
                     let rawParts = [];
                     for (let name of [].concat(labelQuery.has || [])) {
                         if (name) {
@@ -324,18 +293,15 @@ module.exports.searchCompiler = (connection, query) => {
                             rawParts.push(`-label:${formatLabel(name)}`);
                         }
                     }
-
                     // Empty filter is a no-op on any server (do not require the extension)
                     if (!rawParts.length) {
                         break;
                     }
-
                     if (!connection.capabilities.has('X-GM-EXT-1')) {
                         let error = new Error('Server does not support X-GM-EXT-1 extension required for label search');
                         error.code = 'MissingServerExtension';
                         throw error;
                     }
-
                     let rawQuery = rawParts.join(' ');
                     if (isUnicodeString(rawQuery)) {
                         hasUnicode = true;
@@ -343,7 +309,6 @@ module.exports.searchCompiler = (connection, query) => {
                     setOpt(attributes, 'X-GM-RAW', rawQuery);
                     break;
                 }
-
                 // Date searches with WITHIN extension support
                 case 'BEFORE':
                 case 'SINCE':
@@ -354,7 +319,6 @@ module.exports.searchCompiler = (connection, query) => {
                         if (!value) {
                             break;
                         }
-
                         // Use WITHIN extension for better timezone handling if available
                         if (connection.capabilities.has('WITHIN')) {
                             // Convert to seconds ago from now
@@ -364,12 +328,10 @@ module.exports.searchCompiler = (connection, query) => {
                             setOpt(attributes, withinKeyword, withinSeconds.toString());
                             break;
                         }
-
                         // Fallback to standard date search
                         processDateField(attributes, term, value);
                     }
                     break;
-
                 // Standard date searches
                 case 'ON':
                 case 'SENTBEFORE':
@@ -377,7 +339,6 @@ module.exports.searchCompiler = (connection, query) => {
                 case 'SENTSINCE':
                     processDateField(attributes, term, params[term]);
                     break;
-
                 // Keyword/flag searches
                 case 'KEYWORD':
                 case 'UNKEYWORD':
@@ -389,51 +350,44 @@ module.exports.searchCompiler = (connection, query) => {
                         }
                     }
                     break;
-
                 // Header field searches
                 case 'HEADER':
                     if (params[term] && typeof params[term] === 'object') {
                         Object.keys(params[term]).forEach(header => {
                             let value = params[term][header];
-
                             // Allow boolean true to search for header existence
                             if (value === true) {
                                 value = '';
                             }
-
                             // Skip non-string values (after true->'' conversion)
                             if (typeof value !== 'string') {
                                 return;
                             }
-
                             if (isUnicodeString(value)) {
                                 hasUnicode = true;
                             }
-
                             setOpt(attributes, term, [header.toUpperCase().trim(), value]);
                         });
                     }
                     break;
-
                 // NOT operator
                 case 'NOT':
                     if (params[term] && typeof params[term] === 'object') {
                         attributes.push({ type: 'ATOM', value: 'NOT' });
                         if (Object.keys(params[term]).length > 1) {
                             walkGrouped(params[term]);
-                        } else {
+                        }
+                        else {
                             walk(params[term]);
                         }
                     }
                     break;
-
                 // OR operator - complex logic for building OR trees
                 case 'OR':
                     {
                         if (!params[term] || !Array.isArray(params[term]) || !params[term].length) {
                             break;
                         }
-
                         // Single element - just process it directly
                         if (params[term].length === 1) {
                             if (typeof params[term][0] === 'object' && params[term][0]) {
@@ -441,56 +395,49 @@ module.exports.searchCompiler = (connection, query) => {
                             }
                             break;
                         }
-
                         /**
                          * Generates a binary tree structure for OR operations.
                          * IMAP OR takes exactly 2 operands, so we need to nest them.
                          *
-                         * @param {Array} list - List of conditions to OR together
-                         * @returns {Array} Binary tree structure
+                         * @param list - List of conditions to OR together
+                         * @returns Binary tree structure
                          */
-                        let genOrTree = list => {
+                        let genOrTree = (list) => {
                             let group = false;
                             let groups = [];
-
                             // Group items in pairs
                             list.forEach((entry, i) => {
                                 if (i % 2 === 0) {
                                     group = [entry];
-                                } else {
+                                }
+                                else {
                                     group.push(entry);
                                     groups.push(group);
                                     group = false;
                                 }
                             });
-
                             // Handle odd number of items
                             if (group && group.length) {
                                 while (group.length === 1 && Array.isArray(group[0])) {
                                     group = group[0];
                                 }
-
                                 groups.push(group);
                             }
-
                             // Recursively group until we have a binary tree
                             while (groups.length > 2) {
                                 groups = genOrTree(groups);
                             }
-
                             // Flatten single-element arrays
                             while (groups.length === 1 && Array.isArray(groups[0])) {
                                 groups = groups[0];
                             }
-
                             return groups;
                         };
-
                         /**
                          * Walks the OR tree and generates IMAP commands.
-                         * @param {Array|Object} entry - Tree node to process
+                         * @param entry - Tree node to process
                          */
-                        let walkOrTree = entry => {
+                        let walkOrTree = (entry) => {
                             if (Array.isArray(entry)) {
                                 if (entry.length > 1) {
                                     attributes.push({ type: 'ATOM', value: 'OR' });
@@ -501,28 +448,25 @@ module.exports.searchCompiler = (connection, query) => {
                             if (entry && typeof entry === 'object') {
                                 if (Object.keys(entry).length > 1) {
                                     walkGrouped(entry);
-                                } else {
+                                }
+                                else {
                                     walk(entry);
                                 }
                             }
                         };
-
                         walkOrTree(genOrTree(params[term]));
                     }
                     break;
             }
         });
     };
-
     // Process the query
     walk(query);
-
     // If we encountered Unicode strings and UTF-8 is not already accepted,
     // prepend CHARSET UTF-8 to the search command
     if (hasUnicode && !connection.enabled.has('UTF8=ACCEPT')) {
         attributes.unshift({ type: 'ATOM', value: 'UTF-8' });
         attributes.unshift({ type: 'ATOM', value: 'CHARSET' });
     }
-
     return attributes;
 };

package/dist/esm/special-use.d.ts

@@ -0,0 +1,22 @@
+export declare const flags: string[];
+export declare const names: {
+    [flag: string]: string[];
+};
+/**
+ * The parts of a listed folder that special-use detection reads
+ */
+export interface SpecialUseFolder {
+    /** Flags reported for the folder by LIST */
+    flags: Set<string>;
+    /** Folder name, the last path component */
+    name: string;
+}
+/** How a special-use flag was determined */
+export type SpecialUseSource = 'extension' | 'name' | 'name-guess';
+export interface SpecialUseResult {
+    /** The special-use flag, or null when the folder is not a special-use folder */
+    flag: string | null;
+    /** Set when a flag was found */
+    source?: SpecialUseSource | undefined;
+}
+export declare const specialUse: (hasSpecialUseExtension: boolean, folder: SpecialUseFolder) => SpecialUseResult;