imapflow 1.0.188 → 1.0.190

package/lib/search-compiler.js

@@ -1,12 +1,28 @@
-'use strict';
+/* eslint no-control-regex:0 */
 
-const { formatDate, formatFlag, canUseFlag } = require('./tools.js');
+'use strict';
 
+const { formatDate, formatFlag, canUseFlag, isDate } = require('./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
+ * @example
+ * setBoolOpt(attributes, 'SEEN', false) // Adds 'UNSEEN'
+ * setBoolOpt(attributes, 'UNSEEN', false) // Adds 'SEEN' (removes UN prefix)
+ */
 let setBoolOpt = (attributes, term, value) => {
     if (!value) {
+        // For falsy values, toggle the UN- prefix
         if (/^un/i.test(term)) {
+            // Remove existing UN prefix
             term = term.slice(2);
         } else {
+            // Add UN prefix
             term = 'UN' + term;
         }
     }
@@ -14,15 +30,26 @@ let setBoolOpt = (attributes, term, value) => {
     attributes.push({ type: 'ATOM', value: term.toUpperCase() });
 };
 
+/**
+ * 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 {string} [type='ATOM'] - The attribute type
+ */
 let setOpt = (attributes, term, value, type) => {
     type = type || 'ATOM';
 
+    // Handle NOT operations for false or null values
     if (value === false || value === null) {
         attributes.push({ type, value: 'NOT' });
     }
 
     attributes.push({ type, value: term.toUpperCase() });
 
+    // Handle array values (e.g., multiple UIDs)
     if (Array.isArray(value)) {
         value.forEach(entry => attributes.push({ type, value: (entry || '').toString() }));
     } else {
@@ -30,6 +57,14 @@ let setOpt = (attributes, term, value, type) => {
     }
 };
 
+/**
+ * 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 {*} value - Date value to format
+ */
 let processDateField = (attributes, term, value) => {
     let date = formatDate(value);
     if (!date) {
@@ -39,35 +74,85 @@ let processDateField = (attributes, term, value) => {
     setOpt(attributes, term, date);
 };
 
+// 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
+ */
 let isUnicodeString = str => {
     if (!str || typeof str !== 'string') {
         return false;
     }
 
-    return Buffer.byteLength(str) !== str.length;
+    // 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 {Object} connection.capabilities - Set of server capabilities
+ * @param {Object} 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
+ * @throws {Error} When required server extensions are not available
+ *
+ * @example
+ * // Simple search for unseen messages from a sender
+ * searchCompiler(connection, {
+ *   unseen: true,
+ *   from: 'sender@example.com'
+ * });
+ *
+ * @example
+ * // Complex OR search with date range
+ * searchCompiler(connection, {
+ *   or: [
+ *     { from: 'alice@example.com' },
+ *     { from: 'bob@example.com' }
+ *   ],
+ *   since: new Date('2024-01-01')
+ * });
+ */
 module.exports.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
+     */
     const walk = params => {
         Object.keys(params || {}).forEach(term => {
             switch (term.toUpperCase()) {
-                case 'SEQ': // custom key for sequence range
+                // Custom sequence range support (non-standard)
+                case 'SEQ':
                     {
                         let value = params[term];
                         if (typeof value === 'number') {
                             value = value.toString();
                         }
+                        // Only accept valid sequence strings (no whitespace)
                         if (typeof value === 'string' && /^\S+$/.test(value)) {
                             attributes.push({ type: 'SEQUENCE', value });
                         }
                     }
                     break;
 
+                // Boolean flags that support UN- prefixing
                 case 'ANSWERED':
                 case 'DELETED':
                 case 'DRAFT':
@@ -82,6 +167,7 @@ module.exports.searchCompiler = (connection, query) => {
                     setBoolOpt(attributes, term, !!params[term]);
                     break;
 
+                // Simple boolean flags without UN- support
                 case 'ALL':
                 case 'NEW':
                 case 'OLD':
@@ -91,6 +177,7 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // Numeric comparisons
                 case 'LARGER':
                 case 'SMALLER':
                 case 'MODSEQ':
@@ -99,6 +186,7 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // Text search fields - check for Unicode
                 case 'BCC':
                 case 'BODY':
                 case 'CC':
@@ -114,28 +202,34 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // UID sequences
                 case 'UID':
                     if (params[term]) {
                         setOpt(attributes, term, params[term], 'SEQUENCE');
                     }
                     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')) {
+                        // 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')) {
+                        // Fallback to Gmail thread ID
                         setOpt(attributes, 'X-GM-THRID', params[term]);
                     }
                     break;
 
+                // Gmail raw search
                 case 'GMRAW':
                 case 'GMAILRAW': // alias for GMRAW
                     if (connection.capabilities.has('X-GM-EXT-1')) {
@@ -150,33 +244,65 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // Date searches with WITHIN extension support
                 case 'BEFORE':
-                case 'ON':
                 case 'SINCE':
+                    {
+                        // Use WITHIN extension for better timezone handling if available
+                        if (connection.capabilities.has('WITHIN') && isDate(params[term])) {
+                            // Convert to seconds ago from now
+                            const now = Date.now();
+                            const withinSeconds = Math.round(Math.max(0, now - params[term].getTime()) / 1000);
+                            let withinKeyword;
+                            switch (term.toUpperCase()) {
+                                case 'BEFORE':
+                                    withinKeyword = 'OLDER';
+                                    break;
+                                case 'SINCE':
+                                    withinKeyword = 'YOUNGER';
+                                    break;
+                            }
+                            setOpt(attributes, withinKeyword, withinSeconds.toString());
+                            break;
+                        }
+
+                        // Fallback to standard date search
+                        processDateField(attributes, term, params[term]);
+                    }
+                    break;
+
+                // Standard date searches
+                case 'ON':
                 case 'SENTBEFORE':
                 case 'SENTON':
                 case 'SENTSINCE':
                     processDateField(attributes, term, params[term]);
                     break;
 
+                // Keyword/flag searches
                 case 'KEYWORD':
                 case 'UNKEYWORD':
                     {
                         let flag = formatFlag(params[term]);
+                        // Only add if flag is supported or already exists in mailbox
                         if (canUseFlag(mailbox, flag) || mailbox.flags.has(flag)) {
                             setOpt(attributes, term, flag);
                         }
                     }
                     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;
                             }
@@ -190,25 +316,29 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // NOT operator
                 case 'NOT':
-                    {   
+                    {
                         if (!params[term]) {
                             break;
                         }
 
                         if (typeof params[term] === 'object') {
                             attributes.push({ type: 'ATOM', value: 'NOT' });
+                            // Recursively process NOT conditions
                             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]) {
                                 walk(params[term][0]);
@@ -216,12 +346,18 @@ module.exports.searchCompiler = (connection, query) => {
                             break;
                         }
 
-                        // OR values has to be grouped by 2
-                        // OR conditional1 conditional2
+                        /**
+                         * 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
+                         */
                         let genOrTree = list => {
                             let group = false;
                             let groups = [];
 
+                            // Group items in pairs
                             list.forEach((entry, i) => {
                                 if (i % 2 === 0) {
                                     group = [entry];
@@ -232,6 +368,7 @@ module.exports.searchCompiler = (connection, query) => {
                                 }
                             });
 
+                            // Handle odd number of items
                             if (group && group.length) {
                                 while (group.length === 1 && Array.isArray(group[0])) {
                                     group = group[0];
@@ -240,10 +377,12 @@ module.exports.searchCompiler = (connection, query) => {
                                 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];
                             }
@@ -251,8 +390,13 @@ module.exports.searchCompiler = (connection, query) => {
                             return groups;
                         };
 
+                        /**
+                         * Walks the OR tree and generates IMAP commands.
+                         * @param {Array|Object} entry - Tree node to process
+                         */
                         let walkOrTree = entry => {
                             if (Array.isArray(entry)) {
+                                // Only add OR for multiple items
                                 if (entry.length > 1) {
                                     attributes.push({ type: 'ATOM', value: 'OR' });
                                 }
@@ -263,6 +407,7 @@ module.exports.searchCompiler = (connection, query) => {
                                 walk(entry);
                             }
                         };
+
                         walkOrTree(genOrTree(params[term]));
                     }
                     break;
@@ -270,10 +415,12 @@ module.exports.searchCompiler = (connection, query) => {
         });
     };
 
+    // 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')) {
-        // Prepend search query with `CHARSET UTF-8`
         attributes.unshift({ type: 'ATOM', value: 'UTF-8' });
         attributes.unshift({ type: 'ATOM', value: 'CHARSET' });
     }

package/lib/tools.js

@@ -754,6 +754,10 @@ const tools = {
         return walk(entry);
     },
 
+    isDate(obj) {
+        return Object.prototype.toString.call(obj) === '[object Date]';
+    },
+
     formatDate(value) {
         if (typeof value === 'string') {
             value = new Date(value);

package/package.json

@@ -1,14 +1,14 @@
 {
     "name": "imapflow",
-    "version": "1.0.188",
+    "version": "1.0.190",
     "description": "IMAP Client for Node",
-    "main": "./lib/imap-flow.js",
+    "main": "lib/imap-flow.js",
+    "types": "lib/imap-flow.d.ts",
     "scripts": {
         "test": "grunt",
         "prepare": "npm run build",
         "docs": "rm -rf docs && mkdir -p docs && jsdoc lib/imap-flow.js -c jsdoc.json -R README.md --destination docs/ && cp assets/favicon.ico docs",
-        "dst": "node types.js",
-        "build": "npm run docs && npm run dst",
+        "build": "npm run docs",
         "st": "npm run docs && st -d docs -i index.html",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
     },
@@ -28,11 +28,11 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.27.5",
+        "@babel/eslint-parser": "7.28.0",
         "@babel/eslint-plugin": "7.27.1",
         "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.27.2",
-        "@types/node": "24.0.1",
+        "@babel/preset-env": "7.28.0",
+        "@types/node": "24.0.12",
         "eslint": "8.57.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "9.1.0",
@@ -43,16 +43,16 @@
         "imapflow-jsdoc-template": "3.4.0-imapflow.2",
         "jsdoc": "3.6.11",
         "st": "3.0.2",
-        "tsd-jsdoc": "2.5.0"
+        "typescript": "5.8.3"
     },
     "dependencies": {
         "encoding-japanese": "2.2.0",
         "iconv-lite": "0.6.3",
         "libbase64": "1.3.0",
-        "libmime": "5.3.6",
+        "libmime": "5.3.7",
         "libqp": "2.1.1",
-        "mailsplit": "5.4.3",
-        "nodemailer": "7.0.3",
+        "mailsplit": "5.4.5",
+        "nodemailer": "7.0.5",
         "pino": "9.7.0",
         "socks": "2.8.5"
     }