imapflow 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.2.3](https://github.com/postalsys/imapflow/compare/v2.2.2...v2.2.3) (2026-10-03)
+
+
+### Bug Fixes
+
+* reject NUL in a non-ASCII search value instead of sending it as a literal ([8c35084](https://github.com/postalsys/imapflow/commit/8c35084f12376a1195989bf99621c2587f548aca))
+* send non-ASCII search values as literals ([b58d93e](https://github.com/postalsys/imapflow/commit/b58d93e49dd37ef008418c2670afaf53b3d78034)), closes [#417](https://github.com/postalsys/imapflow/issues/417)
+
 ## [2.2.2](https://github.com/postalsys/imapflow/compare/v2.2.1...v2.2.2) (2026-10-03)
 
 

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.2";
+export declare const version = "2.2.3";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.2.2";
+exports.version = "2.2.3";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/search-compiler.js

@@ -3,6 +3,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchCompiler = void 0;
 const tools_js_1 = require("./tools.js");
+// Matches any character outside the ASCII range
+const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
  * Sets a boolean flag in the IMAP search attributes.
  * Automatically handles UN- prefixing for falsy values.
@@ -38,6 +40,17 @@ let setBoolOpt = (attributes, term, value) => {
  * @returns The joined sequence set string
  */
 let toSequenceValue = (value) => [].concat(value).join(',');
+/**
+ * Builds the token for a search value. A quoted string may only carry 7-bit
+ * characters (RFC 3501 section 9), so a non-ASCII value is sent as a literal;
+ * strict servers reply BAD to UTF-8 inside a quoted string. A literal can not
+ * carry NUL either (CHAR8 is %x01-ff), so such a value stays an ATOM and the
+ * compiler rejects it.
+ *
+ * @param value - The search value
+ * @returns An ATOM token (quoted by the compiler when needed), or a LITERAL token
+ */
+let toSearchValue = (value) => UNICODE_PATTERN.test(value) && !value.includes('\0') ? { type: 'LITERAL', value: Buffer.from(value) } : { type: 'ATOM', value };
 /**
  * Adds a search option with its value(s) to the attributes array.
  * Handles NOT operations and array values.
@@ -54,10 +67,10 @@ let setOpt = (attributes, term, value) => {
     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() }));
+        value.forEach(entry => attributes.push(toSearchValue((entry || '').toString())));
     }
     else {
-        attributes.push({ type: 'ATOM', value: value.toString() });
+        attributes.push(toSearchValue(value.toString()));
     }
 };
 /**
@@ -89,8 +102,6 @@ let processDateField = (attributes, term, value) => {
     }
     setOpt(attributes, term, formatted);
 };
-// Pre-compiled regex for better performance
-const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
  * Throws a coded search compilation error.
  *
@@ -103,20 +114,13 @@ let fail = (code, message) => {
     throw error;
 };
 /**
- * Checks if a string contains Unicode characters.
- * Used to determine if CHARSET UTF-8 needs to be specified.
+ * Checks whether any search value was compiled into a literal, which only
+ * happens for non-ASCII values and means CHARSET UTF-8 needs to be specified.
  *
- * @param str - String to check
- * @returns True if string contains non-ASCII characters
+ * @param attributes - Compiled search attributes
+ * @returns True if a LITERAL token is present
  */
-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);
-};
+let hasLiteral = (attributes) => attributes.some(attr => (Array.isArray(attr) ? hasLiteral(attr) : attr.type === 'LITERAL'));
 /**
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
@@ -145,8 +149,6 @@ let isUnicodeString = (str) => {
  */
 const searchCompiler = (connection, query) => {
     const attributes = [];
-    // Track if we need to specify UTF-8 charset
-    let hasUnicode = false;
     /**
      * Recursively walks through the query object and builds IMAP attributes.
      * @param params - Query parameters to process
@@ -236,9 +238,6 @@ const searchCompiler = (connection, query) => {
                 case 'SUBJECT':
                 case 'TEXT':
                 case 'TO':
-                    if (isUnicodeString(params[term])) {
-                        hasUnicode = true;
-                    }
                     if (params[term]) {
                         setOpt(attributes, term, params[term]);
                     }
@@ -286,9 +285,6 @@ const searchCompiler = (connection, query) => {
                 case 'GMRAW':
                 case 'GMAILRAW': // alias for GMRAW
                     if (connection.capabilities.has('X-GM-EXT-1')) {
-                        if (isUnicodeString(params[term])) {
-                            hasUnicode = true;
-                        }
                         setOpt(attributes, 'X-GM-RAW', params[term]);
                     }
                     else {
@@ -329,9 +325,6 @@ const searchCompiler = (connection, query) => {
                         fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for label search');
                     }
                     let rawQuery = rawParts.join(' ');
-                    if (isUnicodeString(rawQuery)) {
-                        hasUnicode = true;
-                    }
                     setOpt(attributes, 'X-GM-RAW', rawQuery);
                     break;
                 }
@@ -391,9 +384,6 @@ const searchCompiler = (connection, query) => {
                             if (typeof value !== 'string') {
                                 return;
                             }
-                            if (isUnicodeString(value)) {
-                                hasUnicode = true;
-                            }
                             setOpt(attributes, term, [header.toUpperCase().trim(), value]);
                         });
                     }
@@ -473,7 +463,7 @@ const searchCompiler = (connection, 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')) {
+    if (!connection.enabled.has('UTF8=ACCEPT') && hasLiteral(attributes)) {
         attributes.unshift({ type: 'ATOM', value: 'UTF-8' });
         attributes.unshift({ type: 'ATOM', value: 'CHARSET' });
     }

package/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.2";
+export declare const version = "2.2.3";
 export declare const homepage = "https://imapflow.com/";

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.2.2";
+export const version = "2.2.3";
 export const homepage = "https://imapflow.com/";

package/dist/esm/search-compiler.js

@@ -1,5 +1,7 @@
 /* eslint no-control-regex:0 */
 import { formatDate, formatFlag, toValidDate, isRev2Active } from './tools.js';
+// Matches any character outside the ASCII range
+const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
  * Sets a boolean flag in the IMAP search attributes.
  * Automatically handles UN- prefixing for falsy values.
@@ -35,6 +37,17 @@ let setBoolOpt = (attributes, term, value) => {
  * @returns The joined sequence set string
  */
 let toSequenceValue = (value) => [].concat(value).join(',');
+/**
+ * Builds the token for a search value. A quoted string may only carry 7-bit
+ * characters (RFC 3501 section 9), so a non-ASCII value is sent as a literal;
+ * strict servers reply BAD to UTF-8 inside a quoted string. A literal can not
+ * carry NUL either (CHAR8 is %x01-ff), so such a value stays an ATOM and the
+ * compiler rejects it.
+ *
+ * @param value - The search value
+ * @returns An ATOM token (quoted by the compiler when needed), or a LITERAL token
+ */
+let toSearchValue = (value) => UNICODE_PATTERN.test(value) && !value.includes('\0') ? { type: 'LITERAL', value: Buffer.from(value) } : { type: 'ATOM', value };
 /**
  * Adds a search option with its value(s) to the attributes array.
  * Handles NOT operations and array values.
@@ -51,10 +64,10 @@ let setOpt = (attributes, term, value) => {
     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() }));
+        value.forEach(entry => attributes.push(toSearchValue((entry || '').toString())));
     }
     else {
-        attributes.push({ type: 'ATOM', value: value.toString() });
+        attributes.push(toSearchValue(value.toString()));
     }
 };
 /**
@@ -86,8 +99,6 @@ let processDateField = (attributes, term, value) => {
     }
     setOpt(attributes, term, formatted);
 };
-// Pre-compiled regex for better performance
-const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
  * Throws a coded search compilation error.
  *
@@ -100,20 +111,13 @@ let fail = (code, message) => {
     throw error;
 };
 /**
- * Checks if a string contains Unicode characters.
- * Used to determine if CHARSET UTF-8 needs to be specified.
+ * Checks whether any search value was compiled into a literal, which only
+ * happens for non-ASCII values and means CHARSET UTF-8 needs to be specified.
  *
- * @param str - String to check
- * @returns True if string contains non-ASCII characters
+ * @param attributes - Compiled search attributes
+ * @returns True if a LITERAL token is present
  */
-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);
-};
+let hasLiteral = (attributes) => attributes.some(attr => (Array.isArray(attr) ? hasLiteral(attr) : attr.type === 'LITERAL'));
 /**
  * Compiles a JavaScript object query into IMAP search command attributes.
  * Supports standard IMAP search criteria and extensions like OBJECTID and Gmail extensions.
@@ -142,8 +146,6 @@ let isUnicodeString = (str) => {
  */
 export const searchCompiler = (connection, query) => {
     const attributes = [];
-    // Track if we need to specify UTF-8 charset
-    let hasUnicode = false;
     /**
      * Recursively walks through the query object and builds IMAP attributes.
      * @param params - Query parameters to process
@@ -233,9 +235,6 @@ export const searchCompiler = (connection, query) => {
                 case 'SUBJECT':
                 case 'TEXT':
                 case 'TO':
-                    if (isUnicodeString(params[term])) {
-                        hasUnicode = true;
-                    }
                     if (params[term]) {
                         setOpt(attributes, term, params[term]);
                     }
@@ -283,9 +282,6 @@ export const searchCompiler = (connection, query) => {
                 case 'GMRAW':
                 case 'GMAILRAW': // alias for GMRAW
                     if (connection.capabilities.has('X-GM-EXT-1')) {
-                        if (isUnicodeString(params[term])) {
-                            hasUnicode = true;
-                        }
                         setOpt(attributes, 'X-GM-RAW', params[term]);
                     }
                     else {
@@ -326,9 +322,6 @@ export const searchCompiler = (connection, query) => {
                         fail('MissingServerExtension', 'Server does not support X-GM-EXT-1 extension required for label search');
                     }
                     let rawQuery = rawParts.join(' ');
-                    if (isUnicodeString(rawQuery)) {
-                        hasUnicode = true;
-                    }
                     setOpt(attributes, 'X-GM-RAW', rawQuery);
                     break;
                 }
@@ -388,9 +381,6 @@ export const searchCompiler = (connection, query) => {
                             if (typeof value !== 'string') {
                                 return;
                             }
-                            if (isUnicodeString(value)) {
-                                hasUnicode = true;
-                            }
                             setOpt(attributes, term, [header.toUpperCase().trim(), value]);
                         });
                     }
@@ -470,7 +460,7 @@ export const searchCompiler = (connection, 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')) {
+    if (!connection.enabled.has('UTF8=ACCEPT') && hasLiteral(attributes)) {
         attributes.unshift({ type: 'ATOM', value: 'UTF-8' });
         attributes.unshift({ type: 'ATOM', value: 'CHARSET' });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.2",
+    "version": "2.2.3",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",